SAP - ABAP RESTful Application Programming - 2302

Developer Guide | PUBLIC
2023-03-27
SAP - ABAP RESTful Application Programming

Model
© 2023 SAP SE or an SAP affiliate company. All rights reserved.
THE BEST RUN

Content
1 ABAP RESTful Application Programming Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2 Learn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.1 Data Modeling and Behavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
2.2 Runtime Frameworks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
2.3 Business Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Business Object Implementation Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
RAP BO Provisioning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
RAP BO Best Practices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
RAP BO Runtime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Entity Manipulation Language (EML). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
2.4 Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
Query Implementation Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Query Capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Unmanaged Query API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
3 Start. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
3.1 Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Naming Conventions for Development Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
ABAP Flight Reference Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
3.2 Downloading the ABAP Flight Reference Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314
3.3 Developing an OData Service for Simple List Reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Defining the Data Model with CDS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Creating an OData Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Designing the User Interface for a Fiori Elements App. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
3.4 Generating a RAP Business Service with the Generate ABAP Repository Objects Wizard. . . . . . . . . 339
Example: RAP Business Service Generation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
4 Develop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
4.1 Development Constraints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
4.2 Develop Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Developing Read-Only List Reporting Apps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .350
Developing Managed Transactional Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
Developing Unmanaged Transactional Apps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
Developing Transactional Apps with Draft Capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
Developing Transactional Apps with Multi-Inline-Edit Capabilities. . . . . . . . . . . . . . . . . . . . . . . 693
 Cloud Developing a UI Service with Access to a Remote Service. . . . . . . . . . . . . . . . . . . . . . 714
SAP - ABAP RESTful Application Programming Model

2 PUBLIC Content
4.3 Develop Web APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Publishing a Web API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767
4.4 Develop APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
Projecting the Draft BO Data Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
Projecting the Draft BO Behavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
4.5 Develop UI-Specifics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774
Adding Field Labels and Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774
Providing Value Help. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .776
Defining CDS Annotations for Metadata-Driven UIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
4.6 Develop Individual BO Capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
Numbering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850
Editing Language-Dependent Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .854
Using Type and Control Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .861
Exposing Messages on the UI and Message Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
Working with Large Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882
Creating RAP Business Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884
Modeling Parameters for Non-Standard Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
4.7 Develop Common Capabilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890
Working with Text Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .891
Enabling Text and Fuzzy Searches in SAP Fiori Apps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 897
Using Aggregate Data in SAP Fiori Apps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901
Using Virtual Elements in CDS Projection Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910
4.8 Implementing an Unmanaged Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .919
Returning Requested Entity in an Unmanaged Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .923
Requesting and Setting Data or Count in an Unmanaged Query. . . . . . . . . . . . . . . . . . . . . . . . 923
Implementing Filtering in an Unmanaged Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
Using Parameters in an Unmanaged Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .927
Implementing Search in an Unmanaged Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
Implementing Paging in an Unmanaged Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931
Implementing Sorting in an Unmanaged Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933
Considering Requested Elements in an Unmanaged Query. . . . . . . . . . . . . . . . . . . . . . . . . . . 935
Implementing Aggregations in an Unmanaged Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
5 Extend. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
5.1 About RAP Extensibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942
Extensibility Feature Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .944
Extensibility Architecture Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948
5.2 RAP Extensibility-Enablement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
Learn about Extensibility-Enablement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 952
Develop Extensibility-Enablement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
5.3 RAP Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978

Content PUBLIC 3
Learn about RAP Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
Develop RAP Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .990
6 Test. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1019
6.1 Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020
6.2 Test Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1020
6.3 Basic Test Class Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021
6.4 Unit Tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
Developing Unit Tests for a CDS View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
Developing Unit Tests for a Behavior Implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1033
6.5 Integration Tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059
EML Integration Tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059
OData Integration Tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1075
7 Consume. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085
7.1 Business Object Interface Consumption. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085
7.2 OData Service Consumption. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1086
8 Reuse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089
8.1 Integrating BTP Workflow Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089
Creating the Data Model for Workflow Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1093
Implementing a Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
Implementing the Service Callback Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100
9 CDS Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1105

9.1 AccessControl Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106
9.2 Aggregation Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107
9.3 Analytics Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1113
9.4 Analytics Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1138
9.5 AnalyticsDetails Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1152
9.6 AnalyticsDetails Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1175
9.7 Consumption Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195
9.8 Hierarchy Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1201
9.9 ObjectModel Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1207
9.10 OData Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
9.11 Search Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1243
9.12 Semantics Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1247
9.13 UI Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1260
10 What's New. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1370

10.1 Version 2302. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1370
ABAP RESTful Application Programming Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371
10.2 Version 2211. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371

4 PUBLIC Content
10.3 Version 2022 FPS00. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372
10.4 Version 2208. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377
10.5 Version 2205. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1379
ABAP RESTful Application Programming Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1379
10.6 Version 2202. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1379
10.7 Version 2111. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1381
10.8 Version 2021 FPS00. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1383
10.9 Version 2108. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1391
10.10 Version 2105. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393
10.11 Version 2020 FPS01. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396
10.12 Version 2102. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396
10.13 Version 2011. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397
10.14 Version 2020 FPS00. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1400
10.15 Version 2008. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1410
10.16 Version 2005. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1413
10.17 Version 2002. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416
10.18 Version 1911. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1418
10.19 Version 1909 FPS00. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1421
10.20 Version 1908. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421
10.21 Version 1905. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1426
10.22 Version 1902. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429
10.23 Version 1811. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432
11 Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1433

Content PUBLIC 5
1 ABAP RESTful Application Programming
Model
The ABAP RESTful Application Programming Model (in short RAP) defines the architecture for efficient end-to-
end development of intrinsically SAP HANA-optimized OData services (such as Fiori apps). It supports the
development of all types of Fiori applications as well as publishing Web APIs. It is based on technologies and
frameworks such as Core Data Services (CDS) for defining semantically rich data models and a service model
infrastructure for creating OData services with bindings to an OData protocol and ABAP-based application
services for custom logic and SAPUI5-based user interfaces – as shown in the figure below.
Architecture Overview
• Design Time [page 9]
Classification of ABAP RESTful Application Programming Model within the

Evolution of ABAP Programming Model
This image is interactive. Hover over each area for a description. Click highlighted areas for more information.

6 PUBLIC ABAP RESTful Application Programming Model

• https://help.sap.com/viewer/aa7fc5c3c1524844b811735b9373252a/LATEST/en-US [https://
help.sap.com/viewer/aa7fc5c3c1524844b811735b9373252a/LATEST/en-US]
• https://help.sap.com/viewer/cc0c305d2fab47bd808adcad3ca7ee9d/LATEST/en-US [https://
help.sap.com/viewer/cc0c305d2fab47bd808adcad3ca7ee9d/LATEST/en-US]
• ABAP RESTful Application Programming Model [page 6]
 For more information about the evolution of the ABAP programming model, read this blog on the
community portal.
ABAP Language Version
The present documentation is based on ABAP for Cloud Development. All described features are applicable
using the restricted set of language elements and repository objects that are released for cloud development.
For cloud products, only the language version ABAP for Cloud Development is available. In classic ABAP
development environments you can choose the ABAP language version. Developing RAP applications with
ABAP for Cloud Development is recommended for all ABAP development environments as this is key for your
developments to be upgrade-stable, cloud-ready, software-architecture-driven and thus future-proven.
For more information, about the ABAP language versions, see ABAP Language Versions (ABAP - Keyword
Documentation).
Validity of Documentation
The ABAP RESTful Application Programming Model is available in the following products:
• SAP BTP ABAP environment

• SAP S/4HANA Cloud
• Application Server ABAP 7.56
 Note
To highlight the specifics for on-prem releases, the  On-Premise icon is used.
To highlight the specifics for SAP BTP and SAP S/4HANA Cloud releases, the  Cloud icon is used.
This documentation reflects the latest feature scope of ABAP Development Tools (ADT) that is shipped with
the latest backend versions of the supported SAP products. Your actual available feature scope depends on
your backend version of the respective SAP product.

ABAP RESTful Application Programming Model PUBLIC 7
To see the product-specific documentation, please refer to the SAP Help Portal:
• SAP BTP ABAP environment

• SAP S/4HANA Cloud
• SAP S/4HANA
Prerequisites
To start developing with the ABAP RESTful Application Programming Model, make sure you meet the
prerequisites. See Prerequisites [page 305].
Constraints
The current version of the ABAP RESTful Application Programming Model still has some constraints for certain
features. For a detailed list, see Development Constraints [page 346].

8 PUBLIC ABAP RESTful Application Programming Model
2 Learn
The content in Learn provides background information about the ABAP RESTful Programming Model and helps
you to understand the concepts behind it.
The ABAP RESTful Programming Model has unified the development of OData services with ABAP. It is based
on three pillars that facilitate your development.
• Tools: The approach to integrate all implementation tasks in one development environment optimizes the
development flow and offers an end-to-end experience in one tool environment. New development artifacts
support the application developer to develop in a standardized way.
• Language: The ABAP language has been aligned and extended to support the development with the ABAP
RESTful Application Programming Model, together with CDS. The application developer uses typed APIs
for standard implementation tasks and benefits from auto-completion, element information, and static
code checks.
• Frameworks: Powerful frameworks represent another important pillar of the ABAP RESTful Programming
Model. They assume standard implementation tasks with options for the application developer to use
dedicated code exits for application-specific business logic.
Learn how these pillars are incorporated into the architecture of the ABAP RESTful Programming Model in the
following topics.
Design Time
The following diagram structures the development of an OData service from a design time perspective. In other
words, it displays the major development artifacts that you have to deal with during the creation of an OData
service with the ABAP RESTful Programming Model. The diagram takes a bottom-up approach that resembles
the development flow. The main development tasks can be categorized in three layers, data modeling and
behavior, business services provisioning and service consumption.
Hover over the building blocks and get more information and click to find out detailed information about the
components.

Learn PUBLIC 9

• Data Modeling and Behavior [page 12]

• Business Object [page 15]
• Query [page 281]
• Business Service [page 196]
• Service Definition [page 204]
• Service Binding [page 207]
• OData Service Consumption [page 1086]
• Web API [page 1087]
• UI service [page 1087]
• Business Object Projection [page 198]
Runtime
The following diagram provides a runtime perspective of the ABAP RESTful Programming Model. Runtime
objects are necessary components to run an application. This runtime stack is illustrated in a top-down
approach. An OData client sends a request, which is then passed to the generic runtime frameworks. These
frameworks prepare a consumable request for ABAP code and dispatch it to the relevant business logic
component. The request is executed by the business object (BO) when data is modified or by the query if data
is only read from the data source.
Hover over the building blocks to get more information and click to navigate to more detailed information about
the components.

10 PUBLIC Learn

• UI service [page 1087]

• Web API [page 1087]
• Runtime Frameworks [page 14]
• Entity Manipulation Language (EML) [page 235]
A more detailed description is available for the following concepts:
• Data Modeling and Behavior [page 12]

• Business Object Projection [page 198]

Learn PUBLIC 11
• Business Service [page 196]
• Service Definition [page 204]
• Service Binding [page 207]
• OData Service Consumption [page 1086]
• Runtime Frameworks [page 14]
2.1 Data Modeling and Behavior
The layer of data modeling and behavior deals with data and the corresponding business logic.
Data Model
The data model comprises the description of the different entities involved in a business scenario, for example
travel and booking, and their relationships, for example the parent-child relationship between travel and
booking. The ABAP RESTful Programming Model uses CDS to define and organize the data model. CDS
provides a framework for defining and consuming semantic data models. Every real-world entity is represented
by one CDS entity. View building capabilities allow you to define application-specific characteristics in the data
model. That means, CDS entities are the fundamental building blocks for your application. When using the CDS
entity for a data selection, the data access is executed by the SQL-view, which is defined in the CDS entity.
Depending on the use case, data models support transactional access or query access to the database. Thus,
data models are used in business objects or queries respectively.
The following diagram gives you an overview of the data model that is used in the development guides in
chapter Develop [page 344] of this documentation. Every block refers to one database table view and the
respective CDS entity. The blue boxes represent a Travel business object, with its child entities Booking
and Booking Supplement. The white boxes represent the entities that are not part of the business object,
but support with value helps or text associations. For read-only access to the database, that is simple data
retrieval, the data model is used for the query.

12 PUBLIC Learn
Data Model Used in the Development Guides of this Documentation
The following diagram shows the data model used in development guide Extend [page 939] to showcase the
possibilities for extending existing business objects.
Behavior
The behavior describes what can be done with the data model, for example if the data can be updated.
In transactional scenarios, the business object behavior defines which operations and what characteristics
belong to a business object. For read-only scenarios, the behavior of the data model is defined by the query
capabilities, for example if the data is filterable.
Learn more about the business object and the query in the following topics.
Business Object [page 15]
Query [page 281]

Learn PUBLIC 13
2.2 Runtime Frameworks
The runtime frameworks SAP Gateway and the RAP Runtime Engine are the frameworks that manage the
generic runtime for OData services built with the ABAP RESTful Programming Model. As a developer you
do not have to know the concrete inner functioning of these frameworks, as many development tasks are
automatically given. However, the following sections provide a high-level overview.
SAP Gateway
SAP Gateway provides an open, REST-based interface that offers simple access to SAP systems via the Open
Data Protocol (OData).
As the name suggests, the gateway layer is the main entry point to the ABAP world. All services that are
created with the ABAP RESTful Programming Model provide an OData interface to access the service. However,
the underlying data models and frameworks are based on ABAP code. SAP Gateway converts these OData
requests into ABAP objects to be consumed by the ABAP runtime.
RAP Runtime Engine
The RAP runtime engine dispatches the requests for the business object (BO) or the query. It receives the
ABAP consumable OData requests from the Gateway layer, forwards it to the relevant part of the business logic
and interprets the matching ABAP calls for it. For transactional requests, the RAP runtime engine delegates
the requests to the BO and calls the respective method of the BO implementation. For query requests,
the framework executes the query. Depending on the implementation type, the BO or the query runtime is
implemented by a framework or by the application developer.
If locks are implemented, the RAP runtime engine executes first instance-independent checks and sets locks.
For the eTag handling, the framework calls the necessary methods before the actual request is executed.
 Note
The RAP runtime engine is also known under the name SADL (Service Adaptation Description Language).
Apart from the runtime orchestration, the SADL framework is also responsible for essential parts in the
query and BO runtime.
Examples
The OData client sends a DELETE request, which is converted to an object that is understandable for ABAP. The
RAP runtime engine analyzes this ABAP object and triggers the MODIFY method for DELETE of the business
object to execute the DELETE operation on the database table. Depending on the implementation type
(managed or unmanaged), the code for the MODIFY method is generically available or must be implemented by
the application developer.
Likewise, if an OData request contains a query option, such as $orderby, the Gateway layer converts it to
the query capability SORT. Then, the RAP runtime engine takes over and delegates the query capability to

14 PUBLIC Learn
the query. Depending on the runtime type (managed or unmanaged), the query is executed by the generic
framework in case of managed type or by the self-implemented runtime in case of unmanaged type. For
a managed query, the generic framework converts the requests to ABAP SQL statements to access the
database.
2.3 Business Object
Introduction
A business object (BO) is a common term to represent a real-world artifact in enterprise application
development such as the Product, the Travel, or the SalesOrder. In general, a business object contains several
nodes such as Items and ScheduleLines and common transactional operations such as for creating, updating
and deleting business data. An additional application-specific operation in the SalesOrder business object
might be, for example, an Approve action allowing the user to approve the sales order. All changing operations
for all application-related business objects form the transactional behavior in an application scenario.
When going to implement an application scenario based on business objects, we may distinguish between the
external, consumer-related representation of a business object and the internal, provider-related perspective:
• The external perspective hides the intrinsic complexity of business objects. Developers who want to
create a service on top of the existing business objects for role-based UIs do not need to know in detail on
which parts of technical artifacts the business objects are composed of or how runtime implementations
are orchestrated internally. The same also applies to all developers who need to implement a consumer on
top of the business object’s APIs.
• The internal perspective exposes the implementation details and the complexity of business objects. This
perspective is required for application developers who want to provide new or extend existing business
objects for the industries, the globalization and partners.
From a formal point of view, a business object is characterized by
• a structure,
• a behavior and
• the corresponding runtime implementation.
Structure of a Business Object
From a structural point of view, a business object consists of a hierarchical tree of nodes (SalesOrder, Items,
ScheduleLines) where the nodes are linked by special kinds of associations, namely by compositions. A
composition is a specialized association that defines a whole-part relationship. A composite part only exists
together with its parent entity (whole).

Learn PUBLIC 15
Each node of this composition tree is an element that is modeled with a CDS entity and arranged along a
composition path. As depicted in the diagram below, a sequence of compositions connecting entities with each
other, builds up a composition tree of an individual business object.
The root entity is of particular importance in a composition tree: The root entity serves as a representation
of the business object and defines the top node within a hierarchy in a business object's structure. This is
considered in the source code of the CDS data definition with the keyword ROOT.
The root entity serves as the source of a composition which is defined using the keyword COMPOSITION in the
corresponding data definition. The target of this composition defines a direct child entity. On the other hand,
CDS entities that represent child nodes of the business object’s composition tree, must define an association
to their compositional parent or root entity. This relationship is expressed by the keyword ASSOCIATION TO
PARENT. A to-parent association in ABAP CDS is a specialized association which can be defined to model the
child-parent relationship between two CDS entities.
In a nutshell: both, a sequence of compositions and to-parent associations between entities define the
structure of a business object with a root entity on top of the composition tree.
All entities - except the root entity - that represent a node of the business object structure serve as a:
• Parent entity - if it represents a node in a business object's structure that is directly connected to another
node when moving towards the root.
• Child entity - if it represents a node in a business object's structure that is directly connected to another
node (parent node) when moving away from the root.
• Leaf entity - if it represents a node in a business object's structure without any child nodes. A leaf entity is
a CDS entity, which is the target of a composition (a child entity node) but does not contain a composition
definition.
Composition Tree Reflects the Structure of a Business Object

16 PUBLIC Learn
Behavior of a Business Object
To specify the business object's behavior, the behavior definition as the corresponding development object
is used. A business object behavior definition (behavior definition for short) is an ABAP Repository object
that describes the behavior of a business object in the context of the ABAP RESTful application programming
model. A behavior definition is defined using the Behavior Definition Language (BDL).
A behavior definition always refers to a CDS data model. As shown in the figure below, a behavior definition
relies directly on the CDS root entity. One behavior definition refers exactly to one root entity and one CDS root
entity has at most one behavior definition (a 0..1 cardinality), which also handles all included child entities that
are included in the composition tree. The implementation of a behavior definition can be done in a single ABAP
class (behavior pool) or can be split between an arbitrary set of ABAP classes (behavior pools). The application
developer can assign any number of behavior pools to a behavior definition (1..N cardinality).
Relationship Between the CDS Entities and the Business Object Behavior
A behavior specifies the operations and field properties of an individual business object in the ABAP RESTful
programming model. It includes a behavior characteristic and a set of operations for each entity of the
business object’s composition tree.

Learn PUBLIC 17
Business Object’s Behavior
Behavior Characteristic
Behavior characteristic is that part of the business object's behavior that specifies general properties of an
entity such as:
ETag [page 33]
Draft handling [page 46]
Feature control
Numbering [page 23]
Authorization Control [page 80]
Apart from draft capabilities, these characteristics can be defined for each entity separately.
Operations
Each entity of a business object can offer a set of operations. They can cause business data changes that
are performed within a transactional life cycle of the business object. As depicted in the diagram above,
these modify operations include the standard operations create(), update() and delete() as well as lock
implementations and application-specific operations with a dedicated input and output structure which are
called actions. Another kind of operations are the read operations: they do not change any business data in the

18 PUBLIC Learn
context of a business object behavior. Read operations include read, read by association, and functions (that
are similar to actions, however, without causing any side effects).
For more information, see
• Create Operation [page 89]

• Update Operation [page 91]
• Delete Operation [page 94]
• Actions [page 101]
• Locking [page 33]
Business Object’s Runtime
The business object runtime mainly consists of two parts:
The first part is the interaction phase, in which a consumer calls the business object operations to change
data and read instances with or without the transactional changes. The business object runtime keeps the
changes in its internal transactional buffer which represents the state of the instance data. This transactional
buffer is always required for a business object. After all changes were performed, the data can be persisted.
This is realized with the save sequence.
For more information about the BO runtime within one LUW, see The RAP Transactional Model for the SAP LUW
[page 219].

Learn PUBLIC 19
BO Runtime
For each operation the transactional runtime is described in detail in the respective runtime diagrams. See
Operations [page 88].
The save sequence has the same structure for each operation. For more information, see Save Sequence
Runtime [page 225].
Instantiation of Handler and Saver Classes
In general, the instantiation of handler and saver classes is tightly coupled to an ABAP session. Instances live as
long as the ABAP session and they can exist across LUW borders. However, their life cycle depends on the way
their methods are called. Nested method invocations always provoke the reinstantiation of the local handler
and saver classes. For example, this is the case if a handler method executes an EML modify request in local
mode to call another method of the same handler class, or if other BOs are involved in the invocation chain.
 Note
Do not work with data in member variables for keeping data for subsequent method invocation. The data is
lost once the handler class is reinstantiated.
The saver class is always instantiated once a corresponding handler method is called.

20 PUBLIC Learn
Released Business Objects
Released Business Objects are RAP business objects of which some components are released with a
release contract that ensures lifecycle stability for the respective business object for consumers.
SAP releases business object parts for consumption in custom implementations with the C1 release contract
to ensure lifecycle stability and upgrade-safety. The details about consuming released BOs is described in
Business Object Interface Consumption [page 1085].
2.3.1 Business Object Implementation Types
Different BO implementation types offer various options to create your development scenario with the ABAP
RESTful application programming model.
General
The RAP framework offers different implementation types that are optimized to match your needs as
application developer. Depending on the initial situation of your development, you can choose the RAP
development approach to easily exploit the many advantages of programming with RAP.
The main approaches are the two standard implementation types of RAP business objects, managed or
unmanaged. Both approaches are based on a data model that is defined in CDS view entities. The difference
between the two implementation types lies in the provisioning of the BO's transactional behavior. It is
mainly the level of free-style development for your specific RAP application that determines which of the
implementation type is the best option for you. Whereas the standard behavior is provided by a RAP managed
provider when using the implementation type managed, it's the developer's task to implement the complete
behavior in the unmanaged implementation type.
Business Objects with both implementation types can be exposed as OData services for UIs or Web APIs.
Managed Implementation Type
The managed implementation type addresses use cases where all essential parts of an application must be
developed from scratch. However, these new applications can highly benefit from out-of-the-box support
for transactional processing. Standard operations (create, update, delete) must only be specified in the
behavior definition to obtain a ready-to-run business object. In addition the provisioning and handling of the
transactional buffer is automatically done for you. The technical implementation aspects are taken over by
the managed RAP BO provider. The interaction phase and the save sequence are implemented generically.
The application developer can then focus on business logic that is implemented using actions, validations and
determinations and user interaction. The corresponding transactional engine manages the entire life cycle of
your business object and covers all aspects of your business application development.
The managed implementation type is aimed for building new applications from scratch without any already
existing code for business logic. The standard functionality that is given in managed business objects is easily

Learn PUBLIC 21
retrieved. The business logic is implemented using predefined implementation methods that are integrated
during the runtime in the interaction phase and save sequence. On the other hand, integrating existing
business logic in the standard functionality of managed business objects can hardly be achieved.
A complete developer guide on how to develop a new application from scratch is provided in Developing
Managed Transactional Apps [page 371].
Managed Implementation Type with Unmanaged or Additional Save

Managed business objects fully provide the managed behavior during the interaction phase, as well as the
saving procedure during the save sequence. In some cases, however, it might be necessary to implement
a different saving option, be it because you need to save to a different database table, or you want to add
an additional saving procedure. These use cases are supported in managed business objects that support
unmanaged or additional save. Whereas the interaction phase is still completely managed by the RAP
managed provider, the save sequence can be modified and business logic for saving can be integrated in
the corresponding saver methods.
The developer guide for managed business objects provides a description on how to implement additional
or unmanaged save options. See Integrating Additional Save in Managed Business Objects [page 438] and
Integrating Unmanaged Save in Managed Business Objects [page 447].
Unmanaged Implementation Type
In unmanaged business objects, the application developer must implement essential components of the REST
contract. There is no standard functionality provided by the RAP framework. It is only the frame of a business
object, that an application developer needs to adhere to. The behavior must be specified in the behavior
definition but implemented manually in ABAP classes in the behavior pool. All existing business logic can be
integrated, including standard behavior like create, update and delete. In addition, the transactional buffer
must be provided and handled by the application developer in the ABAP behavior pool.
This implementation type is mainly aimed at application developers that already have their business logic
encapsulated in functional modules. These function modules can then be integrated in the corresponding
behavior methods in the RAP BO. Like this, you can reuse existing business logic in your RAP business objects
and you still benefit from the standardized RAP runtime orchestration to easily create a RAP service.
A complete developer guide on how to develop an application which integrates existing legacy logic is given in
Developing Unmanaged Transactional Apps [page 481].
Additional Implementation Options
Depending on the targeted RAP service that you want to create, there are several additional implementation
options that can be included in the aforementioned implementation types.
Query Features
RAP services include sophisticated querying features, such as filtering, sorting, search capabilities, aggregation
options, or value helps. Some standard features are provided by the RAP query engine and are given from
scratch when building a RAP service. Business logic dependent features, such as search or value helps must be
implemented using annotations in CDS and its strong data modeling capabilities.

22 PUBLIC Learn
Most of the read-only features are described in Developing Read-Only List Reporting Apps [page 350].
Draft Capabilities
To build end-user applications with stateless functionality that enables using the application independently
of time or device, the RAP framework offers draft capabilities. Using the draft concept in RAP applications
means persisting the state of the transactional buffer on a database table. This prevents data loss and stores all
changes of a current user interaction until it is activated. The draft concept is enabled in RAP business objects
in the behavior definition and is managed by the managed draft provider. The application developer does not
have to handle draft processing.
A complete developer guide on how to develop an application with draft is given in Developing Transactional
Apps with Draft Capabilities [page 578].
2.3.2 RAP BO Provisioning
2.3.2.1 RAP BO Behavior
2.3.2.1.1 Numbering
About Numbering
Numbering is about setting values for primary key fields of entity instances during runtime.
The primary key of a business object entity can be composed of one or more key fields, which are identified
by the keyword key in the underlying CDS view of the business object. The set of primary key fields uniquely
identify each instance of a business object. The primary key value of a business object instance cannot be
changed after the CREATE.
There are various options to handle the numbering for primary key fields depending on when (early or
late during the transactional processing) and by whom (consumer, application developer, or framework) the
primary key values are set. You can assign a numbering type for each primary key field separately.
Early and Late Numbering
In an early numbering scenario, the primary key value is set instantly after the modify request for the CREATE is
executed. The key values can be passed externally by the consumer or can be set internally by the framework
or an implementation of the FOR NUMBERING method. For more information, see Early Numbering [page 24].

Learn PUBLIC 23
In a late numbering scenario, the key values are always assigned internally without consumer interaction after
the point of no return in the interaction phase has passed, and the SAVE sequence is triggered. This
ensures a gap free key value assignment like it is required for example for invoices. For more information, see
Late Numbering [page 28].
Managed and Unmanaged Numbering
In a managed numbering scenario, the primary key values are assigned automatically by the framework
without any additional implementation in the behavior pool, like with numbering: managed in UUID
scenarios.
For more information, refer to Managed Internal Early Numbering [page 26].
In an unmanaged numbering scenario, an additional implementation is necessary for assigning the primary key
values, like with early numbering or late numering that must be implemented in the respective saver
methods in the behavior pool.
For more information, see:
• Unmanaged Internal Early Numbering [page 27]

• Unmanaged Internal Late Numbering [page 29]
Early Numbering [page 24]
Late Numbering [page 28]
Uniqueness Check for Primary Keys [page 32]
2.3.2.1.1.1 Early Numbering
The numbering type early numbering refers to an early value assignment for the primary key field. In this case,
the final key value is available in the transactional buffer instantly after the MODIFY request for CREATE.
The key value can either be given by the consumer (externally) or by the framework (internally). In both cases,
the newly created BO instance is clearly identifiable directly after the CREATE operation has been executed. It
can be referred to by this value in case other operations are executed on this instance during the interaction
phase (for example an UPDATE). During the save sequence, the newly created BO instance is written to the
database with the primary key value that was assigned earlier on the CREATE operation.
External Early Numbering [page 25]
Internal Early Numbering [page 26]
<method> FOR NUMBERING [page 28]

24 PUBLIC Learn
Related Information
Numbering [page 23]

Late Numbering [page 28]
2.3.2.1.1.1.1 External Early Numbering
External Early Numbering
We refer to external numbering if the consumer hands over the primary key values for the CREATE operation,
just like any other values for non-key fields. The runtime framework (managed or unmanaged) takes over the
value and processes it until finally writing it to the database. The control structure for the CREATE operation is
flagged with true for the primary key field.
In this scenario, it must be ensured that the primary key value given by the consumer is uniquely identifiable.
New instances with an already existing primary key value are rejected during the save sequence. The ABAP
RESTful Application Programming Model supports uniqueness checks in early stages of the interaction phase
to give the end user an early feedback.
For more information, see Uniqueness Check for Primary Keys [page 32].
Implementation
For external numbering, you must ensure that the primary key fields are not read-only at CREATE. Otherwise,
the consumer cannot provide any value for the primary key field. The RAP framework offers dynamic primary
key handling for this scenario. To ensure that the primary key fields are filled when creating new instances, but
are read-only on further processing these instances, you can use operation-dependent field access restrictions
in the behavior definition.
For more information, see Dynamic Feature Control [page 131].
...

define behavior for Entity [alias AliasedName]

{ ...
field (mandatory:create| readonly:update);
...}

For more information about the syntax, see CDS-BDL - mandatory:create (ABAP- Keyword Documentation)
and CDS BDL - readonly:update.
Optional External Early Numbering
We refer to optional external numbering if both, external and internal numbering is possible for the same BO.
If the consumer hands over the primary key value (external numbering), this value is processed by the runtime

Learn PUBLIC 25
framework. If the consumer does not set the primary key value, the framework steps in and draws the number
for the instance on CREATE.
 Note
Optional external numbering is only possible for managed business objects with UUID keys.
Use cases for optional external numbering are replication scenarios in which the consumer already knows
some of the UUIDs for specific instances to create.
Implementation
Optional external numbering is defined in the behavior definition. The key field must not be readonly, so that
the consumer is able to fill the primary key fields.
For details about the syntax, see CDS BDL - early numbering (ABAP - Keyword Documentation)
2.3.2.1.1.1.2 Internal Early Numbering
In scenarios with internal numbering, the runtime framework assigns the primary key value when creating the
new instance. Internal numbering can be managed by the RAP runtime or unmanaged, that is implemented by
the application developer.
2.3.2.1.1.1.2.1 Managed Internal Early Numbering
When using managed internal early numbering, a UUID is drawn automatically during the CREATE request by
the RAP managed runtime.
 Note
Managed early numbering is only possible for key fields with ABAP type raw(16) (UUID) of BOs with
implementation type managed.
For more information, see Automatically Drawing Primary Key Values in Managed BOs [page 850].
Implementation
Managed numbering is defined in the behavior definition. Additionally, the key field must be defined as
readonly.

[implementation] managed [implementation in class ABAP_CLASS [unique]];


lock (master|dependent() )
...
{ ...

field ( readonly, numbering:managed ) KeyField1 [, KeyField2, …, keyFieldn];

...}

For more information about the syntax, see CDS BDL - field numbering (ABAP- Keyword Documentation).

26 PUBLIC Learn
2.3.2.1.1.1.2.2 Unmanaged Internal Early Numbering
Unmanaged Numbering in Managed Business Objects and Unmanaged Business Objects

with managed Draft
Unmanaged Early Numbering in Unmanaged Implementation Scenarios
In unmanaged BOs, the CREATE operation implements the assignment of a primary key value during the
CREATE modification.
Implementation
The assignment of a new number must be included in your application code.
For more information, see Implementing the CREATE Operation for Travel Instances [page 522].
Unmanaged Early Numbering in Managed and Unmanaged Implementation Scenarios with

Draft Capabilities
Unmanaged Early Numbering in Managed and Unmanaged Implementation

Scenarios with Draft Capabilities
Early numbering is defined in the behavior definition on entity level and the key assignment is implemented
in the corresponding handler method which is called during the CREATE or CREATE-BY-ASSOCIATION.
Unmanaged internal numbering is then applied to all primary key fields of a BO entity and not on individual field
level. Consequently, you must map all key fields in your implementation in the MAPPED result parameter of the
FOR NUMBERING method .
Unmanaged numbering is defined in the behavior definition with early numbering on entity level. For
scenarios in which all key fields are assigned with unmanaged early numbering, it is recommended to set the
respective key fields to readonly like in the following generic example:


early numbering
...
{ ...

field ( readonly ) KeyField1 [, KeyField2, …, keyFieldn];

...}

You can then implement the FOR NUMBERING method in the behavior pool with the following method
signature. Because the FOR NUMBERING method is executed during the CREATE, it can't be triggered externally
via EML, but only implicitly with a create operation. Furthermore, you can't define any modify operations during
a CREATE. The method receives all entities for which keys need to be assigned as importing parameter::

METHODS earlyNumbering_Create method FOR NUMBERING

[IMPORTING] entities FOR CREATE business_object_entity.
For more details regarding the FOR NUMBERING method, refer to <method> FOR NUMBERING [page 28].
For details about the syntax of unmanaged numbering, refer to CDS BDL - early numbering (ABAP - Keyword
Documentation).

Learn PUBLIC 27
For a specific implementation example of a managed business object with a number range object, refer to
Developing Early Unmanaged Numbering [page 397].
2.3.2.1.1.1.3 <method> FOR NUMBERING
This method implements early unmanaged numbering for managed business objects. You implement the FOR
NUMBERING method if you want to implement early unmanaged numbering for your business object entity. The
implementation is called before a business object entity is instantiated during the CREATE operation. With this
method, all primary key CIDs of a BO entity are mapped to the keys drawn in the method implementation.
 Note
Early numbering can't be combined with numbering:managed.
Declaration of <method> FOR NUMBERING
Unmanaged early numbering is defined on BO entity level with early numbering. The implementation is
applied to all keys of an entity, so that all key fields must be mapped in the implementation. The signature of
this handler method is defined by the keyword FOR NUMBERING, followed by the input parameters entities,
the implicit changing parameters reported, failed, and mapped:

METHODS earlyNumbering_Create method FOR NUMBERING

[IMPORTING] entities FOR CREATE business_object_entity.
The mapped structure specifies how the temporary keys are mapped to the keys drawn in the implementation.
For more information about the mapped structure, refer to Derived Data Types [page 150].
Import Parameters
• entities
The table type of entities includes all entitites for which keys must be assigned.
Implicit Return Parameters

The FOR NUMBERING method provides the implicit CHANGING parameters failed and reported and
mapped. The mapped structure contains the mapping between temporary IDs and assigned keys from the
implementation. For more information, see Implicit Response Parameters [page 151].
2.3.2.1.1.2 Late Numbering
The numbering type late numbering refers to a late value assignment for the primary key fields. The final
number is only assigned just before the instance is saved on the database.

28 PUBLIC Learn
Late numbering is a common concept for drawing gap-free numbers. In some cases, it can be business critical
that identifier numbers are gap-free, for example invoice numbers.
Related Information
Numbering [page 23]

Early Numbering [page 24]
2.3.2.1.1.2.1 Unmanaged Internal Late Numbering
In scenarios with internal numbering, the runtime framework assigns the primary key value when creating the
new instance. Late numbering is internal by default, since a consumer can't influence the SAVE sequence after
the point of no return. To define late numbering, the method ADJUST NUMBERS must be implemented. For
more information, see Unmanaged Internal Late Numbering Definition [page 32].
Late numbering is used for scenarios that need gap-free numbers. Since the final key value is set just before
the SAVE to the database, everything is checked before the number is assigned.
Late numbering available for managed and unmanaged implementation scenarios with and without draft. For
specifics regarding RAP BOs with draft and late numbering, see Draft UUID for Draft Instances [page 30]
and Draft Instances and Associations with late numbering in Source or Target Entity [page 31].
For an overview as to when a key value is assigned in a late numbering scenario with the ADJUST NUMBERS
method, see Save Sequence Runtime [page 225].
Key Handling in Late Numbering
A newly created instance must always be uniquely identifiable by its transactional key for internal processing
during the interaction phase. In a RAP BO with late numbering, in which the final key value assignment
only takes place during the save sequence, the transactional primary key needs an addition to fulfill the
identification requirement during the interaction phase and the early save phases. This is done by extending
the transactional primary key with a preliminary ID (%PID), in order to ensure the uniqueness also during more
than one ABAP session (in draft scenarios).
The component group %tky then contains at least two elements: %pid and %key (where %key contains all key
fields). For transactional processing during the interaction phase, %tky must be uniquely identifiable in total.
This means that you can either fill %pid or %key with a preliminary value and leave the other one empty, or fill
both for unique identification. The following screenshot illustrates the component groups %tky and %pky in a
late numbering scenario. The example scenario is a draft scenario. Therefore, %is_draft is included in %tky.

Learn PUBLIC 29
%tky and %pky in Late Numbering Scenario with Draft
To assign the real and final key value to the instance, the method ADJUST_NUMBERS is called after FINALIZE
and CHECK_BEFORE_SAVE, which is just before the actual SAVE happens. It returns the final key value, which is
globally unique, which means that the instance doesn't need to be identified by the preliminary key anymore.
Retrieving Final Key Values with EML
In a late numbering scenario, the final key values are assigned after the point of no return, where no further
consumer interaction is possible. However, in some use cases it might be required to retrieve the final key
value, e.g., to trigger an operation of another BO, for which the respective key value is required as input
parameter.
 Example
BO A triggers a create of BO B when an instance of A is saved. To establish a foreign key relationship, the
final key value of A is necessary.
As a consumer, you can use the CONVERT KEY statement on a root entity to retrieve the final key value
assigned to a RAP BO instance in ADJUST NUMBERS and use it for further processing. If you use this statement
on child entities outside of the behavior pool of the BO, no result is returned.
Note that you can't use CONVERT KEY for instances of your own RAP BO, only for foreign RAP BOs, e.g. in a
cross-BO relationship. You can use CONVERT KEY only in the late save phase during the COMMIT, when the final
key values are assigned.
For more information, see CONVERT KEY (ABAP- Keyword Documentation).
Late Numbering and Draft Instances
Draft UUID
Since the final key values are only assigned after the point of no return, the interaction phase operates on
preliminary semantic key values. Thus, an additional draft identifier is required as PID to uniquely identify each
draft instance. Hence, RAP BOs with draft capabilities and late numbering require an obligatory DRAFTUUID
key field in the corresponding draft tables.

30 PUBLIC Learn
If late numbering is defined for a root entity, all child nodes must also contain a parentdraftuuid key field
and their own draft identifier if they have late numbering assigned. The mapping of the draft UUIDs itself is
managed by the RAP framework.
 Note
If late numbering is added subsequently to a RAP BO, the draft tables must be regenerated to contain
the required draft key fields.
As an example, the draft database table /dmo/d_travel_d of the Travel entity in a managed with draft
scenario is extended as follows in case of late numbering on root entity level (assuming that the Booking
entity also uses late numbering and BookingSupplement entity uses another numbering method):
 Sample Code
define table /dmo/d_travel_d {

key mandt : mandt not null;
key travel_id : /dmo/travel_id not null;
key draftuuid : sdraft_uuid not null;

...}
As a direct child entity, the draft database table /dmo/d_booking_d of the Booking entity must also be
extended with its own draft uuid and the draft uuid of the parent entity:
 Sample Code
define table /dmo/d_booking_d {

key booking_id : /dmo/booking_id not null;
parentdraftuuid : sdraft_uuid;

...}
 Sample Code
define table /dmo/a_bksuppl_d {

key booking_supplement_id : /dmo/booking_supplement_id not null;
parentdraftuuid : sdraft_uuid;

...}
Draft Instances and Associations with late numbering in Source or Target Entity
Since final key values are only assigned during the late save phase, associations with late numbering in the
source or target entity aren't supported, as well as foreign key associations with late numbering on the target
entity and reverse foreign key associations with late numbering on the source entity. It's technically possible
to define these associations, but they cause a syntax warning in the behavior definition. Executing these
associations for draft instances results in a short dump.
Generally, instances with late numbering can only be defined as an association target if the instance was
already saved and the final key values have been assigned.

Learn PUBLIC 31
The restrictions regarding associations aren't applicable for late numbering in the following scenarios:
• Compositions, ToParent associations, ToLockMaster associations, ToAuthorizationMaster associations, or

ToEtagMaster associations.
• Foreign key associations with early numbering target and late numbering source.
• Reverse foreign key associations with early numbering source and late numbering target.
Unmanaged Internal Late Numbering Definition
You can define late numbering with the addition late numbering in the behavior definition header for each
RAP entity in RAP BOs with managed and unmanaged implementation type with and without draft capabilities.
For more information about the syntax, see CDS BDL - late numbering (ABAP - Keyword Documentation). As a
prerequisite, you must implement the ADJUST_NUMBERS method for both implementation types.
For more information about the ADJUST NUMBERS method , see ADJUST_NUMBERS [page 230].
For an implementation example, refer to Implementing the Interaction Phase and the Save Sequence [page
520].
2.3.2.1.1.3 Uniqueness Check for Primary Keys
A uniqueness check ensures that new primary keys are unique before the saving of instances with these
primary keys are rejected by a database table. The persistent database table rejects any entry with a key that
already exists. To avoid that the work of an end user is in vain if all the changes are rejected by the database,
the uniqueness of the primary key values of new or resumed instances must be checked as early as possible.
Hence, on creating new draft data, the application must ensure that the primary keys are unique.
A uniqueness check must check the new primary key values against all already existing active instances and
additionally all draft instances, that are still in their exclusive lock phase (for details about the locking phases of
a draft instance, see Locking in Draft Scenarios [page 40]). In case of a primary key value conflict with any of
those existing instances, the creation of the new instance must be rejected. In case there is a conflict with the
primary key values of the entity instance to be created and an already existing draft instance, that has reached
its optimistic locking phase, the RAP runtime framework will however automatically discard the existing draft
instance in order to allow creation of the new instance instead.
Internal Numbering
In scenarios with internal numbering, the uniqueness is usually given by the process of determining the
number, for example by a number range object. In scenarios with internal managed numbering, the RAP
runtime framework ensures the uniqueness as it provides unique UUID values.
External Numbering
In scenarios with external numbering, the uniqueness must be checked explicitly. In some cases, it is possible
for the RAP runtime framework to do the check. For other cases, you must implement a precheck to check the
keys before the actual instance is created and provide an implementation for the resume action in scenarios
with draft support.

32 PUBLIC Learn
Responsibilities for the Uniqueness Check in Scenarios with External Numbering
Managed Scenario without Draft without Unmanaged Lock RAP runtime framework
Managed Scenario with Draft without Unmanaged Lock • for active instances: RAP runtime framework
• for draft instances: Application developer needs to im-
plement a precheck and the draft resume action.
Managed Scenario with/without Draft with Unmanaged Lock Application developer needs to implement the uniqueness
check in the precheck and the draft resume action.
Unmanaged Scenario with/without Draft Application developer needs to implement the uniqueness
check in the precheck and the draft resume action.
After the uniqueness is checked successfully, the RAP runtime framework exclusively reserves the primary key
value for the corresponding draft instance for the time of exclusive lock phase. After the exclusive lock, once
the draft is resumed, the uniqueness check must be executed again.
Related Information
Operation Precheck [page 115]

2.3.2.1.2 Concurrency Control
Concurrency control prevents concurrent and interfering database access of different users. It ensures that
data can only be changed if data consistency is assured.
RESTful applications are designed to be usable by multiple users in parallel. In particular, if more than one user
has transactional database access, it must be ensured that every user only executes changes based on the
current state of the data and thus the data stays consistent. In addition, it must be ensured that users do not
change the same data at the same time.
There are two approaches to regulate concurrent writing access to data. Both of them must be used in the
ABAP RESTful Application Programming Model to ensure consistent data changes.
• Optimistic Concurrency Control [page 33]

• Pessimistic Concurrency Control (Locking) [page 38]
2.3.2.1.2.1 Optimistic Concurrency Control
Optimistic concurrency control enables transactional access to data by multiple users while avoiding
inconsistencies and unintentional changes of already modified data.
The approach of optimistically controlling data relies on the concept that every change on a data set is logged
by a specified ETag field. Most often, the ETag field contains a timestamp, a hash value, or any other versioning

Learn PUBLIC 33
that precisely identifies the version of the data set. Optimistic concurrency control is only relevant when
consuming business objects via OData. That is why, the ETag is also referred to as OData ETag.
When optimistic concurrency control is enabled for RAP business objects, the OData client must send an ETag
value with every modifying operation. On each ETag relevant operation, the value of the ETag field is compared
to the value the client sends with the request. Only if these values match is the change request accepted and
the data can be modified. This mechanism ensures that the client only changes data with exactly the version
the client wants to change. In particular, it is ensured that data an OData client tries to change has not been
changed by another client between data retrieval and sending the change request. On modifying the entity
instance, the ETag value must also be updated to log the change of the instance and to define a new version for
the entity instance.
Concurrency control based on ETags is independent of the ABAP session and instances are not blocked to be
used by other clients.
The following diagram illustrates the ETag checks for two different clients working on the same entity instance.
ETag Check in Update Operation
In RAP business objects, optimistic concurrency control is defined in the behavior definition by specifying an
ETag field. Shortly before data is changed on the database, the RAP runtime engine reads the ETag field to
compare its value to the value that is sent with the change request. The modify operation is accepted if the
ETag values match. The modify operation is then executed and a new ETag value is assigned to the entity
instance. The modify operation is denied if the ETag values are not identical. To enable the transactional read

34 PUBLIC Learn
for reading the ETag value in unmanaged scenarios, the method FOR READ must be implemented by the
application developer.
For more information about the ETag check during the runtime of a modify operation, see Update Operation
[page 91].
ETag in Draft Scenarios
In draft scenarios, the ETag pursues the same goal as in non-draft scenarios. It ensures that the end user of an
OData service only changes instances with the state that is known, for example displayed on the UI.
When active instances are requested (for example by the edit action), the value of the indicated ETag field on
the active database table is compared to the ETag that is sent with the request.
When draft instances are requested (for example by an UPDATE on a draft instance), the value of the field on
the draft table that logs the changes on the draft instance (draftentitylastchangedatetime) is used for
value comparison. Like this, it is ensured that one user cannot make changes on the same draft instance on
different UIs. In other words, a user can only make changes on the latest version of the draft instance.
Draft scenarios also require a total ETag that manages the transitions from active to draft and vice-versa. For
more information, see Total ETag [page 51].
Related Information
ETag Definition [page 35]

ETag Implementation [page 36]
2.3.2.1.2.1.1 ETag Definition
In RAP business objects, ETags are used for optimistic concurrency control. You define the ETag in the behavior
definition of the business object entity.
ETag fields are dedicated administrative fields on the database table that log data access and modification.
The RAP framework offers reuse data elements that can be used for the administrative data field definition in
database tables. For more information, see RAP Reuse Data Elements [page 210].
Whenever an ETag is defined for a business object entity in the behavior definition, the ETag check is executed
for modifying operations, as described in Optimistic Concurrency Control [page 33]. You can define which
entities support optimistic concurrency control based on their own ETag field and which entities use the ETag
field of other entities, in other words, which are dependent on others.
For information about the syntax, see CDS BDL - ETag (ABAP - Keyword Documentation).
ETag Master

Learn PUBLIC 35
An entity is an ETag master if changes of the entity are logged in a field that is part of the business object entity.
This field must be specified as an ETag field in the behavior definition (ETagField). Its value is compared to
the value the change request sends before changes on the business entity are executed.
Root entities are often ETag masters that log the changes of every business object entity that is part of the BO.
ETag Dependent
An entity is defined as ETag dependent if the changes of the entity are logged in a field of another BO entity. In
this case, there must be an association to the ETag master entity. To identify the ETag master, the association
to the ETag master entity is specified in the behavior definition (_AssocToETagMaster). Whenever changes
on the ETag dependent entities are requested, the ETag value of their ETag master is checked.
 Note
You do not have to include the ETag field in ETag dependent entities. Via the association to the ETag master
entity, it is ensured that the ETag field can always be reached.
The association that defines the ETag master must be explicitly specified in the behavior definition, even
though it is implicitly transaction-enabled due to internal BO relations, for example a child/parent relationship.
The association must also be defined in the data model structure in the CDS views and, if needed, redefined in
the respective projection views.
An ETag master entity must always be higher in the BO composition structure than its dependents. In other
words, a child entity cannot be ETag master of its parent entity.
Projection Behavior Definition
projection;

define behavior for ProjectionView [alias ProjectionViewAlias]

use etag [page 36]

{
...
use association _AssocToETagMaster

}
To expose the ETag for a service specification in the projection layer, the ETag has to be used in the projection
behavior definition for each entity with the syntax use etag. The ETag type (master or dependent) is derived
from the underlying behavior definition and cannot be changed in the projection behavior definition.
If the entity is an ETag dependent, the association that defines the ETag master must be used in the projection
behavior definition. This association must be correctly redirected in the projection layer.
Related Information
Optimistic Concurrency Control [page 33]

ETag Implementation [page 36]
2.3.2.1.2.1.2 ETag Implementation
There are two prerequisites that must be fulfilled to make an ETag check work properly:

36 PUBLIC Learn
• The ETag field must be updated reliably with every change on the entity instance.
• The read access to the ETag master field from every entity that uses an ETag must be guaranteed.
If these prerequisites are fulfilled, the actual ETag check is performed by the RAP runtime engine, see Update
Operation [page 91], for example.
Implementation for ETag Field Updates
An ETag check is only possible, if the ETag field is updated with a new value whenever the data set of the entity
instance is changed or created. That means, for every modify operation, except for the delete operation, the
ETag value must be uniquely updated.
Managed Scenario
The managed scenario updates administrative fields automatically if they are annotated with the respective
annotations:
@Semantics.user.createdBy: true

@Semantics.systemDateTime.createdAt: true
@Semantics.user.lastChangedBy: true

@Semantics.systemDateTime.localInstanceLastChangedAt: true
If the element that is annotated with @Semantics.systemDateTime.localInstanceLastChangedAt:

true is used as an ETag field, it gets automatic updates by the framework and receives a unique value on each
update. In this case, you do not have to implement ETag field updates.
If you choose an element as ETag field that is not automatically updated, you have to make sure that the ETag
value is updated on every modify operation via determinations.
Unmanaged Scenario
Unlike in managed scenarios, the application developer in the unmanaged scenario must always ensure that
the defined ETag field is correctly updated on every modify operation in the application code of the relevant
operations, including for updates by actions.
Implementation for Read Access to the ETag Field
As can be seen in the runtime diagrams of the ETag check-relevant operations (for example Update Operation
[page 91]), the ETag check during runtime can only be performed if the transactional READ operation to the
relevant ETag master entity is enabled.
For ETag master entities that means the READ operation must be defined and implemented, whereas for ETag
dependent entities, the READ by Association operation to the ETag master entity must be defined and
implemented.
Unless you are using groups in your behavior definition, the READ operation is always implicitly defined. You
cannot explicitly specify it. In groups, however, you have to assign the READ operation to one group.

Learn PUBLIC 37
The READ by Association must be defined in the behavior definition by the syntax association
AssocName, see ETag Definition [page 35]. It must be ensured that there is an implementation available for the
READ by Association definition.
Managed Scenario
In the managed scenario, the READ operation, as well as the READ by Association operation for each
entity is provided by the framework. The READ operation is always supported for each entity and the READ
by Association operation is supported as soon as the association is explicitly declared in the behavior
definition, see <method> FOR READ [page 145].
Unmanaged Scenario
In the unmanaged scenario, the application developer has to implement the read operations for the ETag
check. This includes the READ operation for the ETag master entity, as well as the READ by Association
operation from every ETag dependent entity to the ETag master entity. The corresponding method for READ
must be implemented in the behavior pool of the business object.
For a complete example, see Implementing the READ Operation for Travel Data [page 531] and Implementing
the READ Operation for Associated Bookings [page 541].
Related Information
Optimistic Concurrency Control [page 33]

ETag Definition [page 35]
2.3.2.1.2.2 Pessimistic Concurrency Control (Locking)
Pessimistic concurrency control prevents simultaneous modification access to data on the database by more
than one user.
Pessimistic concurrency control is done by exclusively locking data sets. The data set that is being modified by
one user cannot be changed by another user at the same time.
Technically, locking is ensured by using enqueue locks and global lock table entries. Before data is changed
on the database, the corresponding data set receives a lock entry in the global lock table. Every time a lock is
requested, the system checks the lock table to determine whether the request collides with an existing lock. If
this is the case, the request is rejected. Otherwise, the new lock is written to the lock table. After the change
request has been successfully executed, the lock entry on the lock table is removed. The data set is available to
be changed by any user again.
The lifetime of such an exclusive lock is tied to multiple factors:
• ABAP session: The enqueue lock is released once the ABAP session is terminated.
• LUW: The lock is released, once the RAP LUW is terminated with a COMMIT or ROLLBACK.
• Draft: In draft scenarios, the lock is not coupled to the LUW or the ABAP session, but depends on the
lifetime of the draft instance. The lock is released if the draft state for the instance expires, or, if the draft
instance is activated and the LUW is terminated.

38 PUBLIC Learn
The following diagram illustrates how the lock is set on the global lock table during an UPDATE operation.
Locking Process During UPDATE Operation
For the OData client that first sends a change request, the RAP transactional engine makes an entry in the
global lock table. During the time of the LUW, the second client cannot set a lock for the same entity instance
in the global lock tables and the change request is rejected. After the successful update of client 1, the lock is
removed and the same entity instance can be locked by any user.
For more information, see SAP Lock Concept.
Locking in Non-Draft Scenarios
If a lock is defined for a RAP BO entity, it is invoked during the runtime of the following modify operations:

• Create by Association Operation [page 97]
• Action [page 108].
The CREATE operation does not invoke the lock mechanism, as there is no active instance that can be locked
during the runtime of CREATE, see Create Operation [page 89].
To prevent simultaneous data changes in RAP business objects, the lock mechanism must be defined in the
behavior definition. Before instance data is changed by RAP-modifying operations, the entity instance is then
locked to prevent data from being changed by other users or transactions.
 Note
The locking mechanism does not check key values for uniqueness during CREATE. That means, the locking
mechanism does not prevent the simultaneous creation of two instances with the same key values.

Learn PUBLIC 39
In the managed scenario, such a uniqueness check is executed by the managed BO provider. In the
unmanaged scenario, the uniqueness check must be ensured by the application code provided by the
application developer, see Uniqueness Check for Primary Keys [page 32].
Managed Scenarios
In managed scenarios, the business object framework assumes all of the locking tasks. You do not have
to implement the locking mechanism in that case. If you do not want the standard locking mechanism by
the managed business object framework, you can create an unmanaged lock in the managed scenario. This
enables you to implement your own locking logic for the business object.
Unmanaged Scenarios
In unmanaged scenarios, however, the application developer has to implement the method for lock and
implement the locking mechanism including the creation of the lock object. The method for lock is called
by the RAP runtime engine before the relevant modifying operations are executed. The lock method calls the
enqueue method of a lock object that was previously created to enter the lock for the relevant entity instance
on the lock table. During the save sequence, after data has been successfully saved to the database, the lock is
removed during the cleanup method, see Save Sequence Runtime [page 225].
 Note
Whereas the managed BO runtime executes a uniqueness check for all dependent entities of the lock
master entity, an unmanaged implementation must ensure that newly created instances are unique.
Locking in Draft Scenarios
In scenarios with draft support, locking plays an even more crucial role during the draft business object life
cycle.
As soon as a draft instance is created for an existing active instance, the active instance receives an exclusive
lock and cannot be modified by another user. This exclusive lock remains for a determined time, even if the
ABAP session terminates. The duration time of the exclusive lock can be configured. Once the exclusive lock
expires after this duration time, the optimistic lock phase begins.
There are three cases that end the optimistic lock phase:
1. The user that created a draft instance for an active instance, and thus set an exclusive lock on the active
instance, discards the draft explicitly. This can be the case, if the data changes are not relevant anymore.
2. The draft is discarded implicitly, when
1. the draft remains untouched for a certain period of time. The lifetime of a draft is determined. If the
draft is not used for a certain period of time, the draft is discarded automatically by the life-cycle
service. By default this is done after 28 days.
2. the corresponding active instance is changed directly without using the draft (by the draft owner or by
a different user). This is possible during the optimistic lock phase. This change on the active instance
invalidates the draft document. Invalid drafts are discarded automatically after a determined time by
the draft life-cycle service.
3. a second draft is created for the corresponding active document.
3. The draft is resumed by the draft owner. If the user that created the draft continues to work on the
draft instance after the exclusive locking phase has ended, the draft can be resumed and the changes

40 PUBLIC Learn
are still available for the user. The optimistic locking phase ends as a new exclusive lock is set for the
corresponding active document.
Lock Lifetime of a Draft
Lock Master and Lock Dependent
In RAP, locking is not only restricted to the entity instance that is being modified. All related entities in the
business object structure are involved if one entity instance is getting locked. The locking structure is defined
in the behavior definition with the keywords lock master and lock dependent by. Every business object
that supports locking must have at least one lock master entity. Whenever a lock is requested for a specific
entity instance, its lock master and all dependent entity instances are locked for editing by a different user. This
mechanism ensures that relevant data is not changed concurrently.
 Note
Currently, only root entities can be lock masters.
Lock dependent entities must always have a lock master that is superior to them in the business object
structure.
The following diagram illustrates the structure of a business object with lock master and lock dependent
entities.

Learn PUBLIC 41
Locking Structure in RAP BO
If one entity instance of the blue BO tree receives a lock request, its lock master, the travel instance, is locked
and with it all dependent entity instances of this travel instance. That means if one of the blue instances is
locked, all blue instances are locked, but not the green instances of a different lock master entity instance.
Related Information
Lock Definition [page 42]

Lock Implementation [page 44]
2.3.2.1.2.2.1 Lock Definition
In RAP business objects, enqueue locks are used for pessimistic concurrency control. You define the lock in the
behavior definition of the business object entity.
Whenever the locking mechanism is defined for a business object entity in the behavior definition, the RAP
runtime engine calls the lock method to lock the respective data set and its lock dependencies. You define
which entities are lock masters and which entities are dependent on other entities. The lock mechanism is only
defined in the behavior definition in the interface layer. Its use for a business service must not be specified in a
projection behavior definition.
 Note
In managed scenarios, locking must always be enabled. Therefore, the lock definition is always included in
the template of the behavior definition.
The lock mechanism is defined using the following syntax elements in the behavior definition:
...

define behavior for CDSEntity [alias AliasedEntityName]

implementation in class ABAP_CLASS_NAME [unique]

...


42 PUBLIC Learn
lock master [page 43] [unmanaged [page 43]] | lock dependent by
_AssocToLockMaster [page 43]

...
{ ...
association _AssocToLockMaster { }

}
Lock Master
Lock master entities are locked on each locking request on one of their lock dependent entities. The
method FOR LOCK in unmanaged scenarios must be implemented for the lock master entities. The lock
implementation must include locking all dependent entities.
 Note
Currently, only root entities are allowed to be lock masters.
Lock dependent entities must always have a lock master that is superior to them in the business object
composition structure.
Lock Master Unmanaged
In the managed scenario, you can define an unmanaged lock if you do not want the managed BO framework
to assume the locking task. In this case the lock mechanism must be implemented in the method FOR LOCK
of the behavior pool, just like the lock implementation in the unmanaged scenario, see Unmanaged Scenario
[page 44].
Lock Dependent
An entity is defined as lock dependent if locking requests shall be delegated to its lock master entity. The
lock master entity of lock dependent entities is identified via the association to the lock master entity.
This association must be explicitly specified in the behavior definition, even though it is implicitly transaction-
enabled due to internal BO relations, for example a child/parent relationship. The association must also be
defined in the data model structure in the CDS views and, if needed, redefined in the respective projection
views.
 Note
In unmanaged business objects, the definition of lock dependent entities requires the implementation of
the read-by-association method. As locking on lock dependent entities are delegated to the lock master,
the read-by-association is used to get the authorization information from the master entity.
In managed business objects, the read-by-association is provided by the RAP managed BO provider.
Related Information
Pessimistic Concurrency Control (Locking) [page 38]

Lock Implementation [page 44]

Learn PUBLIC 43
2.3.2.1.2.2.2 Lock Implementation
If a lock mechanism is defined for business objects in the behavior definition, it must be ensured that the lock
is set for modifying operations.
Managed Scenario
The lock mechanism is enabled by default for business objects with implementation type managed. The
template for the behavior definition comes with the definition for at least one lock master entity and the
implementation of the lock mechanism is provided by the managed BO framework.
If you define an unmanaged lock for a managed business object, you have to implement the method FOR
LOCK, just like in the unmanaged scenario. It is then invoked at runtime.
 Note
In scenarios in which you have client-dependent database tables, but join client-independent fields from
other database tables to your CDS view, the managed BO runtime locks the instances specific to the client.
This means only the fields from the client-dependent database tables are locked. If you also want to lock
the client-independent fields, you have to implement an unmanaged lock.
Unmanaged Scenario
Just like any other operation in the unmanaged scenario, the lock must be implemented by the application
developer. To enable locking, the method FOR LOCK must be implemented.
For a complete example, see Implementing the LOCK Operation [page 544].
<method> FOR LOCK
2.3.2.1.2.2.2.1 <method> FOR LOCK
Implements the lock for entities in accordance with the lock properties specified in the behavior definition.
The FOR LOCK method is automatically called by the orchestration framework before a changing (MODIFY)
operation such as update is called.

44 PUBLIC Learn
Declaration of <method> FOR LOCK
In the behavior definition, you can determine which entities support direct locking by defining them as lock
master.
 Note
The definition of lock master is currently only supported for root nodes of business objects.
In addition, you can define entities as lock dependent. This status can be assigned to entities that depend
on the locking status of a parent or root entity. The specification of lock dependent contains the association
by which the runtime automatically determines the corresponding lock master whose method FOR LOCK is
executed when change requests for the dependent entities occur.
The declaration of the predefined LOCK method in the behavior definition is the following:

METHODS lock_method FOR LOCK

[IMPORTING] lock_import_parameter FOR LOCK entity.

The keyword IMPORTING can be specified before the import parameter. The name of the import parameter
lock_import_parameter can be freely selected.
The placeholder entity refers to the name of the entity (such as a CDS view) or to the alias defined in the
behavior definition.
Import Parameters
The row type of the import table provides the following data:
• ID fields
All elements that are specified as a key in the related CDS view.
 Note
The compiler-generated structures %CID, %CID_REF, and %PID are not relevant in the context of locking
since locking only affects persisted (non-transient) instances.
Changing Parameters
The LOCK method also provides the implicit CHANGING parameters failed and reported.
• The failed parameter is used to log the causes when a lock fails.
• The reported parameter is used to store messages about the fail cause.
You have the option of explicitly declaring these parameters in the LOCK method as follows:

IMPORTING lock_import_parameter FOR LOCK entity
CHANGING failed TYPE DATA
reported TYPE DATA.


Learn PUBLIC 45
Implementation of method FOR LOCK
The RAP lock mechanism requires the instantiation of a lock object. A lock object is an ABAP dictionary object,
with which you can enqueue and dequeue locking request. For tooling information about lock objects, see .
The enqueue method of the lock object writes an entry in the global lock tables and locks the required entity
instances.
An example on how to implement the method FOR LOCK is given in Implementing the LOCK Operation [page
544].
Related Information
Implicit Response Parameters [page 151]
2.3.2.1.3 Draft
You can draft-enable a business object to automatically persist transactional data in the backend. This
approach supports stateless communication for your applications.
Modern cloud-ready apps require a stateless communication pattern, for example to leverage cloud
capabilities like elasticity and scalability. Thus, there is no fixed backend session resource along a business
transaction for each user and the incoming requests can be dispatched to different backend resources, which
supports load balancing. On the other hand apps are stateful from end-user perspective. Business data that is
entered by the end user needs to be locked, validated and enriched via ABAP business logic on backend side.
The draft concept fills the gap between a stateless communication pattern and a stateful application by
applying REST principles:
• The draft represents the state and stores the transactional changes on the database in shadow tables. It is
an addressable resource, the exact copy of the active data that is currently being edited.
• Between two backend roundtrips, there is no running ABAP session waiting for the next roundtrip. The
execution might even be performed on different backend servers.
Draft-enabled applications allow the end user to store changed data in the backend and continue at a later
point in time or from a different device, even if the application terminates unexpectedly. This kind of scenario
needs to support a stateless communication and requires a replacement for the temporary in-memory version
of the business entity that is created or edited. This temporary version is kept on a separate database table and
is known as draft data. Drafts are isolated in their own persistence and do not influence existing business logic
until activated.

46 PUBLIC Learn
Draft and Active Data
In general, the draft implies the following advantages for your application:
• Save & Continue:

A draft allows you to stop processing and saving of business data at any time and to continue processing
later on, no matter if the data is in a consistent state or not.
• Staging:
The draft works like a staging area so that business data is isolated during processing and can finally be
activated, that is, saved to the active database.
• Device Switch:
As the draft persists the state of processing, it can be resumed with any device. For instance, you can edit
data on a laptop and continue from a mobile device.
• Collaboration:
With this release, only the exclusive draft is supported. This means that only the user who has created the
draft is able to process and activate it. A shared draft, however, allows dispatching the ownership of the
draft to a different user. Finally, the collaborative draft allows editing the same draft instance by multiple
users at the same time.
State Handling
Applications usually have a transactional state that buffers all changes of a current transaction until it is
committed by the application user. If the buffer state is consistent, the commit is accepted, if not, the whole
transaction is rejected. This all-or-nothing-approach prevents inconsistent data on the database table.
For smaller applications, sending the whole transactional state to the backend is unproblematic. The state can
be managed completely on the frontend side. We speak of frontend state handling in that case. However, in
case of complex backend-located business logic (especially legacy code), configuration, and data volume,
transferring everything to the frontend layer does not work for performance, maintenance, and security
reasons. Thus, backend state handling (draft) is required.

Learn PUBLIC 47
Basic Principles
• The main business logic is implemented on the active entity, for example with actions or feature control.
This behavior can be applied to draft entities in the same manner.
• There can be only up to one draft instance for each active instance at the same time.
• The primary key value of a draft and the corresponding active instance is the same.
Exclusive Draft
There are several approaches how draft instances that are created by different users can be accessed. The
current version of the ABAP RESTful Application Programming Model only supports the exclusive draft. A
draft exclusively belongs to the user that created the draft. Only this user is able to see and process the draft
instance.
The exclusive draft goes hand in hand with the exclusive lock. As soon as a user starts working on a draft, it sets
an exclusive lock. It is locked for other users. The exclusiveness is maintained for a defined period of time. After
that period, the draft goes into an optimistic lock phase. In this phase, the draft can either be resumed by the
same user or discarded, if other users take over the exclusive draft handling. For more information, see Locking
in Draft Scenarios [page 40]
Draft in the ABAP RESTful Application Programming Model
Draft is an option that you can use for application development with both, the managed and unmanaged
implementation type and also with mixed scenarios, for example, managed with unmanaged save. In all
scenarios, the draft is managed. That means, it is handled by the RAP runtime framework. You, as an
application developer, do not need to care about how draft data is written to the draft database table. This
is done for you. Of course, adding draft capabilities to your business object might imply changes in your
business logic also for the processing of active data that you are responsible of. In addition, RAP also offers
implementation exits for cases in which you need business service-specific draft capabilities that impact the
draft handling.
Restrictions
Draft-Enabled Business Objects
• There can be locking conflicts for the active provider if an instance that was activated is locked again in the
same transaction. This is because the durable lock of the active instance remains after the activation of a
draft instance.
• Every child entity in a CDS composition hierarchy must be represented in the behavior definition if a
behavior definition for the root entity exists and defines a draft-enabled RAP business object.

48 PUBLIC Learn
Unmanaged Business Objects with Draft
There are features that can be defined in the behavior definition of an unmanaged business object and thus
used on active instances, but not on draft instances:
• You can't execute the following operations on draft instances:

• Create-enabled associations that aren't modeled as part of a composition
• Direct creates on child instances
• The aggregated admin data fields aren't updated automatically when a draft instance is saved.
• Associations that use NOT in the binding condition can't be draft-enabled.
• There's no support for transactional draft-enabled associations leading from draft to active instances.
• Client-independent CDS views aren't supported.
2.3.2.1.3.1 Draft Design Time
Given the fact that the runtime of a draft business object differs significantly from a non-draft business object,
it comes with no surprise that there are also quite some differences with regard to the design time of a draft
business object.
The addition with draft in the behavior definition defines a draft business object. As soon as the business
object is draft-enabled with this syntax element, you have various other options to use draft capabilities on
certain actions and operations. For more information, see Draft Business Object [page 49].
As draft instances are stored independently of active instances, a separate database table, the draft table,
must be created. This draft table must be explicitly stated in the behavior definition and can be generated from
there. For more information, see Draft Database Table [page 50].
To control the state of the active BO data, you use the total ETag, which must also be defined in the behavior
definition. For more information, see Total ETag [page 51].
To enable that an association retrieves active data if it is followed from an active instance and draft data if it
is followed from a draft source instance, the associations must be draft-enabled. For more information, see
Draft-Enabled Associations [page 54].
2.3.2.1.3.1.1 Draft Business Object
The draft capability for a draft business object is defined in the behavior definition.
You can build draft business objects from scratch, or you can draft-enable existing business objects with both
implementation types managed or unmanaged. The draft-indicating syntax element with draft is added at
the top of the behavior definition as it does not belong to a certain entity of the BO, but concerns the whole BO.
You cannot implement draft capabilities for single BO entities.
For a detailed syntax description, see CDS BDL - with draft (ABAP - Keyword Documentation).
In draft business objects, the handling of the draft instances is always managed by the RAP runtime
framework, no matter if your business object is unmanaged or managed. That means, the draft life-cycle is

Learn PUBLIC 49
determined by the RAP draft runtime and specific draft actions are implicitly available for the draft business
object.
Runtime Aspects
If you use %tky to address the application key components of an entity, you do not have to change your
business logic implementation when draft-enabling the business object. The derived type component %tky
automatically includes the draft indicator %IS_DRAFT for draft business object to distinguish draft instances
from active instances. Like this, the business functionality runs smoothly without adapting your code after
draft-enabling your business object.
If you use %key in your business logic implementation, you have to revise the complete implementation
when draft-enabling the business object. This derived type component only comprises the application key
component. In this case, the runtime is not able to distinguish between draft and active instances.
 Note
The recommendation is to only use %tky in your business logic implementation for both, active-only and
draft business object.
For more information, about the components of derived types, see Components of BDEF Derived Types (ABAP
- Keyword Documentation).
2.3.2.1.3.1.2 Draft Database Table
Draft business objects need two separate database tables for each entity. One for the active persistence and
one for storing draft instances.
The draft data is stored on a separate draft table to match the different access patterns of draft and active
data. While the active database table stores many instances, but rarely has access on these instances, it is vice
versa for the draft table. With two separate tables, the performance can be adapted to the different approaches
of the two tables more easily. During runtime, every request is marked whether it is intended for the draft table,
or for the active with the draft indicator %IS_DRAFT.
With using a separate database table for the draft information, it is guaranteed that the active persistence
database table remains untouched and thus consistent for existing database functionality.
 Note
Although draft database tables are usual ABAP Dictionary database tables and there are no technical
access restrictions, it is not allowed to directly access the draft database table via SQL, neither with reading
access nor writing access. The access to the draft database table must always be done via EML, with which
the draft metadata get updated automatically.
The fields of the draft database table are derived from the corresponding CDS view entity. In addition,
it contains some technical information the RAP transactional engine needs to handle draft. The technical
information is added with the draft admin include.

50 PUBLIC Learn
For more information, see CDS BDL - draft table (ABAP - Keyword Documentation).
Draft Admin Include
...

define structure sych_bdl_draft_admin_inc {
draftentitycreationdatetime : sych_bdl_draft_created_at;
draftentitylastchangedatetime : sych_bdl_draft_last_changed_at;
draftadministrativedatauuid : sych_bdl_draft_admin_uuid;
draftentityoperationcode : sych_bdl_draft_operation_code;
hasactiveentity : sych_bdl_draft_hasactive;

draftfieldchanges : sych_bdl_draft_field_changes;}
The draft table can be generated automatically via a quick fix in the behavior definition, which is offered as soon
as the business object is draft-enabled with the syntax with draft.
For more information, about the syntax in the behavior definition, see CDS BDL - entity behavior
characteristics (ABAP - Keyword Documentation).
In case the draft database table does already exist, the quick fix completely overwrites the table.
Database Table Generation
Whenever you change the active data model in the active database table, you have to regenerate the draft
table to align them. The behavior definition offers a quick fix for regeneration, but it is the responsibility of the
application developer to keep the two database tables synchronized. When regenerating the draft database
table it completely overwrites the existing one.
2.3.2.1.3.1.3 Total ETag
The total ETag is a designated field in a draft business object to enable optimistic concurrency checks during
the transition from draft to active data.
Draft business objects require a total ETag. This designated field on the database table is updated by the RAP
runtime framework as soon as an active instance is changed. The total ETag always refers to the complete BO.
As soon as an instance of any BO entity is changed, the total ETag is updated. Its value is compared when
resuming a draft instance to ensure that the active data has not been changed after the exclusive lock has
expired. Thus, the total ETag is important for optimistic concurrency control during the transition from draft to
active data. The total ETag is defined in the behavior definition.
Total ETag Definition
[implementation] unmanaged|managed|abstract [in class class_name unique];

with draft;

define behavior for CDSEntityName [alias AliasName]

Learn PUBLIC 51

implementation in class BehaviorImplementationClass unique
persistent table ActiveDBTable
draft table DraftDBTable
lock master
total etag TotalETagField
etag master LocalETagField

...
The total ETag field is defined on the lock master entity (currently identical to root entity) and optimistically
controls the whole business object regarding concurrency on the active data.
 Note
The definition of the total ETag is only possible directly after the lock master definition in the behavior
definition.
The RAP managed framework is able to update the total ETag field automatically on saving a draft instance if
the following conditions are fulfilled:
• The field is annotated in CDS with the annotation @Semantics.systemDateTime.lastChangedAt:

true with the precondition that the field has a date-compatible type).
• The total ETag field is included in the field-mapping prescription in the behavior definition, if the names on
the database table and in CDS are different. .
If you don’t enable the framework to update the field, you have to include your own updating logic in the
business logic of the BO.
 Note
Total ETag and ETag master/dependent are two sides of the same medal. For a smoothly running
application, you need both ETags.
The total ETag is used for edit-drafts, a draft that has a corresponding active instance. As soon as the
exclusive lock expires and an edit-draft is resumed, the total ETag value of the draft instance is compared to
the total ETag value on the active instance. Only if the values coincide can the draft be resumed. The total
ETag is compared for all entities of a BO. Draft business objects requires a total ETag to ensure optimistic
concurrency comparison.
The ETag master/dependent concept ensures that the end user of an OData service only changes
instances with the state that is displayed on the UI. Hence, the ETag master/dependent prevents changes
of the BO that are not noticed by the OData consumers. With ETag master, each BO entity can be
checked independently. ETag master fields are required to provide optimistic concurrency locking for
OData consumers. For more information, see Optimistic Concurrency Control [page 33].
Since the total ETag and the ETag master serve different purposes, it’s recommended to use separate fields
to make use of the different functionalities. If you use the same field for the total ETag and the ETag master
for a BO with several child entities, you need to consider that the total ETag changes (and thus the ETag
master) whenever a child entity is updated (and saved).

52 PUBLIC Learn
2.3.2.1.3.1.4 Draft Actions
Draft actions are actions that are implicitly available for draft business objects as soon as the business object is
draft-enabled. In strict mode, they have to be explicitly declared in the behavior definition.
Draft actions can only be specified for lock master entities, as they always refer to the whole lockable subtree
of a business object.
For syntax information, see CDS BDL - draft actions (ABAP - Keyword Documentation).
Draft actions are needed for specific occasions in business services with draft. Draft actions can be completely
handled by the RAP framework, in managed and in unmanaged implementation scenarios. Nevertheless,
an application developer can add additional implementation for each draft action if the addition with
additional implementation is used. In this case, the additional implementation is executed on the same
instance version (draft or active), on which the default draft action is executed. For example, the additional
implementation for Edit receives the transactional key with the draft indicator off, as the Edit action is executed
on the active instance.
Draft Action Edit

The draft action EDIT copies an active instance to the draft database table. Feature and authorization control is
available for the EDIT, which you can optionally define to restrict the usage of the action.
For more information, see Edit Action [page 59].
Draft Action Activate

The draft action ACTIVATE is the inverse action to EDIT. It invokes the PREPARE and a modify call containing
all the changes for the active instance in case of an edit-draft, or a CREATE in case of a new-draft. Once the
active instance is successfully created, the draft instance is discarded.
In contrast to the draft action Edit, the Activate does not allow feature or authorization control.
Authorization is not available as the Activate only transfers the state of the draft buffer to the active buffer.
Authorization is controlled when the active instance is saved to the database.
For more information, see Edit Action [page 64].
Draft Action Discard

The draft action DISCARD deletes the draft instance from the draft database table. No feature or authorization
control can be implemented.
For more information, see Discarding Root Draft Instances [page 70].
Draft Determine Action Prepare

The draft determine action PREPARE executes the determinations and validations that are specified for it in the
behavior definition. The PREPARE enables validating draft data before the transition to active data.
In the behavior definition, you must specify which determinations and validations are called during the prepare
action. Only determinations and validations that are defined and implemented for the BO can be used.
For more information, see Preparing Draft Instances for Activation [page 73].
Draft Action Resume

The draft action RESUME is executed when a user continues to work on a draft instance whose exclusive lock for
the active data has already expired. It recreates the lock for the corresponding instance on the active database

Learn PUBLIC 53
table. On a Fiori Elements UI, it is invoked when reopening and changing a draft instance whose exclusive lock
is expired.
In case of a new draft, the same feature and authorization control is executed as defined for a CREATE. In case
of an edit-draft, the same feature and authorization control is executed like in an Edit.
If you want to implement your own logic for the resume action, it must be implemented by the application
developer in the related behavior implementation class, just like any other action, see Action Implementation
[page 106].
For more information about the Resume, see Resuming Locks for Draft Instances [page 75].
2.3.2.1.3.1.5 Draft-Enabled Associations
A draft-enabled association retrieves active data if it is followed from an active instance and draft data if it is
followed from a draft source instance.
The intended behavior for all associations within the composition tree of a draft business object is to be
draft-enabled, so that the associations always lead to the target instance with the same state (draft or active).
 Example
On creating a child instance of a draft root instance by a create-by-association, you want to create a
draft instance. Creating an active child instance would lead to BO-internal inconsistencies. That is why, all
compositions are automatically draft-enabled.
As soon as you draft-enable a business object by adding with draft to the behavior definition, all BO-internal
associations are automatically draft-enabled. To make this behavior explicit, the behavior prompts you to
specify the compositions within a draft BO with with draft.
For syntax information, see > associations (ABAP - Keyword Documentation).
2.3.2.1.3.1.6 Draft Query Views
Draft query views allow you to define READ access limitations for draft data based on the data control language
(DCL).
About Draft Query Views
A DCL offers the possibility to restrict read access to the data that is returned from a CDS View. A RAP
business object with draft capabilities is based on an active database table that reflects the state of the latest
saved to the database and a draft table that stores the draft data until it's written to the persistent database.
In general, DCLs defined for the CDS views choosing from the active database table aren't applied to draft data.
Draft query views allow you to define read access restrictions for draft data.

54 PUBLIC Learn
Draft Query View Definition
The following example is based on the sample scenario /DMO/FLIGHT_REUSE_AGENCY.
A draft query view is a CDS view that selects directly from a draft database table. This CDS view must always
contain all fields contained in the draft table including administrative fields.
Defining the Draft Table

In the following example, the draft table defined in the base behavior definition is /dmo/agency_d. It contains
the required fields for a travel agency like an agency name or address, a well as adminitrative data like
localcreatedby: Expand the following code sample to view the source code of the draft table /DMO/
AGENCY_D.

@EndUserText.label : 'Draft table for entity /DMO/R_AGENCY'
...
define table /dmo/agency_d {
key agencyid : /dmo/agency_id not null;
name : /dmo/agency_name;
street : /dmo/street;
postalcode : /dmo/postal_code;
city : /dmo/city;
countrycode : land1;
phonenumber : /dmo/phone_number;
emailaddress : /dmo/email_address;
webaddress : /dmo/web_address;
attachment : /dmo/attachment;
mimetype : /dmo/mime_type;
filename : /dmo/filename;
localcreatedby : abp_creation_user;
localcreatedat : abp_creation_tstmpl;
locallastchangedby : abp_locinst_lastchange_user;
locallastchangedat : abp_locinst_lastchange_tstmpl;
lastchangedat : abp_lastchange_tstmpl;
"%admin" : include sych_bdl_draft_admin_inc;
}

Defining a Draft Query View

The CDS View /DMO/R_AgencyDraft selects diretly from /dmo/agency_d and must contain all elements
of the draft table. Also the fields from the %admin include are part of the CDS View. For more details about
the elements of draft tables, see Draft Database Table [page 50]. The /DMO/R_AgencyDraft can define read
access controls like for other read use cases, which is then applied when data is read from the draft table.
For more general information about access controls, see .
 Expand the following code sample to view the source code of the draft query view /DMO/R_AgencyDraft.

@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: 'Draft Query View: Agency'
define view entity /DMO/R_AgencyDraft
as select from /dmo/agency_d as Agency
{
key agencyid as Agencyid,
key draftuuid as Draftuuid,
name as Name,
street as Street,
postalcode as Postalcode,
city as City,

Learn PUBLIC 55
countrycode as Countrycode,
phonenumber as Phonenumber,
emailaddress as Emailaddress,
webaddress as Webaddress,
attachment as Attachment,
mimetype as Mimetype,
filename as Filename,
localcreatedby as Localcreatedby,
localcreatedat as Localcreatedat,
locallastchangedby as Locallastchangedby,
locallastchangedat as Locallastchangedat,
lastchangedat as Lastchangedat,
draftentitycreationdatetime as Draftentitycreationdatetime,
draftentitylastchangedatetime as Draftentitylastchangedatetime,
draftadministrativedatauuid as Draftadministrativedatauuid,
draftentityoperationcode as Draftentityoperationcode,
hasactiveentity as Hasactiveentity,
draftfieldchanges as Draftfieldchanges
}

Defining Draft Query Views in the Behavior Definition

The draft query view is included in the behavior definition with the keyword query after the draft table name.
Then the respective draft query view is identified as draft query view by the RAP query engine. The behavior
definition /DMO/R_AgencyTP specifies /DMO/R_AgencyDraft as draft query view for the Agency RAP BO.
 Expand the following code sample to view the source code of the behavior definition /DMO/R_AgencyTP.

define behavior for /DMO/R_AgencyTP alias /DMO/Agency
persistent table /dmo/agency
draft table /dmo/agency_d query /DMO/R_AgencyDraft
{...}

Draft Query Views in RAP Extensibility Scenarios
If the original BO is draft-enbaled and release contracs are used, using draft query views is mandatory during
the extensibility-enablement.
For more information, see Extensibility-Enablement for CDS Data Model Extensions [page 952].
2.3.2.1.3.2 Draft Runtime
RESTful applications require a constant stateless communication with the backend to prevent that transient
data is lost when a user session ends. Data changes are constantly persisted on the draft database tables and
are therefore always retrievable from any device. The fact that two database tables are involved in the runtime
of a draft business object requires an elaborate lifecycle of data. All data undergo several states while being
processed by a draft business object. There are three distinct states that need to be distinguished.
For initial data that is not yet persisted on the active database table, we speak of new-draft instances.
New-draft instances do not have a corresponding active instance. They are created using the modify CREATE
operation having the draft indicator %IS_DRAFT set to true. The draft indicator is automatically available as
derived type when working with the transactional key %tky.

56 PUBLIC Learn
As soon as a draft instance is transferred from the draft database table to the persistent table, the draft
instance is activated. The data that is stored on the persistent database table is called active data. Active
instances come into being by activating new-draft instances or by using the modify CREATE operation and
setting the draft indicator %IS_DRAFT to false.
Edit-drafts always exist in parallel to the corresponding active data. Whenever active data is edited, the whole
active instance is copied to the draft table. All modifications are saved on the draft database table before
the changes are finally applied to the active data on the active database table again. Edit-draft instances are
created by using the EDIT action on active instances.
The following diagram illustrates the lifecycle of draft and active data and their transitions from one state to the
other.
Lifecycle of Draft and Active Data
When working with draft instances, you always set an exclusive lock for this instance. In case of an edit-draft,
that means that the corresponding active instance cannot be modified by any other user. In case of a new-
draft, the primary key number is locked exclusively to avoid duplicate key failure on the database. For the
time of the exclusive lock phase, it is not possible to create neither an active, nor a draft instance with the
same key. After the exclusive lock has expired, the draft is in an optimistic lock mode, in case the user starts
processing again, the draft resume action is automatically invoked. It locks the corresponding active instance
again, compares the total ETag and if successful, the draft can be continued in exclusive mode.
You can always send requests for draft instances or active instances. Accessing draft instances via EML or
OData works exactly like accessing active instances. To distinguish if the requests are aimed at draft or active
instances, the RAP runtime framework evaluates the draft indicator %IS_DRAFT. This draft indicator must be
set for every request, which can be processed on active or draft instances. In OData, this technical primary key
component is mapped to isActiveInstance.
On a UI, modifications of data in a draft BO always take place on the draft instance (except for actions). Only
in case of activation via the activate action are the changes applied to the corresponding active instance. The
transition from draft to active data and vice versa requires specific actions that process tasks that are not
relevant in a non-draft business object. These actions are explained best when considering the lifecycle of a
draft and active data in detail.
Creating Draft Data [page 58]
Creating Active Data [page 64]
Changing and Reading Instances of a Draft BO [page 67]

Learn PUBLIC 57
Deleting Instances of a Draft BO [page 70]
Preparing Draft Instances for Activation [page 73]
Resuming Locks for Draft Instances [page 75]
Saving Data to the Database [page 77]
2.3.2.1.3.2.1 Creating Draft Data
You create draft instances by creating new-drafts or by editing active instances.
As the preceding diagram suggests, there are two options to create draft data:
Modify CREATE Request
By using the modify operation for CREATE, you create a new-draft instance, a draft instance that has no
corresponding active instance. For such a create request, the draft indicator must be set to true. Like
a CREATE for active instances, the RAP runtime sets an exclusive lock for the instance and triggers any
determination on modify with trigger CREATE. On creating a new instance the uniqueness of the primary keys
must be ensured. Otherwise, if duplicate keys reach the active database table, the whole request is denied. For
more information about an early uniqueness check, see Uniqueness Check for Primary Keys [page 32].
On a Fiori Elements UI, using the Create button executes a CREATE request with the draft indicator set to true.
It is not possible to directly create active instances by using the Create button on a Fiori UI.
Via EML, however, it is possible to distinguish requests to create draft data and requests to create active data.
To create draft instances, the draft indicator must be set to true:
MODIFY ENTITIES OF BusinessObjectName

ENTITY BO_Entity
CREATE FROM
VALUE #( ( %is_draft = if_abap_behv=>mk-on "positive draft
indicator
%control-FieldName = if_abap_behv=>mk-on

58 PUBLIC Learn
%data-FieldName = 'Value') )
REPORTED DATA(create_reported)
FAILED DATA(create_failed)

MAPPED DATA(create_mapped).
Edit Action
By executing the draft action EDIT on an active instance, you create an edit-draft instance, a draft instance that
has a corresponding active instance on the persistent database. An edit action creates a new draft document
by automatically copying the corresponding active instance data to the draft table. At the same time, the EDIT
triggers an exclusive lock for the active instance. This lock is maintained until the durable lock phase of the
draft ends, which is either when the draft is activated, or when the durable lock expires after a certain time.
The edit action has a parameter with which you can determine whether editing an active instance for which
a draft already exists is possible or not. Having set the parameter preserve_changes to true, your action
request is rejected if a draft already exists. If preserve_changes is set to false (default setting), the edit
action is executed. That means, the active instance is copied to the draft database table and the existing draft
is overwritten with the values of the active data. In that case, you lose the changes that anyone has done on the
existing draft instance. Hence, it is recommended to always include the parameter in your action requests.
For edit action requests, the draft indicator does not have to be set, as the EDIT is always executed on the
active instance.
Instance authority and feature control are both checked for the action. To implement application-specific
controls, define the EDIT action in the behavior definition and implement the method for features or for
authorization in the behavior pool.
On a Fiori Elements UI, the edit action is triggered when choosing the Edit button, which is only available on
the object page of an active instance. Triggering the edit action from the UI always includes the parameter
preserve_changes set to true.
In this case, OData sends a POST request for action execution of the EDIT, which is then carried out by the RAP
runtime framework.
The edit action can be executed via EML, just like any other business logic action:

ENTITY BO_Entity
EXECUTE Edit FROM
VALUE #( ( %key-element1 = 'KeyValue'
%param-preserve_changes = 'X' ) )
REPORTED DATA(edit_reported)
FAILED DATA(edit_failed)

MAPPED DATA(edit_mapped).

Learn PUBLIC 59
2.3.2.1.3.2.1.1 Runtime CREATE Draft
This topic illustrates the execution order of possible runtime activities after executing a modify request for
CREATE.
Not all activities of the following runtime diagram are always present. It depends on the BO's behavior that is
specified in the behavior definition.

60 PUBLIC Learn
Learn PUBLIC 61
2.3.2.1.3.2.1.2 Runtime Edit Action
EDIT.

62 PUBLIC Learn
Learn PUBLIC 63
2.3.2.1.3.2.2 Creating Active Data
You create active data by activating draft data or by directly creating an active instance with a modify CREATE
request.
Modify CREATE Request
Creating a new active instance for a draft BO from scratch is not possible from a Fiori Elements UI. Every create
request (OData POST) is sent without the OData draft indicator IsActiveEntity. This is interpreted as false
and the RAP runtime framework creates a new-draft instance.
Via EML, however, it is possible to distinguish modify CREATE requests for active instances and for draft
instances. The syntax for directly creating an active instance via EML is the following:

ENTITY BO_Entity
CREATE FROM
VALUE #( ( %is_draft = if_abap_behv=>mk-off "negative draft
indicator
%control-FieldName = if_abap_behv=>mk-on
%data-FieldName = 'Value') )
REPORTED DATA(create_reported)

MAPPED DATA(create_mapped).
The runtime of a modify request for active instances can be seen in Create Operation [page 89].
 Note
When saving the data from the application buffer on the persistent database table via COMMIT ENTITIES
or BO-internal triggers of the save sequence, validations are executed and can prevent modification
requests if the data is not consistent, see Save Sequence Runtime [page 225].
Activate Action
By executing the draft action ACTIVATE on a draft instance, you copy the draft instance to the active
application buffer. It invokes the PREPARE and a modify request to change the active BO instance according to

64 PUBLIC Learn
the state of the draft instance. Once the active instance is successfully created or updated, the draft instance is
discarded. The activate action does not save the active instance on the database. The actual save is executed
separately, either by COMMIT ENTITIES via EML or by calling the save sequence in case of OData.
The activate action is only possible on draft instances.
On a Fiori Elements UI, the activate action is triggered when choosing the Save button after editing data. The
Save button also triggers the save sequence after the activation.
For executing the ACTIVATE via EML, the following syntax is used:

ENTITY BO_Entity
EXECUTE Activate FROM
VALUE #( ( %key-FieldName = 'Value' ) )
REPORTED DATA(activate_reported)
FAILED DATA(activate_failed)

MAPPED DATA(activate_mapped).
 Note
The modify request to adapt the active instance according to the state of the draft BO-instance entails
every operation that was done on the draft instance.
In case of an unmanaged implementation scenario, it is just one modify request that is passed to the active
unmanaged provider. This can lead to problems if a child draft instance is deleted; and in the same logical
unit of work, a new child instance is created with the same key. As the order of the modify requests for
delete and create by association is not determined, it can happen that the unmanaged provider executes
the CREATE_BY_ASSOCIATION before the child instance with the same key is deleted. This scenario raises
a short dump during runtime. To prevent this, combine the handler methods for delete and create by
association in one handler method in unmanaged scenarios with draft. In this single handler method,
strictly define the order so that first, the DELETE is executed and then the CREATE_BY_ASSOCIATION.
2.3.2.1.3.2.2.1 Runtime Activate Action
ACTIVATE.

Learn PUBLIC 65
66 PUBLIC Learn
 Note
• (1) The detailed runtime of this step is illustrated in the runtime diagrams of the operations in non-draft
BOs. See
Create Operation [page 89],
Update Operation [page 91],
Delete Operation [page 94],
Create by Association Operation [page 97],
Action Runtime [page 108].
• (2) The detailed runtime of this step is illustrated in the runtime diagram of the save sequence. See
Save Sequence Runtime [page 225].
2.3.2.1.3.2.3 Changing and Reading Instances of a Draft BO
You execute actions on, update, or read instances of a draft BO by sending a modify or read request. The draft
indicator decides whether the active or the draft instance is processed.
Life Cycle of Draft and Active Data
Updating Instances of a Draft BO
Fields of draft BO instances are changed by the modify request for UPDATE. Depending on the draft indicator,
the request changes the active or the draft instance.
On a Fiori Element UI, the UPDATE with the draft indicator set to true is called whenever input fields on the
UI are filled. After leaving the input field, the modify request for UPDATE is sent and the draft save sequence is
triggered to save the draft on the draft database table.
The UPDATE with the draft indicator set to false is called by the activate action, after the prepare action
is executed on an edit-draft instance. Hence, the modify UPDATE on active entities is hidden under the
functionality of the Save button, see Activate Action [page 64].
Via EML you determine whether you want to update an active or a draft instance by setting the draft indicator
%IS_DRAFT = if_abap_behv=>mk-on/off.

Learn PUBLIC 67
Each modify request for UPDATE, no matter if aimed at draft or active instances, goes through the same
runtime process as in scenarios without draft, including locking, determination triggers etc. For more
information about the runtime orchestrations, see Update Operation [page 91].
Executing Actions on a Draft BO
Actions on draft business objects are executed by modify requests for action execution. Depending on the draft
indicator, the action is executed on the active or the draft instance.
A Fiori Elements UI sends requests for action execution whenever you choose an action button that is defined
for an application-specific action. Depending on whether this is done on a draft or an active instance, the draft
indicator is set to true or false.
In the EML syntax for executing actions, you can also set the draft indicator to indicate whether you want to
execute the action on a draft or an active instance.
Each modify request for action execution, no matter if aimed at draft or active instances, goes through the
same runtime process as in scenarios without draft, including locking, determination triggers etc. For more
information about the runtime orchestrations of actions, see Action Runtime [page 108].
Static actions are always delegated to the active provider. Static actions contain an additional parameter that
indicates whether the action produces a draft or an active instance.
Reading Instances of a Draft BO
Business object instances of a draft BO are read by a read request. Depending on the draft indicator, the
request reads the active or the draft instance.
In the reading request via EML, set the draft indicator to determine whether active or draft instances are read.
On a Fiori Elements UI, the transactional read operation is always used when buffer information is relevant for
the next operation. The draft indicator decides whether the draft or the active instance is read from the buffer.
2.3.2.1.3.2.3.1 Runtime MODIFY Draft
UPDATE, DELETE, actions, and create by association.

68 PUBLIC Learn
Learn PUBLIC 69
2.3.2.1.3.2.4 Deleting Instances of a Draft BO
You delete instances of a draft BO by using the modify request for delete on active instances or the discard
action for draft instances.
Discarding Root Draft Instances
By executing the draft action DISCARD, you delete the draft instance from the draft database table. In addition,
possible exclusive locks are released. The DISCARD can be executed on new-drafts and on edit-drafts. Apart
from releasing the lock, the action has no impact on the active instance. It is just the draft data that is deleted.
On a Fiori Elements UI, the draft action DISCARD is invoked by choosing Cancel. The discard action is always
enabled. Neither dynamic feature control, nor authority control can restrict it. A user can always make a draft
undone.
Via EML you discard draft instances with the following syntax:

ENTITY BO_Entity
EXECUTE Discard FROM
REPORTED DATA(discard_reported)
FAILED DATA(discard_failed)

MAPPED DATA(discard_mapped).
You cannot delete a draft instance with a DELETE request. A delete request on a draft instance fails.
Deleting Root Active Instances
As in non-draft business objects, persisted data can be deleted by using the standard operation DELETE.
On a Fiori Elements UI, the DELETE is called when choosing Delete button. If you choose Delete for an instance
that has an active and a draft representation, the UI sends a request for DELETE on the active instance and one
for DELETE on a draft instance. The DELETE on the draft instance is BO-internally considered as a DISCARD.

70 PUBLIC Learn
The syntax for deleting instances is the following:

ENTITY BO_Entity
DELETE FROM
VALUE #( ( %key-FieldName = 'Value'
%is_draft = if_abap_behv=>mk-on|off "draft indicator) )
REPORTED DATA(delete_reported)
FAILED DATA(delete_failed)

MAPPED DATA(delete_mapped).
Each modify request for DELETE goes through the same runtime process as in scenarios without draft,
including locking, determination triggers etc. For more information about the runtime orchestrations, see
Delete Operation [page 94].
Deleting and Discarding Instances of Child Entities
Deleting an active child instance, with a delete request that has the draft indicator set to true, directly deletes
the active child instance without affecting the other entities of the business object.
Deleting draft child instances, with a delete request that has the draft indicator set to false, deletes the draft
child instance. Once the root entity, and with it all related child entities, is activated, the active child instance
is deleted as well. During activation, it is the state of the whole composition tree that is passed to the active
buffer. The activate action provides the suitable modify request for the changes that are done on the draft BO.
2.3.2.1.3.2.4.1 Runtime Discard Action
DISCARD.

Learn PUBLIC 71
72 PUBLIC Learn
2.3.2.1.3.2.5 Preparing Draft Instances for Activation
Before draft instances become active, they are checked by the validations and determinations that are
specified for the draft determine action prepare in the behavior definition.
The draft determine action PREPARE is executed automatically at least once before draft data is activated
during the activate action. It ensures that the draft instance is consistent by calling the validations and
determinations on save that are specified for the prepare action in the behavior definition. The prepare action
can only be executed on draft instances.
On a Fiori Elements UI, the action is invoked by choosing Save on a draft instance. The UI then sends the
request for PREPARE before executing the action ACTIVATE.
 Note
When choosing Save on the UI, the prepare action is executed at least twice. First, the UI requests the
PREPARE directly, and then it is called during the execution of the activate action.
Via EML the prepare action is executed with the following syntax:

ENTITY BO_Entity
EXECUTE Prepare FROM
REPORTED DATA(prepare_reported)
FAILED DATA(prepare_failed)

MAPPED DATA(prepare_mapped).
As the PREPARE can only be executed on draft instances, the draft indicator cannot be set for the action.
The prepare action only fails if the instance with the given key is not found. If the validations that are called
by the PREPARE detect inconsistencies, the issues are only written in the REPORTED table, but the FAILED
table remains empty. A possible COMMIT ENTITIES after the prepare action succeeds if the PREPARE does not
return any failed keys, even if the validations within the PREPARE return failed keys.
 Note
Only transition messages from validations are handed over to the REPORTED table of the prepare action,
state messages are not. State messages describe the state of an instance and saved together with the
instance. They are returned if a READ is executed on the respective instance.

Learn PUBLIC 73
2.3.2.1.3.2.5.1 Runtime Prepare Action
PREPARE.

74 PUBLIC Learn
2.3.2.1.3.2.6 Resuming Locks for Draft Instances
The draft action resume is called automatically if the work on a draft instance with an expired lock is resumed.
The draft action RESUME is executed automatically whenever there is a modification on a draft instance whose
exclusive lock has expired. It recreates the lock for the corresponding active instance on the active database
table.
On a Fiori Elements UI, the action is invoked when the user chooses a draft instance and continues with editing
data if the exclusive lock is expired. This is the case when the user chooses an own draft and continues with
editing the input fields. An UPDATE on the draft instance is sent, which invokes the resume action if the lock has
expired.
 Note
If the user chooses a foreign draft and chooses the Edit button to edit any input fields, it is only possible
to discard the foreign draft completely and start with a new draft based on the current active data. In this
case, the user gets a pop-up with the warning that any changes done by the other user are lost.
Via EML the resume action is executed with the following syntax:

ENTITY BO_Entity
EXECUTE Resume FROM
REPORTED DATA(resume_reported)
FAILED DATA(resume_failed)

MAPPED DATA(resume_mapped).
When resuming draft instances it must be ensured that the primary keys of the instance are still unique. It
might have happened that other users created an instance with the same primary keys during the optimistic
lock phase. For more information, see Uniqueness Check for Primary Keys [page 32].
During the execution of a resume action, the framework runs the same checks as for a MODIFY CREATE in case
of a new-draft, and the same checks as for an EDIT in case of an edit-draft.

Learn PUBLIC 75
2.3.2.1.3.2.6.1 Runtime Resume Action
RESUME.

76 PUBLIC Learn
2.3.2.1.3.2.7 Saving Data to the Database
Persisting business object instances is done during the save sequence. Draft instances are automatically saved
on the draft database by the RAP runtime framework.
Depending on the state of the instance you want to save, the SAVE is done on the draft database table or the
active database table. Active instances are saved on the active database tables; draft instances are saved on
the draft database table.
Via EML, the statement COMMIT ENTITIES triggers the process to save the data on the database. It saves the
state of the buffer, draft instances to the draft database table and active instances to the active database table.
For active instances, the save sequence is triggered. For draft instances, only the actual save to the database is
done. No validations or determinations on save are called.
Saving Active Instances

For saving active data to the persistent database table, the data of the instance must be consistent in the
buffer. The actual SAVE is done during the save sequence, which is triggered after the interaction phase, see
On a Fiori Elements UI, the save sequence is triggered by choosing the Save button on the UI. After the
PREPARE and the ACTIVATE are executed successfully, the save sequence is triggered automatically.
Saving Draft Instances

Draft data does not have to be in a consistent state to be saved. No validations are triggered when saving draft
data to the draft database. The save sequence of the active provider is not triggered. That means, there is no
Finalize and no Check_Before_Save when saving draft instances on the draft database table.
On a Fiori Element UI, the state of the application buffer is saved to the draft database table whenever the input
fields are edited. This is done for each field separately. That means, after leaving one input field, the data is
transferred to the draft database table. The UI displays the message Draft saved after each roundtrip.

Learn PUBLIC 77
2.3.2.1.3.2.7.1 Runtime Activate Action
ACTIVATE.

78 PUBLIC Learn
Learn PUBLIC 79
 Note
• (1) The detailed runtime of this step is illustrated in the runtime diagrams of the operations in non-draft
BOs. See
Create Operation [page 89],
Update Operation [page 91],
Delete Operation [page 94],
Create by Association Operation [page 97],
Action Runtime [page 108].
• (2) The detailed runtime of this step is illustrated in the runtime diagram of the save sequence. See
2.3.2.1.4 Authorization Control
Authorization control in RAP protects your business object against unauthorized access to data.
Context
To define which consumers under which circumstances are allowed to read or change data of a business
object, RAP offers an authorization concept for application developers to restrict access to the business object.
Authorization control is always relevant when the permission to execute an operation depends on the role of
the business object consumer. This contrasts to feature control, where the permission for operations depends
on the state of existing instances, or on BO-external factors that don't relate to the user.
The authorization for consumers is managed and maintained by the system administrator and grouped
into consumer roles. Authorization objects define the authorization for the respective user roles for certain
operations. In RAP each read or modify request can be checked via authorization objects against user roles
before the request is finally executed and reaches data. The authorization check with authorization objects
is called from CDS entities in case of read requests and from the behavior implementation in case of modify
requests.
For more information, about using authorization objects in your implementation, see .
 Home For more information, about using authorization objects in your implementation, see User and Role
Administration of Application Server ABAP.
 Cloud For more information, about the general authorization concept for RAP business services, see
Authorization Basics in the Identity and Access Management (IAM) Guide.
Authorization Checks for Read Operations
To protect data from unauthorized read access, the ABAP CDS provides its own authorization concept based
on a data control language (DCL). To restrict read access to RAP business objects, it's sufficient to model
DCL for the CDS entities used in RAP business objects. The authorization and role concept of ABAP CDS uses

80 PUBLIC Learn
conditions defined in CDS access control objects to check the authorizations of users for read access to the
data in question. In other words, access control allows you to limit the results returned by a CDS entity to those
results you authorize a user to see.
 Restriction
You can't define authorization control or feature control for functions.
In addition, DCL is also automatically evaluated in case of transactional read access for managed business
objects, that is when using EML-based read and read-by-association operations. In unmanaged business
objects, the transactional read operation must be implemented by the application developer. Hence, DCL must
be checked in this implementation.
For more information, see .
Authorization Checks for Modify Operations
In RAP business objects, modifying operations, such as standard operations and actions can be checked
against unauthorized access during runtime. To retrieve user authorizations for incoming requests,
authorization objects are included in the behavior implementation for your business objects. Authorization
objects return authorization values.
You've dedicated authorization implementation options in RAP business objects available. For them,
authorization is defined in the behavior definition and implemented in the methods for authorization. These
dedicated authorization methods are called during runtime at a specific point in time before the actual modify
operation. Hence, you can prevent modify operations with authorization control before the actual modify
operation is executed on the transactional buffer. Authorization checks in RAP authorization control methods
can only check against the state of the BO before the request was executed, the so-called before image,
because these methods are called before the actual modify request is executed. Hence, it isn't possible to
check the authorization of a user against the incoming values. To implement authorization checks against
incoming values, see Authorization Check against Incoming Values (Precheck) [page 82].
To see when the authorization exits are called at runtime when updating a draft instance, see Runtime MODIFY
Draft [page 68].
Global Authorization
Global authorization is used for all authorization checks that only depend on the user. You can define global
authorization to check if users are allowed to execute an operation in general.
 Example
Only HR representatives can create new instances in an employee master data BO.
During the runtime of the CREATE request, the authorization is checked against the role of the user.
Global authorization is the first check for incoming requests. With global authorization you can reject the
request before it reaches any other method of the behavior handler classes.
Global authorization checks can be implemented for both, static, and instance-bound operations.

Learn PUBLIC 81
Instance Authorization
Instance authorization is used for all authorization checks that, in addition to the user role, depend on the state
of the entity instance in question. With instance authorization, you can define authorization that depends on a
field value of the instance.
 Example
Managers can only change the salary amount of their own employees.
In this case, the employee entity must contain a field that refers to the manager. During the runtime of
the UPDATE request, the value of the manager field is compared to the authorization of the user role. Only
if for this value the user is authorized to update the instance, the update request is approved and can be
executed. Otherwise, the request fails.
Instance authorization is only possible for instance-based operations. Operations that don't operate on a
specific instance can't be checked with instance authorization. Operations that are excluded from instance
authorization are CREATE and static actions. Technically speaking, the implementation method for instance
authorizations requires the keys of the instance for the authorization check. Static operations don't relate to
one specific instance, and thus, can't provide a key.
Authorization Check against Incoming Values (Precheck)

Authorization checks can be implemented in the corresponding precheck method for the operation to check
against incoming values. In this case, the unwanted values don't even reach the transactional buffer.
 Caution
Fiori Elements UIs don't fully support the behavior of authorization checks in precheck methods.
For more information, see Precheck [page 85] and for an implementation example refer to Implementing
Prechecks [page 630].
Authorization in Projection Behavior Definitions
Generally, CRUD operations and actions reused with use inherit the authorization control from the base
behavior definition. If you define new actions on projection level as described in Actions and Functions in
Projection Behavior Definitions [page 105] and the projection behavior definition is defined as strict, you
can add authorization control for these actions on projection level. Contrary to the base behavior definition,
you must define each projection definition individually either as authorization global or authorization
instance. There's no master/dependent relation between the different projection definitions. Additionally,
you can define an action with authorization:none to exclude it from authorization checks.
For more information about syntax and examples, refer to CDS BDL - authorization, projection BDEF (ABAP -
Keyword Documentation).
Authorization in Draft Scenarios
Authorization checks in RAP authorization control methods are executed before the draft instance is modified.
The authorization methods are called for the operations that operate on draft instances and for the draft

82 PUBLIC Learn
actions EDIT and RESUME, see Runtime Edit Action [page 62] and Runtime Resume Action [page 76]. In case of
RESUME, the authorization control for CREATE is checked when executed for a new-draft and it's called for EDIT
when the RESUME is executed for edit-drafts.
 Note
The authorization methods aren't called when activating the draft instance. If you want to prevent that a
draft instance is activated, you must implement the authorization check in a validation.
Consumer Hints in UI Scenarios
In UI scenarios, consumer hints, which are retrieved from the backend, provide the information for the UI which
operations are enabled for the current situation. On a Fiori Elements UI, action and other operation buttons are
only displayed and clickable if authorization and feature control methods provide a positive result under the
current conditions (the state of the retrieved BO instances).
The definition and implementation of authorization and feature control is important, as the consumer hints are
based on the result of the authorization and feature control. The implementation methods for authorization
and feature control are called on displaying the list report or the object page for a specific instance. By
checking the authorization for all the exposed actions beforehand, users can't even start operations, for which
they aren't authorized, as their triggers (action buttons) aren't available.
 Example
The action SetStatusBooked can only be executed for instances, whose status isn't booked yet (feature
control) and by users that are assigned to a specific role (authorization). When selecting instances, whose
status is booked already, the button for this action isn't available on the UI and the user can't execute the
action.
2.3.2.1.4.1 Authorization Definition
Authorization is defined in the behavior definition of a RAP business object.
Syntax
Like other behavior characteristics, authorization is defined in the header of the behavior definition for a
business object entity.
For details about the syntax of authorization in the behavior definition, see CDS BDL - authorization (ABAP -
Once you have defined authorization in the behavior definition you can use the quick fix to generate the
corresponding methods in the specified behavior pool.

Learn PUBLIC 83
Authorization Master
An entity is defined as authorization master (authorization master ()) if the operations of this entity
have their own authorization implementation. That means in the behavior implementation of this entity, the
authorization control must be implemented in the corresponding method for authorization (global or instance).
For the authorization master, you must define either global, or instance, or both.
The current version of the RAP model only supports authorization masters on root entities.
Authorization Dependent
An entity is defined as authorization dependent (authorization dependent by _Assoc) if the

authorization control from the authorization master entity shall also be applied for the operations of this entity.
In this case, for the authorization check for the update, the delete, and the create-by-association operation
on an authorization dependent entity, the authorization check for the update operation of the authorization
master entity is applied.
For actions of authorization dependent entities, as well as for create-enabled associations that are not
compositions, the authorization control must be implemented in separate methods for authorization in the
behavior implementation class of the authorization dependent entity. It depends on the definition of the
authorization master entity, if global or instance authorization must be implemented for these actions.
 Note
For the definition of authorization dependent entities, you have to specify the association to the
authorization master entity in the behavior definition, even though it is implicitly transaction-enabled due
to internal BO relations.
{

association _AssocToMaster;

}
 Note
In unmanaged business objects, the definition of authorization dependent entities requires the
implementation of the read-by-association method. As authorization checks on authorization dependent
entities are delegated to the authorization master, the read-by-association is used to get the authorization
information from the master entity.
In managed business objects, the read-by-association is provided by the RAP managed BO provider.
If you define an authorization master in a business object, it is recommended that all other entities are
authorization dependent entities.

84 PUBLIC Learn
By defining global authorization (authorization master (global)), you implement authority control for
the following operations of the entity:
• Create
• Create-by-association
• Update
• Delete
• Static Actions
• Instance Actions
The authorization check is implemented in the corresponding method in the behavior implementation. For
more information, see Global Authorization Implementation [page 87].
The global authorization check is called during runtime before the request reaches the backend. In case of a
scenario with draft, if a user is not authorized, a request is rejected before a draft is saved on the draft database
table.
By defining instance authorization (authorization instance ()), the following operations of the entity
can be checked against unauthorized access:
• Create-by-association
• Update
• Delete
• Instance Actions
The authorization check is implemented in the corresponding method in the behavior implementation. For
more information, see Instance Authorization Implementation [page 87].
The instance authorization check is called during runtime before the actual execution of the requested
operation. In draft scenarios this means that the draft instance already exists, but its activation is prevented.
You can define both, global and instance authorization. It is possible to check instance-based operations in
the global and the instance authority check. The checks are executed during different points in time during
runtime.
Precheck
With a precheck implementation you can check against incoming values and deny incoming requests before
data reaches the transactional buffer. For more information, see Operation Precheck [page 115].
The precheck requires an implementation in the behavior pool. For more information, see Precheck [page 87].

Learn PUBLIC 85
Authorization Exclusion
By using the syntax element authorization: none on an operation in the entity's behavior definition, you
exclude the operation in question from authorization checks. You can disable operations from authorization
checks in authorization master and dependent entities.
Authorization Delegation
By using the syntax authorization: update on an operation in the entity's behavior definition, you can
use the authorization check that is implemented for the update operation for the annotated operation. The
derived types in the augmentation implementation methods do not show the annotated operation in requested
authorizations in this case.
Authorization can be delegated for the following operations:
• delete
• create-by-association
• actions
The authorization for internal actions cannot be delegated. Internal actions do not have authorization checks in
general, as they are only invoked internally. Likewise, it is not possible to delegate the authorization for the draft
action Edit .
You can delegate the authorization for operations to the update operation, even if the update operation is not
enabled for this entity.
 Remember
Standard operations in authorization dependent entities are automatically delegated to the update
operation of the authorization master entity.
If you the authorization for an action in an authorization dependent entity to the update operation, it will be
delegated to the update operation of the authorization master entity in the end.
2.3.2.1.4.2 Authorization Implementation
Authorization checks are implemented in the behavior pool with the respective methods for global
authorization, instance authorization or prechecks.
The authorization that is defined on a business object's entity must be implemented in the corresponding
local handler class (lhc_handler) of the behavior pool. As depicted in the listing below, each such local class
inherits from the base handler class CL_ABAP_BEHAVIOR_HANDLER. The authorization check is implemented
in this handler class using the corresponding methods global authorization or instance authorization. To check
authorization for incoming values, you implement the respective method for the precheck.

86 PUBLIC Learn
Authorization Implementation in the Behavior Pool
The method declarations can be generated via a quick fix when defining authorization in the behavior
definition. Global and instance authorization need to be handled separately from provider perspective as
they're consumed during different points in time.
The global authorization method is called as the first method in the handler class, when a modify or create
request is executed, see Update Operation [page 91].
As global authorization is independent of the state of the entity and just checks the authorization of the user
that has executed the request, the global authorization handler is used to forbid certain operations for certain
user groups in general. A typical use case is to only allow specific user groups to create new instances.
For a detailed implementation example, see Implementing Global Authorization [page 620].
For more information about the implementation in the behavior pool, see FOR GLOBAL AUTHORIZAITON
(ABAP- Keyword Documentation).
The method for instance authorization is called, right before the actual modification of the respective instance
happens, see Update Operation [page 91]. At this point in time, during the runtime execution, you can only
make checks against the state of the instance as it was before the modification request was triggered. This
state, the so-called before image is relevant for authorization checks in the instance authorization method. You
don't have the option to check against incoming values.
 Example
Travel instances with an agency ID that have a certain country/region code can only be changed by a
specific user group. In this example, you implement the authorization check in the instance authorization
method and select the agency data set from the database table /DMO/agency to check the value of the
country/region code field of the before image instance to pass to the authorization object. The actual
authorization check is done by the authorization object if you have defined authorization values.
For the detailed description of this example, see Implementing Instance Authorization [page 624].
For more information about the implementation in the behavior pool, see FOR INSTANCE AUTHORIZATION,
AUTHORIZATION (ABAP- Keyword Documentation).
Precheck
The precheck implementation checks incoming values against the before image of a RAP BO to determine
whether certain values can be set in a request. The precheck implementation is called before the requested
changes can reach the transactional buffer.
 Example
A travel agency is only allowed to create or update travels for the country/region it's located in. Then the
requests must be checked against the country-code of the respective travel agency to determine whether
an agency has permissions to change or create the respective travels.
For a detailed implementation, see [SET LINK].

Learn PUBLIC 87
For more information about the implementation in the behavior pool, see FOR PRECHECK (ABAP- Keyword
Documentation).
2.3.2.1.5 Operations
This section describes the operations that are available for RAP business objects and their functionality.
Standard Operations [page 88]

Standard operations in RAP business objects are operations that cover the standard functionality for
creating, updating, deleting and locking RAP BO instances.
Nonstandard Operations [page 101]

Nonstandard operations in RAP are operations that do not provide the canonical behavior of RAP BOs.
Instead, they are used to provide customized, business-logic-specific behavior.

With a precheck implementation you can deny incoming requests before data reaches the
transactional buffer.
Operation Augmentation [page 116]

With an augmentation implementation you can add data or modify incoming requests on the projection
layer before data reaches the transactional buffer.
2.3.2.1.5.1 Standard Operations
Standard operations in RAP business objects are operations that cover the standard functionality for creating,
updating, deleting and locking RAP BO instances.
Create Operation [page 89]

In RAP, the create operation is a standard modifying operation that creates new instances of a
business object entity.
Update Operation [page 91]

In RAP, the update operation is a standard modifying operation that changes instances of a business
object entity.
Delete Operation [page 94]

In RAP, the delete operation is a standard modifying operation that deletes instances of a business
object entity.
Create by Association Operation [page 97]

In RAP, the create by association operation is a modify operation that creates new instances of
an associated entity.
Lock Operation [page 100]

In RAP, the lock operation is a standard operation that locks instances of a business object entity.

88 PUBLIC Learn
2.3.2.1.5.1.1 Create Operation
In RAP, the create operation is a standard modifying operation that creates new instances of a business
object entity.
 Note
In case of a managed business object, instances for child entities can only be created by a create-by-
association.
The following runtime diagram illustrates the main agents' activities during the interaction phase of a create
operation when the BO consumer sends a create request. The save sequence is illustrated in a separate
diagram, see Save Sequence Runtime [page 225].
Instantiation of Handler Classes in the ABAP Behavior Pool

 Note

Learn PUBLIC 89


90 PUBLIC Learn
• Authorization Control [page 80]
• Operation Precheck [page 115]
• <method> FOR NUMBERING [page 28]
• Numbering [page 23]
• Determinations [page 119]
• Save Sequence Runtime [page 225]
• Feature Control [page 128]
• Operation Augmentation [page 116]
• ROLLBACK ENTITIES [page 259]
2.3.2.1.5.1.2 Update Operation
In RAP, the update operation is a standard modifying operation that changes instances of a business object
entity.
The following runtime diagram illustrates the main agents' activities during the interaction phase of an update
operation when a BO consumer sends an update request. The save sequence is illustrated in a separate

Learn PUBLIC 91
 Note

92 PUBLIC Learn


Learn PUBLIC 93
• Lock Implementation [page 44]
• Concurrency Control [page 33]
2.3.2.1.5.1.3 Delete Operation
In RAP, the delete operation is a standard modifying operation that deletes instances of a business object
entity.
The following runtime diagram illustrates the main agents' activities during the interaction phase of a delete
operation when a BO consumer sends a delete request. The save sequence is illustrated in a separate diagram,
see Save Sequence Runtime [page 225].

94 PUBLIC Learn
 Note

Learn PUBLIC 95


96 PUBLIC Learn
2.3.2.1.5.1.4 Create by Association Operation
In RAP, the create by association operation is a modify operation that creates new instances of an
associated entity.
The following runtime diagram illustrates the main agents' activities during the interaction phase of a create
by association operation when a BO consumer sends a create-by-association request. The save sequence
is illustrated in a separate diagram, see Save Sequence Runtime [page 225].

Learn PUBLIC 97
 Note

98 PUBLIC Learn


Learn PUBLIC 99
2.3.2.1.5.1.5 Lock Operation
In RAP, the lock operation is a standard operation that locks instances of a business object entity.
For details about the lock operation in RAP, see Pessimistic Concurrency Control (Locking) [page 38].

100 PUBLIC Learn
2.3.2.1.5.2 Nonstandard Operations
Nonstandard operations in RAP are operations that do not provide the canonical behavior of RAP BOs. Instead,
they are used to provide customized, business-logic-specific behavior.
Actions [page 101]

An action in RAP is a non-standard modifying operation that is part of the business logic.
Functions [page 111]

A function in RAP is a custom read-operation that is part of the business logic.
2.3.2.1.5.2.1 Actions
An action in RAP is a non-standard modifying operation that is part of the business logic.
The standard use case of an action is to change specific fields of a business object entity. When using an
action, it is not the standard update operation that is called, but the action with the predefined update
implementation. On a Fiori UI, this means that the consumer of the Fiori app can change the state of an
individual business object instance without having to switch to edit mode. The application developer provides
action buttons for the action to be executable directly from a list report or an object page.
In the travel demo scenario, we provide examples of actions for changing the status of a travel instance to
booked. Expand the following figure to watch how an action is executed on a Fiori UI.
Setting the Status to booked by an Action
In general, however, actions can have a much wider scope than just changing single values of an instance. You
can create instances or implement complete work-flows in an action.
Technically, actions are part of the business logic. They are defined in the behavior definition and implemented
in the behavior pool of a business object. Actions are executed by calling the corresponding method FOR

Learn PUBLIC 101
MODIFY that has typed import and export parameters. They are identified as actions by the syntax FOR
ACTION.
Triggers for Actions
For an action to be executed, a corresponding trigger is required. Actions can be called by
• A service consumer, for example, by a user interface.

• Internally, for example, by another action or by a determination via EML.
• By other business objects via EML.
 Restriction
There are some restrictions in exposing actions for OData V2 services:
• For importing parameters only simple types are supported

• Results with collection of complex type in collections are not supported.
• Result entity is only supported with cardinality [0..1] or [1].
Related Information
Action Definition [page 102]

Action Implementation [page 106]
Action Runtime [page 108]
2.3.2.1.5.2.1.1 Action Definition
You define actions for an entity in the behavior definition.
Syntax for Defining Actions
Actions are specified as non-standard operations in behavior definitions and are implemented in the ABAP
behavior pool.
For details about the syntax, see CDS BDL - action (ABAP - Keyword Documentation).
Input Parameter
For details about input parameters for actions, see CDS -BDL - input parameter (ABAP - Keyword
Documentation).

102 PUBLIC Learn
For details about modeling of parameters in RAP, see Modeling Parameters for Non-Standard Operations [page
887].
For OData V4 UI services, you can specify a default value for the input parameter, which is automatically
displayed when the pop-up of the input parameter shows up. For more information about the modeling, see
Action deductDiscount [page 597] in the development guide for Transactional Apps with Draft Capabilities.
You can specify $self if the input parameter entity is the same abstract entity the action is assigned to. Input
parameters with $self are only allowed on static actions. The reason for this is that instance-bound actions
always import the key of the instance on which the action is executed. If you import the same entity instance
as input parameter, the keys would be imported twice, which will cause a short dump during runtime. For more
information about the importing parameter, see Importing Parameter [page 106].
Output Parameters
For details, about output parameters, see CDS BDL - output parameter (ABAP - Keyword Documentation ).
887].
The output parameter for actions and functions is defined with the keyword result. The result parameter
is optional. However, if a result parameter is declared in the action definition, it must be filled in the
implementation. If it is not filled, the action does not return anything, even if the action is declared with result
cardinality greater 0. In such a case, the OData service returns initial values.
Factory actions return their result in the mapped response parameter by mapping the keys to the %cid that
was provided by the consumer.
By declaring the action result as selective you can define that the action consumer can decide whether
the result shall be returned completely or only parts of it, for example the keys only. This can help to
improve performance as performance consuming calculated fields can be excluded from the result. For more
information about the implementation with selective result parameter, see Action Importing Parameter [page
106].A Fiori UI requests only the keys of the result when an action with selective result is executed.
The result cardinality for actions and functions determines the multiplicity of the output. In this way, it
indicates whether the action produces 0..1, 1, 0..n, or 1..n output instances. The possible values for cardinality
are therefore:[0..1], or [1], or [0..*], or [1..*]
You can return either a result entity or a result structure:
• Result Entity: By declaring the action with result entity MyBOEntity, the action returns one ore
more instances of MyBOEntity. result $self returns one or more instances of the entity the action is
assigned to.
When you return a result entity with $self in a UI service, the current UI behavior is that it stays on the
same page where they action is executed. For factory actions, a Fiori Elements UI currently navigates to the
object page of the newly created instance.
 Note
Only actions and functions having output entities that are included in the service definition are exposed
in the service.
In a projection behavior definition, result entities other than $self must be redefined with the projection
result entity. For more information, see Actions in Projection Behavior Definitions [page 105].
• Result Structure: If the action result is an abstract entity, you have to define the result without the keyword
entity as abstract entities are generally considered to be structures in ABAP.

Learn PUBLIC 103
Action Types
Internal Action
By default, actions are executable by OData requests as well as by EML from another business object or from
the same business object. To only provide an action for the same BO, the option internal can be set before
the action name, for example, when executing internal status updates. An internal action can only be accessed
from the business logic inside the business object implementation such as from a determination or from
another action.
Static Action
By default, actions are related to instances of a business object’s entity. The option static allows you to
define a static action that is not bound to any instance but relates to the complete entity
Repeatable Action
The addition repeatable allows you to define an instance action that can be executed multiply on the same
instance in the same EML request or OData changeset. The different executions of such an action can be
distinguished using the content ID %CID. The content ID is contained in the derived type of repeatable actions
and needs to be provided in every call of a repeatable action.
Factory Action
With factory actions, you can create entity instances by executing an action. Factory actions can be instance-
bound or static. Instance factory actions can be useful if you want to copy specific values of an instance. Static
factory actions can be used to create instances with prefilled default values. A factory action always has the
result cardinality [1].
In contrast to a non-factory action, the handler method of factory actions offers %cid handling for the result
instance. The result is determined via the response parameter mapped. There is no result parameter. In
contrast to non-factory actions, the %cid, which is provided by the consumer when executing factory actions,
is mapped to the final key value. This helps the consumer identifying the newly created instance.
Action Additions
External Action Name

By using the syntax external 'ExternalActionName', you can rename the action for external usage. That
means, the new name is exposed in the OData metadata. This external name can be much longer than the
actual action name, but is not known by ABAP.
If you want to define an action button for an action with an external name, the external name must be used in
the @UI annotation. For more information, see UI Consumption of Actions [page 107].
Instance Feature Control

Instance feature control for actions enables or disables the action depending on preconditions within the
business object. For example, you might want to offer the action accept_travel only if the status is not
rejected already.
Dynamic instance feature control for actions is defined with the syntax features: instance.

104 PUBLIC Learn
For more information, see Feature Control [page 128].
Global Feature Control

Global feature control for actions enables or disables the action depending on BO-external preconditions. For
example, you might want to offer an action only during a specific time of the year.
Dynamic global feature control for actions is defined with the syntax features: global.
For more information, see Global Feature Control [page 132].
Authorization Control
Actions can be checked against unauthorized execution. A precondition for this is the definition of an
authorization master in the behavior definition. To exclude the action from authorization checks, you can use
the syntax authorization: none.
For more information, see Authorization Definition [page 83].
Non-Locking Action
By default, instance actions lock the instance on which they are executed. To prevent that the locking
mechanism is triggered when executing an action, you can define an instance action as non-locking with the
syntax lock: none.
Copy actions are a use case for this. You might want to copy the data of an existing instance without locking the
template instance. Since static actions are not related to a specific instance, they are non-locking by definition
and this syntax element is not applicable.
 Note
The locking mechanism is only prevented for the action itself. Possible modify calls in the action
implementation are not affected by the non-locking specification in the action definition. Consequently,
an instance is locked if it is modified by an action even if the action is defined as non-locking.
Actions and Functions in Projection Behavior Definitions
You can add new actions and functions on projection level, for example if an action is only relevant for one
specific use case. For the definition, the same rules applay as for actions and functions defined on the base
RAP business object. However, if an authorization concept is required, you must define it for each BO node
and the projection BDEF must be defined as strict. For more information. see Authorization Definition [page
83]. Actions and Functions added to the projection BDEF are automatically exposed with the OData service and
don't need to be exposed separately.
Actions and Functions defined in base behavior definitions must be included in the projection behavior
definition if you want to expose it for an OData service. The following syntax is used:
projection; ...


{...

use action ActionName [result entity ProjResultEntity] [as ActionAlias]
[external ExtActName];

use function FunctionName [result entity ProjResultEntity] [as FunctionAlias]
[external ExtFuncName];

Learn PUBLIC 105

}
For more information about actions and functions in projection BDEFs, see CDS BDL - entity behavior definition
(ABAP - Keyword Documentation).
Related Information
Actions [page 101]

2.3.2.1.5.2.1.2 Action Implementation
You implement actions in the behavior pool with the respective method FOR MODIFY.
As a rule, a custom operations that belongs to a business object’s entity is implemented in the behavior pool
that is defined in the behavior definition by the keyword implementation in class ABAP_ClASS_NAME
[unique].
The concrete implementation is based on the ABAP language in a local handler class as part of the behavior
pool.
As depicted in the listing below, each such local class inherits from the base handler class
CL_ABAP_BEHAVIOR_HANDLER. The signature of the handler method FOR MODIFY is type based on the entity
that is defined by the keyword FOR ACTION followed by AliasedEntityName~ActionName. The alias name
is defined in the behavior definition using the additional alias AliasedEntityName that refers to the suitable
CDS entity.
Implementing an Action in a Local Handler Class

CLASS lhc_handler DEFINITION INHERITING FROM cl_abap_behavior_handler.
PRIVATE SECTION.
METHODS method_name FOR MODIFY
IMPORTING keys FOR ACTION AliasedEntityName~ActionName

[REQUEST requested_fields]

[RESULT result].

ENDCLASS.
CLASS lhc_handler IMPLEMENTATION.
METHOD method_name.
// Implement method here!
ENDMETHOD.
ENDCLASS.

Importing Parameter
• Depending on the type of action, the importing parameter keys has the following components:

106 PUBLIC Learn
Action Specifics Importing Parameter Components
instance action An instance action imports the key of the instan
An instance action imports %cid_ref. This co

action is executed on a newly created instance t
filled with the %cid of the instance the action is
static action A static action imports %cid. For static actions

the operation uniquely.
action with parameter An action with parameter imports the paramete
action with result type entity If the action returns one or more entity instance
instance before the final key is set.
factory action A factory action imports %cid and %cid_ref
As factory actions always create new instances,

the final key is set.
If factory actions are instance-bound they also i

created instance to which they are assigned.
• If the result parameter is defined as selective in the behavior definition, the action declaration in
the behavior pool receives another importing parameter REQUEST requested_field. In the request
parameter all fields of the action result that are selected by the action executor are flagged. Because of
this, the action provider knows which fields are expected as a result.
Result Parameter
The components of the result parameter depend on those of the importing structure. The imported values of
%cid and %cid_ref are returned if they are imported.
If a result is defined, it has the structure %param to be filled by the action implementation. This component is a
table that reflects the type of the defined result type.
For action with selective result, only the fields that are requested in REQUEST must be filled in %param.
UI Consumption of Actions
For an action to be consumable by a Fiori Elements UI, you need to define an action button in the relevant CDS
view.
An action is always assigned to one business object entity in the behavior definition. In the corresponding CDS
view, the action button must be defined in the @UI annotation.
Use @UI.lineItem: [ {type: #FOR_ACTION, dataAction: 'ActionName', label:

'ButtonLabel' ] } to define an action button on a list report page.
Use @UI.identification: [ {type: #FOR_ACTION, dataAction: 'ActionName', label:

'ButtonLabel' ] } to define an action button on the object page.
The ActionName must correspond to the action name in the behavior definition. If an external action name is
defined for the action, you have to use this external name.

Learn PUBLIC 107
Example
For a fully implemented action, see Implementing Actions [page 408] and Enabling Actions for UI Consumption
[page 414].
Related Information

Actions [page 101]
2.3.2.1.5.2.1.3 Action Runtime
In RAP, an action is a non-standard modify operation.
The following runtime diagram illustrates the main agents' activities during the interaction phase of an action
when a BO consumer requests the execution of an action. The save sequence is illustrated in a separate

 Note

108 PUBLIC Learn


Learn PUBLIC 109
• Action Runtime [page 108]
Related Information
Actions [page 101]


110 PUBLIC Learn
2.3.2.1.5.2.2 Functions
A function in RAP is a custom read-operation that is part of the business logic.
Functions perform calculations or reads on business objects without causing any side effects. Functions
don't issue any locks on database tables and you can't modify or persist any data computed in a function
implementation.
 Caution
 Example
If you have a business object that manages batch jobs and you want to administer the jobs simultaneously,
you can use functions.
Functions and Queries
Similar to a query, a function offers a possibility for structured data retrieval and data filtering without
modifying any data. A function is preferable to a query, if you don't want the consumer to operate on the
entire result-set, but a prefiltered result-set instead. If the filter criteria are predefined and don't depend on the
consumer, you can use functions to push the data filtering and structuring to the back end and only expose the
final result set to the consumer.
While a query only allows one implementation, you can implement several instance-bound or entity-bound
functions operating on the same result set, but with different filter conditions. You can develop more complex
filtering semantics because you can use a combination of customized parameters reflecting your individual use
case in addition to the query capabilities described in Query Capabilities [page 283].
Furthermore, you can create and expose transition messages for the consumer to offer more transparency if a
request fails. For more information about messages, refer to Messages [page 261]. Note that functions can only
return transition messages and no state messages.
Triggers for Functions
For a function to be executed, a corresponding trigger is required. Functions can be called by:
• A service consumer, for example, by a user interface.

• Internally, for example, by an action or by a determination via EML.
• By other business objects via EML.

Learn PUBLIC 111
2.3.2.1.5.2.2.1 Function Definition
Function Syntax
Functions are specified as nonstandard operations in behavior definitions and are implemented in the ABAP
behavior pool.
For details about the syntax, see CDS BDL - function (ABAP - Keyword Documentation).
Input Parameter
For details about input parameters for functions, see CDS -BDL - input parameter (ABAP - Keyword
Documentation).
887].
Output Parameters
For details, about output parameters, see CDS BDL - output parameter (ABAP - Keyword Documentation ).
887].
The output parameter for actions and functions is defined with the keyword result. The result parameter
is optional. However, if a result parameter is declared in the action definition, it must be filled in the
implementation. If it isn't filled, the action doesn't return anything, even if the action is declared with result
cardinality greater 0. In such a case, the OData service returns initial values.
By declaring the action result to as selective you can define that the action consumer can decide whether
the result shall be returned completely or only parts of it, for example the keys only. This can help to
improve performance as performance consuming calculated fields can be excluded from the result. For more
information about the implementation with selective result parameter, see Action Importing Parameter [page
106]. A SAP Fiori UI requests only the keys of the result when an action with selective result is executed.
The result cardinality for actions and functions determines the multiplicity of the output. In this way, it
indicates whether the action produces 0..1, 1, 0..n, or 1..n output instances. The possible values for cardinality
are therefore:
[0..1], or [1], or [0..*], or [1..*].
 Note
End-to-end support for RAP scenarios is only given with result entity cardinality [0..1], or [1].
You can return either a result entity or a result structure:
• Result Entity: By declaring the action with result entity MyBOEntiy, the action returns one ore
more instances of MyBOEntity. result $self returns one or more instances of the entity the action is
assigned to.

112 PUBLIC Learn
When you return a result entity with $self in a UI service, the current UI behavior is that it stays on the
same page where they action is executed. For factory actions, a Fiori Elements UI currently navigates to the
object page of the newly created instance.
 Note
Only actions and functions having output entities that are included in the service definition are exposed
in the service.
In a projection behavior definition, result entities other than $self must be redefined with the projection
result entity. For more information, see Actions in Projection Behavior Definitions [page 105].
• Result Structure: If the action result is an abstract entity, you have to define the result without the keyword
entity as abstract entities are generally considered to be structures in ABAP.
Function Types
 Caution
By using the syntax external 'ExternalFunctionName', you can rename the function for external usage.
That means, the new name is exposed in the OData metadata. This external name can be much longer than the
actual function name, but isn’t known by ABAP.
Internal Function
By default, functions are executable by OData requests as well as by EML from another business object or from
the same business object. To only provide a function for the same BO, the option internal can be set before
the function names. An internal function can only be accessed from the business logic inside the business
object implementation such as from a determination or from another function.
Static Function
By default, functions are related to instances of a business object’s entity. The option static allows you to
define a static function that isn’t bound to any instance but relates to the complete entity.
Repeatable Function
The addition repeatable allows you to define an instance function that can be executed multiply on the
same instance in the same EML request or OData changeset. The different executions of such a function can
be distinguished using the content ID %CID. The content ID is contained in the derived type of repeatable
functions and needs to be provided in every call of a repeatable function.
Actions and Functions in Projection Behavior Definitions
You can add new actions and functions on projection level, for example if an action is only relevant for one
specific use case. For the definition, the same rules applay as for actions and functions defined on the base

Learn PUBLIC 113
RAP business object. However, if an authorization concept is required, you must define it for each BO node
and the projection BDEF must be defined as strict. For more information. see Authorization Definition [page
83]. Actions and Functions added to the projection BDEF are automatically exposed with the OData service and
don't need to be exposed separately.
Actions and Functions defined in base behavior definitions must be included in the projection behavior
definition if you want to expose it for an OData service. The following syntax is used:
projection; ...


{...

use action ActionName [result entity ProjResultEntity] [as ActionAlias]
[external ExtActName];

use function FunctionName [result entity ProjResultEntity] [as FunctionAlias]
[external ExtFuncName];

}
For more information about actions and functions in projection BDEFs, see CDS BDL - entity behavior definition
State Messages in Read Operations
Read operations, including functions, don't cause any changes to the business object state, but simply return
data. Consequently, a read or function implementation can't issue new state messages.
In OData V4, a function with result type entity returns the respective entity including the respective state
messages. In OData V2, the entity is returned without state messages as default behavior.
For more information about how messages behave in EML, refer to Message Behavior in EML (Entity
Manipulation Language) [page 274].
2.3.2.1.5.2.2.2 Function Implementation
As a rule, a custom operation that belongs to a business object’s entity is implemented in the behavior pool
that is defined in the behavior definition by the keyword implementation in class ABAP_CLASS_NAME
[unique].
The concrete implementation is based on the ABAP language in a local handler class as part of the behavior
pool.
As depicted in the listing below, each such local class inherits from the base handler class
CL_ABAP_BEHAVIOR_HANDLER. The signature of the handler method FOR READ is type based on the entity
that is defined by the keyword FOR FUNCTION followed by AliasedEntityName~FunctionName. The alias
name is defined in the behavior definition using the additional alias AliasedEntityName that refers to the
suitable CDS entity.
Implementing a function in a Local Handler Class

CLASS lhc_handler DEFINITION INHERITING FROM cl_abap_behavior_handler.

114 PUBLIC Learn
PRIVATE SECTION.
METHODS function_name FOR READ
IMPORTING keys FOR FUNCTION AliasedEntityName~ActionName

[REQUEST requested_fields]

[RESULT result].

ENDCLASS.
METHOD method_name.
// Implement function here!
ENDMETHOD.
ENDCLASS.

Importing Parameter
• Depending on the type of function, the importing parameter keys consists of the following components:
Action Specifics Importing Parameter Components
instance function An instance function imports the key of the inst
static function A static function imports %cid. For static funct

identifies the operation uniquely.
function with parameter A function with parameter imports the paramet
• If the result parameter is defined as selective in the behavior definition, the function declaration in
the behavior pool receives another importing parameter REQUEST requested_field. In the request
parameter all fields of the action result that are selected by the function executor are flagged. Because of
this, the function provider knows which fields are expected as a result.
Result Parameter
The components of the result parameter depend on those of the importing structure. The imported values of
%cid in case of a static function are returned if they are imported.
If a result is defined, it has the structure %param to be filled by the action implementation. This component is a
table that reflects the type of the defined result type.
For functions with selective result, only the fields that are requested in REQUEST must be filled in %param.
2.3.2.1.5.3 Operation Precheck
With a precheck implementation you can deny incoming requests before data reaches the transactional buffer.
You can prevent illegal changes from reaching the transactional buffer by prechecking modify operations.
Use cases are
• Authorization checks against incoming values, see Authorization Control [page 80]. For an implementation
example, refer to Implementing Prechecks [page 630].
• Uniqueness checks in managed BO scenarios with an unmanaged lock implementation, or unmanaged BO
scenarios, see Uniqueness Check for Primary Keys [page 32].

Learn PUBLIC 115
For details about the syntax for the precheck that can be defined for every modify operation in the behavior
definition or in the projection behavior definition, see CDS BDL - standard operations (ABAP- Keyword
Documentation)
The implementation for the condition deciding whether the modify operation is executed for a certain instance
must be implemented in the corresponding method in the behavior pool. If the precheck is used for an
operation in the projection behavior definition, the method must be implemented in the behavior pool for the
projection.
METHOD MethodName FOR PRECHECK

IMPORTING Keys1 FOR CREATE...

Keys2 FOR ACTION...
The precheck method is called during runtime before the assigned modify operation and removes all input
from the modifying request for which the condition in the precheck is not fulfilled.
Depending on the use case, you can define a precheck for the operation in the BO-layer or in the projection
layer. Also, it is possible to define for both layers.
Prechecks in UI Scenario
If a precheck fails and messages are returned in the REPORTED parameter, the messages are displayed on the
UI. The end user has to resolve the issue by changing the entries, so that the precheck does not return any
failed keys and messages.
Related Information
Create Operation [page 89]

Update Operation [page 91]
Delete Operation [page 94]
Create by Association Operation [page 97]
Actions [page 101]
Save Sequence Runtime [page 225]
2.3.2.1.5.4 Operation Augmentation
With an augmentation implementation you can add data or modify incoming requests on the projection layer
before data reaches the transactional buffer.
You can add data to a modify request or issue additional requests by augmenting the operation before the
request is passed to the base business object.
Use cases for augmentation are
• Defaulting for incoming requests.

116 PUBLIC Learn
The incoming original request for CREATE is augmented (modified) so that the request with prefilled values
is passed to the base BO for processing. In this case, the augmented request is the same as the original
request, just with different values.
• Behavior-enabling denormalized fields, for example enabling editing of language dependent fields, see
Editing Language-Dependent Fields [page 854].
The incoming original request for CREATE is augmented and a second request for
CREATE_BY_ASSOCIATION is issued. In this case the original request is augmented with a second one.
Definition
Augmentation is defined in the projection behavior definition on the relevant operation with the following
syntax:

..
{
use create (augment);
use update (augment);
use association AssocName { create (augment); }
...

}
Implementation
The implementation of the augmentation is done in an ABAP handler class of the projection behavior pool for
the augmented operation.
Method Declaration
METHODS augment_operation FOR MODIFY

IMPORTING entities_create FOR CREATE ProjectionEntityAlias
IMPORTING entities_update FOR UPDATE ProjectionEntityAlias

IMPORTING entities_cba FOR CREATE ProjectionEntityAlias\_Association
If you augment more than one operation, implement the logic in one method in the behavior implementation,
to be able to work with %cid_ref if you need to reference another instance.
 Example
One logical unit of work contains a create and an update request on the newly created instance. You need
to be able to reference the newly created instance in the augmentation implementation. That's where the
%cid of the newly created instance must be referenced in %cid_ref in the augmentation implementation
for the update operation. If you handle CREATE and UPDATE in separate methods, you cannot work with
%cid and %cid_ref.
A special form of the EML statement MODIFY is used to manipulate the request for the base BO in the handler
implementation.
METHOD augment_operation.

MODIFY AUGMENTING ENTITIES OF BaseBusinessObject
ENTITY EntityAlias
CREATE|UPDATE|EXECUTE MyAction FIELDS ( Field1 )
WITH VALUE #( ( Field1 = 'DefaultValue' ) )
RELATING TO OriginalInstance BY RelatedInstance.

ENDMETHOD.

Learn PUBLIC 117
 Note
This form of EML can only be used by a BO-provider.
With this EML statement, you can modify entities of the base business object. All modify operations are
allowed (including actions).
The statement variant has no FAILED or REPORTED addition. This is because of its special semantics. The
operations in modify augmenting are not executed immediately, but are only merged with the operation of
the original request. Thus, the processing of the augmented request by the base BO handler only begins after
the termination of the augment method. Failures during the processing of the underlying base BO handlers
cannot be reported back to the EML statement in the augmentation implementation. To trace possible errors
during processing of the augmented request, the relating table is used to map messages to incoming
requests. See RELATING Mechanism for New Instances [page 118].
However, the augment method itself has the changing parameters FAILED and REPORTED, which can be filled if
errors in its input are detected. These responses are included in the overall response of the projection request.
Furthermore, failed instances returned by the augment method are removed from the request before the
remainder of it is passed to the base BO.
A modify augmenting statement can request original base instances, instances that are requested in the
original request, or, it can modify other base instances that were not requested by the original request. The
recognition of original instances is done either by the imported instance key, or by using %CID_REF.
The following regulations apply when an instance of the original request is augmented:
• To augment an original UPDATE, issue an augmenting operation UPDATE on the same instance.
Set the values and %CONTROL flags for those fields only which are added by the augmentation.
• To augment an original CREATE (for example. for setting default values), issue an augmenting operation
CREATE on the same instance.
Do not issue an augmenting UPDATE (using the %CID_REF), as the base BO would then see the un-
augmented CREATE operation, which it may refuse (for example because of a missing mandatory field) or
handle in an unwanted manner.
• To augment an original CREATE_BY_ASSOCIATION, issue an augmenting operation
CREATE_BY_ASSOCIATION on the same instance. The target set of instances may contain original target
instances (with additional fields being set), as well as new instances. The same regulations apply as for
CREATE
• It is not possible to set a field in augment which was already set for the original instance. The RAP runtime
discards such augment fields. For example, values set in the original request cannot be changed. Only
fields which are unset in the original request can be added.
RELATING Mechanism for New Instances
It can happen that the base business object returns entries in the FAILED and REPORTED tables for augmented
requests. To relate these responses to the original request, if the augmented request contains new instances,
the MODIFY AUGMENTING statement offers an addition which allows to relate augmented instances to original
instances. The runtime uses this information to transform FAILED keys of new instances back to the keys of
the related original instances.

118 PUBLIC Learn
If an augmented instance fails, the related original instance is included in the FAILED response of the overall
request. If the failure occurs in locking, the related original instance is not passed to the base business object
handler classes.
2.3.2.1.6 Determinations
A determination is an optional part of the business object behavior that modifies instances of business objects
based on trigger conditions.
A determination is implicitly invoked by the business object’s framework if the trigger condition of the
determination is fulfilled. Trigger conditions can be modify operations and modified fields. The trigger
condition is evaluated at the trigger time, a predefined point during the BO runtime. An invoked determination
can compute data, modify entity instances according to the computation result and return messages to the
consumer by passing them to the corresponding table in the REPORTED structure.
For detailed information on messages, see Messages [page 261].
 Example
A determination is implemented to calculate the invoice amount based on a changed price or quantity of
an item. As soon as the consumer creates a new item entity instance or updates the quantity or price of an
existing one, the determination is executed and recalculates the invoice amount.
 Note
When working with determinations, you have to consider the following runtime specifics:
• In unmanaged scenarios, determinations are only supported for draft instances, not for active
instances.
• The determination result must not change if the determination is executed several times under the
same conditions (idempotence).
• The execution order of determinations is not fixed. If there is more than one determination triggered by
the same condition, you cannot know which determination is executed first.
• Once a determination has been triggered, it must run independently from other determinations.
• If you create or update an instance and delete it with the same request, it can happen that an EML read
operation in a determination on modify fails as instances with the given key cannot be found.
 Note
Side effects can be used to trigger a call to the backend after a determination has been executed. This
makes sense if the determined data are not automatically reread by the operation the determination
belongs to. Side effects must be defined and annotated in the OData document. For more information, see
Side effects.

Learn PUBLIC 119
2.3.2.1.6.1 Determination Definition
Syntax for Defining Determinations
For details about the syntax for defining determinations, see CDS BDL - determinations (ABAP- Keyword
Documentation)
Assigned Entity
A determination belongs to an entity stated in the behavior definition. The fields that are used for the trigger
conditions must belong to the same entity the determination is assigned to. The determined fields and the
determining fields may belong to the same entity or to other entities of the business object.
Reference to Implementation Class
Determinations are implemented in the behavior pool, which is referred in the behavior definition by the
keyword implementation in class ABAP_CLASS_NAME [unique].
Trigger Time
The trigger time defines at what time the trigger condition of a determination is evaluated. The following
options are available:
• on modify: The determination is triggered during a modify operation.
 Note
A determination on modify can also be triggered by the draft action activate as this action invokes a
modify call including an update operation in case of an already existing active instance or a create
operation in case of a new active instance. For more information, see Activate Action [page 64].
• on save:
• The determination is triggered in the finalize phase of the save sequence.
• The determination can be called on request by executing a determine action, if the determination
has been assigned to such an action in the behavior definition. For more information, see Determine
Actions [page 127].
For more information on the different activities performed during the BO runtime, see Operations [page 88].

120 PUBLIC Learn
Trigger Condition
Determinations can be triggered by trigger operations or by trigger fields or by both.
 Note
A determination can trigger itself, for example if update is defined as a trigger operation. To avoid
an infinite loop of executions, the trigger conditions can be defined on field level. If the determination
implementation changes other fields than the ones chosen as trigger conditions, the determination will not
be triggered repeatedly. In case that a determination does trigger itself, for example because an update
trigger is defined, the determination must stick to the rule of idempotence to avoid an infinite loop of
executions, see Rules for determinations [page 119].
Trigger Operations
Determinations can be triggered by the operations create, update and delete. When one of these
operations is executed for a draft instance or for an active instance, determinations with the respective trigger
operations are triggered.
 Note
The trigger operation update for determinations on save is only supported in combination with the trigger
operation create.
Trigger Aggregations
Determinations on save are triggered according to the relation between the operations performed on the
current transactional buffer and the state of the database before the transaction. This applies to draft and to
non-draft scenarios.
In draft scenarios, the transactional buffer is represented by the draft instance. In order to determine which
operation triggers a determination on save, all operations performed on the draft instance are aggregated
across its whole lifetime. Then, when a determination on save is called, these operations are evaluated
relatively to the state of the active database. This does not apply to determinations on modify.
 Example
A new draft instance is created. Then, it is updated. After that, a determine action containing a
determination on save is called. The trigger for the determination is the operation create and not the
operation update, because from the active database's point of view, this instance is new and has hence
been created, not updated.
If a delete operation is involved as a subsequent operation, the delete operation is the one which triggers the
determination on save. This enables the business object consumer to revert changes that might have been
performed before the delete operation by implementing a determination which triggers on that delete.
 Example
A new draft instance is created as the child of an existing draft root instance. While entering data for
this child instance, a determine action containing a determination on save is called that modifies the

Learn PUBLIC 121
root instance. After that, the child instance is deleted. A determination which is triggered by the delete
operation can now ensure that the changes done to the root instance are reverted.
The table below shows, which operation triggers a determination on save in case of different operation
aggregations. The trigger operation which is respectively effective must be stated in the behavior definition
for the determination so that it is executed. The following rules apply to the standalone execution of
determinations on save as well as to their execution via determine actions.
Operation aggregation Effective trigger operation
Create + Update Create
Create + Delete Delete
Update + Update Update
Update + Delete Delete
Delete + Create Create
Trigger Fields
Determinations can be triggered by fields belonging to the assigned entity. When one or more fields are
changed by a create or by an update operation, the determination is executed.
Input Parameter
A determination imports the keys of the instances on which the determination is executed. The name of
the input parameter must be declared in the signature of the corresponding method, see Determination
Implementation [page 123].
 Note
If imported keys are not available anymore during the runtime of a triggered determination on modify, this
determination is ignored by the framework.
Output Parameter
Messages can be returned to the consumer by writing them into the implicitly declared REPORTED structure.

122 PUBLIC Learn
2.3.2.1.6.2 Determination Implementation
The implementation of a determination is contained in a local handler class as part of the

behavior pool. As depicted in the listing below, this local class inherits from the base handler class
CL_ABAP_BEHAVIOR_HANDLER.
The signature of a determination method is typed using the keyword FOR DETERMINE followed by the chosen
determination time and the importing parameter. The type of the importing parameter is an internal table
containing the keys of the instances the determination will be executed on. Lastly the signature contains the
affected entity followed by the name of the determination stated in the behavior definition.
It is possible to implement multiple determinations for multiple entities in a single method, if these
determinations use the same trigger time.
Listing 1: Implementing a Determination in a Local Handler Class

CLASS lhc_handler DEFINITION INHERITING FROM CL_ABAP_BEHAVIOR_HANDLER.
PRIVATE SECTION.
METHODS method_name1 FOR DETERMINE ON MODIFY
IMPORTING keys FOR AliasedEntityName~DetOnModify.
METHODS method_name2 FOR DETERMINE ON SAVE
IMPORTING keys FOR AliasedEntityName~DetOnSave
keys2 FOR AliasedEntityName2~DetOnSave2.
ENDCLASS.
METHOD method_name1.
// Implement method for determination here!
ENDMETHOD.
...
ENDCLASS.

2.3.2.1.7 Validations
A validation is an optional part of the business object behavior that checks the consistency of business object
instances based on trigger conditions.
A validation is implicitly invoked by the business object’s framework if the trigger condition of the validation is
fulfilled. Trigger conditions can be modify operations and modified fields. The trigger condition is evaluated
at the trigger time, a predefined point during the BO runtime. An invoked validation can reject inconsistent
instance data from being saved by passing the keys of failed instances to the corresponding table in the
FAILED structure. Additionally, a validation can return messages to the consumer by passing them to the
corresponding table in the REPORTED structure.
For detailed information on messages, see Messages [page 261].
 Example
A validation is implemented to check if the customer ID contained in travel instances is valid. This validation
is assigned to the entity travel and contains the trigger field customer_ID. As soon as the field for
the customer ID is updated by the consumer, the validation checks whether the customer ID is valid or
not. If the customer ID is not valid, the validation prevents the instance data from being saved in the save
sequence and returns a warning message.

Learn PUBLIC 123
 Note
When working with validations, you have to consider the following runtime specifics:
• In unmanaged scenarios, validations are only supported for draft instances, not for active instances.
• The execution order of validations is not fixed. If there is more than one validation triggered by the
same condition, you cannot know which validation is executed first.
• It is not allowed to use EML modify statements in validations.
• In a managed scenario with draft, it is strongly recommended to assign validations to the PREPARE, so
that state messages from the validations are returned correctly to the consumer. For more information,
see State Messages [page 268].
2.3.2.1.7.1 Validation Definition
For details about the syntax for defining validations, see CDS BDL - validations (ABAP- Keyword
Documentation)
Assigned Entity
A validation belongs to an entity stated in the behavior definition. The fields that are used for the trigger
conditions must belong to the same entity the validation is assigned to. The validated fields may belong to the
same entity or to other entities of the business object.
Reference to Implementation Class
Validations are implemented in the behavior pool, which is referred in the behavior definition by the keyword
implementation in class ABAP_CLASS_NAME [unique].
Trigger Time
The trigger time defines at what time the trigger condition of a validation is evaluated. For validations, only the
trigger time on save can be stated. Validations on save are executed:
• In the checkBeforeSave method of the save sequence

• On request by executing a determine action, if the validation has been assigned to such an action in the
behavior definition. For more information, see Determine Actions [page 127].
For more information on the different activities performed during the BO runtime, see Operations [page 88].

124 PUBLIC Learn
Trigger Condition
Validations can be triggered by trigger operations or by trigger fields or by both.
Trigger Operations
Validations can be triggered by the operations create, update and delete. When one of these operations
is executed for a draft instance or for an active instance, validations with the respective trigger operations are
triggered.
 Note
The trigger operation update for validations is only supported in combination with the trigger operation
create.
Trigger Aggregations
Validations are triggered according to the relation between the operations performed on the current
transactional buffer and the state of the database before the transaction. This applies to draft and to non-draft
scenarios.
In draft scenarios, the transactional buffer is represented by the draft instance. In order to determine which
operation triggers a validation, all operations performed on the draft instance are aggregated across its whole
lifetime. Then, when a validation is called, these operations are evaluated relatively to the state of the active
database.
 Example
A new draft instance is created. Then, it is updated. After that, a determine action containing a validation is
called. The trigger for the validation is the operation create and not the operation update, because from
the active database's point of view, this instance is new and has hence been created, not updated.
If a delete operation is involved as a subsequent operation, the delete operation is the one which triggers the
validation. This enables the business object consumer to check data determined by a determination that might
have been executed before the delete operation.
 Example
A new draft instance is created as the child of an existing draft root instance. While entering data for
this child instance, a determine action containing a determination on save is called that modifies the root
instance. After that, the child instance is deleted. A validation which is triggered by the delete operation can
now validate the changes done to the root instance.
The table below shows, which operation triggers a validation in case of different operation aggregations. The
trigger operation which is respectively effective must be stated in the behavior definition for the validation
so that it is executed. The following rules apply to the standalone execution of validations as well as to their
execution via determine actions.

Learn PUBLIC 125
Operation aggregation Effective trigger operation
Create + Update Create
Create + Delete Delete
Update + Update Update
Update + Delete Delete
Delete + Create Create
Trigger Fields
Validations can be triggered by fields belonging to the assigned entity. When one or more fields are changed by
a create or by an update operation, the validation is executed.
Input Parameter
A validation imports the keys of the instances on which the validation is executed. The name of the input
parameter must be declared in the signature of the corresponding method, see Validation Implementation
[page 126].
Output Parameter
An invoked validation can reject inconsistent instance data from being saved by writing the keys of failed
instances into the implicitly declared FAILED structure.
Additionally, messages can be returned to the consumer by writing them into the implicitly declared REPORTED
structure.
2.3.2.1.7.2 Validation Implementation
The implementation of a validation is contained in a local handler class as part of the behavior
pool. As depicted in the listing below, this local class inherits from the base handler class
CL_ABAP_BEHAVIOR_HANDLER.
The signature of a validation method is typed using the keyword FOR VALIDATE followed by the importing
parameter. The type of the importing parameter is an internal table containing the keys of the instances the
validation will be executed on. Lastly the signature contains the affected entity followed by the name of the
validation stated in the behavior definition.
It is possible to implement multiple validations for multiple entities in a single method.

126 PUBLIC Learn
Listing 1: Implementing a Validation in a Local Handler Class

CLASS lhc_handler DEFINITION INHERITING FROM CL_ABAP_BEHAVIOR_HANDLER.
PRIVATE SECTION.
METHODS method_name1 FOR VALIDATE ON SAVE
IMPORTING keys FOR AliasedEntityName~MyValidation.
METHODS method_name2 FOR VALIDATE ON SAVE
IMPORTING keys FOR AliasedEntityName~AnotherValidation
keys2 FOR AliasedEntityName2~AnotherValidation2.
ENDCLASS.
METHOD method_name1.
// Implement method for validation here!
ENDMETHOD.
...
ENDCLASS.

2.3.2.1.8 Determine Actions
Determine Action
Determine actions allow the business object consumer to call determinations and validations on request. You
can assign determinations on save and validations to a determine action and execute it like any other action.
Whenever a determine action is called, the determinations and validations assigned to it are evaluated and
then only those determinations and validations are executed whose trigger conditions are fulfilled.
Determine actions are primarily meant to be called by side effects in order to give the user immediate
feedback after changing UI fields or field groups in draft-enabled applications. Combined with side effects,
determine actions act as an early execution of parts of the save sequence that already runs determinations and
validations before the draft instance is prepared and activated. Side effects must be defined and annotated in
the OData document. RAP offers a way to define side effects in the behavior definition, which affects the OData
annotations based on your application backend implementation. For more information, see Side Effects [page
133].
You cannot add on modify determinations to a determine action. Furthermore, feature and authorization
control are not enabled for determine actions.
You cannot execute determine actions inside implementations of determinations and validations.
In unmanaged scenarios, determine actions must be implemented manually for active instances.
Syntax for Defining Determine Actions

Determine actions are specified in the behavior definition with the DETERMINE ACTION DetActionName.
For more information about the syntax, see CDS BDL - determine actions (ABAP - Keyword Documentation).
Only determinations and validations that are defined and implemented in the BO can be assigned to a
determine action.
You can include validations and determinations for child entities, if these validations or determinations do not
include the trigger operation delete.

Learn PUBLIC 127
The always flag
When a determine action is called that contains a determination or validation with the flag always, this
determination or validation is executed regardless of its trigger conditions. After a determination with the flag
always has been executed, it can be triggered again by other determinations belonging to the same determine
action.
Execution order
After calling a determine action, assigned determinations are executed before assigned validations. The
execution order among determinations or validations themselves is defined by the framework and is
independent of the specified order within the determine action.
Messages and failed keys
Determinations and validations assigned to determine actions can return messages to the REPORTED
structure, but the failed keys of assigned validations are discarded.
The draft determine action prepare is a determine action that is implicitly available for all draft BOs.
It is automatically called before a draft instance is activated and cannot be called for active instances. If a
validation is assigned to the draft determine action prepare and detects failed keys, the subsequent
activate action is not executed anymore. The FAILED structure is not filled in this case either.
For more information, see Draft Actions [page 53].
2.3.2.1.9 Feature Control
This topic is about the concept of feature control for the ABAP RESTful application development.
About Feature Control
With feature control, you can provide information to the service on how data has to be displayed for
consumption in a SAP Fiori UI, for example if fields are mandatory or read-only.
You can implement feature control in a static or dynamic way. In a static case, you define which operations are
available for each business object entity or which fields have specific access restrictions like being mandatory
or ready-only. In a dynamic case, the access restrictions for fields or the enabling or disabling of methods
depends on the state of the business object, for example on the value of a specific field.
 Note
Note that you can only use instance feature control or global feature control on an operation or action. It's
not possible to combine both.
For more information, see Instance Feature Control [page 129].

128 PUBLIC Learn
Consumer Hints in UI Scenarios
In UI scenarios, consumer hints, which are retrieved from the backend, provide the information for the UI which
operations are enabled for the current situation. On a Fiori Elements UI, action and other operation buttons are
only displayed and clickable if authorization and feature control methods provide a positive result under the
current conditions (the state of the retrieved BO instances).
The definition and implementation of authorization and feature control is important, as the consumer hints are
based on the result of the authorization and feature control. The implementation methods for authorization
and feature control are called on displaying the list report or the object page for a specific instance. By
checking the authorization for all the exposed actions beforehand, users can't even start operations, for which
they aren't authorized, as their triggers (action buttons) aren't available.
 Example
The action SetStatusBooked can only be executed for instances, whose status isn't booked yet (feature
control) and by users that are assigned to a specific role (authorization). When selecting instances, whose
status is booked already, the button for this action isn't available on the UI and the user can't execute the
action.
Related Information
Global Feature Control [page 132]
2.3.2.1.9.1 Instance Feature Control
You can define feature control on instance level for fields, operations, and actions. With this, you can control,
for example, if a method is enabled or disabled when an instance of a business object entity has a certain
state. You can define instance-based feature control for UPDATE and DELETE, as well as for actions. Since you
need an active instance of a business object in this case, the CREATE operation can't have feature control on
instance level.
Static Feature Control
Fields
You can define specific access restrictions for each field. You can implement the restrictions in a static way if
the access restriction is always valid for each instance.
Within the behavior definition, you can specify individual fields of an entity that have certain access restrictions.
For details about the syntax, see CDS BDL - field characteristics, projection BDEF (ABAP - Keyword
Documentation) .

Learn PUBLIC 129
You can use the following field properties to define static field control:
The field (read only) property defines that values of the specified fields must not be created or updated
by the consumer. You can set this property in the behavior definition.
 Note
The BO runtime rejects external EML MODIFY requests that include read-only fields for update or create
operations.
Read-only fields that are included in OData call to update or create instances are ignored while possible
other fields are processed for update and create operations.
The field (mandatory) property defines that the specified fields are mandatory. The specified fields must
be filled by the consumer when executing modifying requests. For the relevant fields, the value must be
provided in CREATE operations. In update operations, it must not be given the null value.
 Note
The mandatory property must be set in the behavior definition, not in the projection. This property isn’t
evaluated if you've defined it in a projection.
 Caution
Note that there’s no implicit validation by the business object framework. As an application developer, you
must ensure that you’ve implemented a corresponding validation.
Operations
In a typical transactional scenario, you have to specify which operations are provided by the respective entity.
The transactional character of a business object is defined in the behavior definition where all supported
transactional operations are specified for each node of the business object’s composition tree. Whenever
the corresponding root or child entity is going to be created, updated, or deleted, these operations must be
declared in the behavior definition. In this way, you specify at the business object entity level whether each
instance is enabled for creation, update, or deletion. For more general information about operations, refer to
Operations [page 88].
For details about the syntax, see CDS BDL - standard operations (ABAP- Keyword Documentation).
The following operations are available, if they are declared for an entity in the behavior definition:
• create
• update
• delete
• internal *operation*
• _association { create;}
Actions
For more information about the syntax, see CDS BDL - action (ABAP - Keyword Documentation).
You can define actions and internal actions. If they're defined with static feature control, they're always
available for the respective entity. For more general information, see Actions.

130 PUBLIC Learn
Operation Effects
action ActionName [...] If actions are defined in the behavior definition without
dynamic feature control, they’re always available for the
respective entity.
For general information about defining and implementing

actions, refer to Actions [page 101].
internal action ActionName [...] Specific operations of an entity of a business object can
be defined using actions. Similar to standard operations,
you can define internal actions in the behavior definition
by adding the option internal to the operation name.
Internal actions can only be accessed from the business
logic inside the business object implementation such as
from validations, determinations, or from other noninternal
actions.
Dynamic Feature Control
Fields
You can define specific access restrictions for each field. You can implement the restrictions in a dynamic way
if the restrictions depend on a certain operation or condition. With dynamic feature control, you can add access
restrictions based on conditions or specify access restrictions for fields.
For details about the syntax, see CDS BDL - Field Characteristics, Projection BDEF .
You can implement dynamic feature control for fields in the behavior pool that decides upon the status for
these fields. The fields are notated with field (features: instance) in the behavior definition. In the
behavior pool, the following field statuses can be assigned:
• UNRESTRICTED– field has no restrictions

• MANDATORY– field is mandatory
• READONLY– field is read-only
• ALL– all restrictions are requested
The field (mandatory:create) triggers a check before the data is persisted. If the annotated field is not
filled in, the SAVE is rejected.
The field (readonly:update) displays a field as read-only when a business object instance is edited and
the value can't be changed via the user interface or via an external EML UPDATE request. If a field is only
defined as readonly:update without mandatory:create, the fields can't be edited on the UI.
The combination of the field (mandatory:create) and the field (readonly:update) combines the
effects of both annotations: In this case, a value must be filled in for new instances in CREATE requests and
this value can't be changed via the user interface or an EML request during a MODIFY. A typical use case would
be the definition of an ID using external numbering. The ID is defined once and isn’t to be changed when the
instance is modified.

Learn PUBLIC 131
Operations
For dynamic control of operations, the option (features: instance) must be added to the operation
or association in question. This is also possible for the create-by-association operation. However, an
implementation in the referenced class pool ABAP_CLASS is necessary for this. For each relevant operation,
you can specify the following values in the implementation of FOR INSTANCE FEATURES:
• ENABLED - if the operation is enabled

• DISABLED- if the operation is disabled
Actions
You can implement specific operations for an entity of a business object with actions. Just like the CUD-
operations, actions can be enabled or disabled using dynamic feature control. If you define actions in the
behavior definition without feature control, they’re always available for the respective business object entity
they belong to.
• action (features:instance)
For dynamic control of actions, the option (features: instance) must be added to action in question.
However, an implementation in the referenced class pool ABAP_CLASS is necessary for this. For each relevant
operation, you can specify the following values in the implementation of FOR INSTANCE FEATURES:
• ENABLED - if the action is enabled

• DISABLED - if the action is disabled
For more information about the BDL syntax, see CDS BDL - feature control (ABAP - Keyword Documentation).
For more information about the implementation syntax, see FOR INSTANCE FEATURES, FEATURES (ABAP-
2.3.2.1.9.2 Global Feature Control
You can define global feature control for feature control that is independent of the business object state, for
example if you want to disable the CREATE depending on whether a certain business scope is active or not.
Operations, associations and actions that get Global Feature Control, are provided with the suffix (features:
global).
Create|Update|Delete|Action (features:global)
For global feature control, the option (features: global) must be added to the create, update, delete,
or action operation in question. However, an implementation in the referenced class pool ABAP_CLASS is
necessary for this. For each relevant operation, you can specify the following values in the implementation of
FOR GLOBAL FEATURES:
• ENABLED - if the operation or action is enabled

132 PUBLIC Learn
• DISABLED - if the operation or action is disabled
_association {create(features:global);}
For global feature control of the create by association, the option (features: global) must be added
to the create-by-association operation in question. However, an implementation in the referenced class pool
ABAP_ClASS is necessary for this. For each relevant CREATE, you can specify in the implementing handler of
the class pool the following values in FOR GLOBAL FEATURES:
• ENABLED - if the CREATE is enabled

• DISABLED - if the CREATE operation is disabled
For more information about the BDL syntax, see CDS BDL - feature control (ABAP - Keyword Documentation).
For more information about the implementation syntax, see FOR GLOBAL FEATURES (ABAP- Keyword
Documentation).
2.3.2.1.10 Side Effects
Side effects are used to trigger data, permission, or message changes based on data changes in UI scenarios
with draft-enabled BOs.
About Side Effects
Side effects are useful in UI scenarios based on draft-enabled BOs to notify a Fiori Elements UI that data
changes of defined fields require the recalculation of other data values, permissions or messages.
Since draft-enabled scenarios use a stateless communication pattern, the UI doesn't trigger a reload of all
BO-related properties for every user input. If only certain fields are changed by the end user in edit mode, that
is on the draft BO instance, the user can't expect data consistency of displayed data on the UI at all times. In
other words, when a UI user changes data of a draft instance, there is not necessarily a READ request for all
fields that are displayed. Without side effects, this may lead to inconsistencies of displayed data on the draft
instance, for example when data is calculated based on other fields.
Side effects solve this problem. They define the interdependency between fields and other BO characteristics
to trigger a reload of affected properties. In particular, side effects are efficient since there is no full reload of all
BO-properties, but only of those that are affected by particular user input.
 Example
The total price in a travel BO is calculated based on different prices, such as booking fee, flight prices and
supplement prices. If the UI user changes the booking fee, the total price needs to be recalculated. If the
user doesn't directly save the draft BO instance, the modeled determination, with which the total amount
is usually recalculated, is not triggered and the data on the UI in the total amount field doesn't change
directly. That means, the user still sees the old total amount, which is an inconsistency and can be avoided
by side effects. With a side effect, the application developer defines the interdependency between the total
amount and the other amount fields, which triggers the determination for recalculation, whenever the UI
user changes one of the amount fields.
For a detailed description of such a side effect implementation, see Developing Side Effects [page 652].

Learn PUBLIC 133
Side effects are defined in the RAP behavior definition. The definition provokes additional annotations in the
OData metadata of the RAP service. Based on these annotations, the UI triggers the defined reloads and sends
READ requests for the respective properties. Like other behavior that is defined in the behavior definition, side
effects must be reused for consumption in every projection behavior definition.
You can also annotate the OData document directly, but with RAP side effects, as an application developer, you
can influence the UI behavior from the backend implementation.
Types of Side Effects
Side effects can be defined in the behavior definition for the following RAP BO properties:
• field: Whenever a defined field is changed on the UI, the side effect is triggered and the defined targets are
reloaded.
side effects { field MyField affects Targets }
• action: Whenever the action is executed on the UI, the side effect is triggered and the defined targets are
reloaded.
side effects { action MyAction affects Targets }
• determine action: Whenever the defined source is changed, the determine action is triggered and the
defined targets are reloaded.
side effects { determine action MyDetermineAction executed on Sources affects
Targets }
Targets
The following BO properties can be used as side effect targets:
• field: The specified field is reloaded when the side effect is triggered field MyField. You can specify
one or more fields as side effect target. The wildcard field * reloads all fields of the same entity instance.
You can also use fields from other entity instances as targets. They must be defined via an association path
_assoc.Myfield.
 Restriction
Association paths with multiple associations are currently not supported.
• permissions: The feature and authorization control of the specified properties are reloaded when the
side effect is triggered. You can specify the permissions for
• fields: permissions(field MyField),
• actions: permissions(action MyAction) and
• for the operations update and delete: permissions (update|delete).
You can also specify permissions for properties of associated entities via association path: permissions
( _assoc.{field|action|update|delete} ).
• $self: The own entity is reloaded and all fields are recalculated.
 Restriction
Currently, $self as side effect target is only possible with OData V2.
• entity: The specified associated entity is reloaded and all fields are recalculated when the side effect is
triggered: entity _MyAssoc.

134 PUBLIC Learn
 Restriction
• messages: All messages stored in reported are reloaded when the side effect is triggered.
 Restriction
Messages as side effect target are only available with OData V4.
Sources
The following BO properties can be used as sources for determine action side effects.
• field: The determine action is triggered whenever the specified field is changed: field MyField. You
can specify one or more fields as determine action source.
 Note
By using more than one field as source for the determine aciton side effect, the fields are implicitly
considered as field group. The side effect is only triggered if the cursor is set outside of the group of
source fields after changing at least one of them.
You can also use fields from other entity instances as sources. They must be defined via an association
path: _assoc.Myfield.
• $self: The determine action is triggered whenever anything on the own entity instance is changed (fields,
create child, delete child).
 Restriction
Currently, $self as side effect source or target is only possible with OData V2.
• entity: The determine action is triggered whenever anything on the specified entity is changed (fields,
create, delete): _assoc.
 Restriction
2.3.2.1.11 Business Events
About Business Events in RAP
RAP supports event-driven architecture natively. Event-driven architecture enables asynchronous

communication between an event provider and an event consumer in use cases where no direct response from
the event consumer is required. Events represent a significant change of state of the RAP business objects or
of one of its children that is relevant for follow-up processes, for example if a new travel is created and you want

Learn PUBLIC 135
to enable consuming applications to trigger additional actions when this is the case. Most commonly, event-
driven architecture is used in combination with a messaging service that notifies the event consumer when
an event occurs. This follows a publisher-subscriber pattern where the event provider triggers the messaging
when the specific event occurs and the event consumer is then notified and responsible to trigger the follow-up
actions as required by the business use case, but the event provider doesn't know about the event consumers
and there is no two-sided communication pattern. This allows for asynchronous communication between event
provider and event consumer.
A RAP BO can act as event consumer or event provider.
RAP BO as Event Provider
As event provider, an event can be defined in the behavior definition of a RAP business object with the key
word event EventName with or without parameters. After the event has been defined, it can be raised in the
behavior implementation in the late save phase. Usually, an event with the respective message is raised after
a change of state has been completed, e.g. if a BO entity like a travel or a booking has been created, updated
or deleted. When the change is saved to the database, the event is raised during the SAVE sequence after the
point of no return has passed. The Event Binding development artifact represents the design time definition
of the event and maps the event defined in a RAP BO to a namespace, a business object and a business object
operation like modify. The definition of the event in the behavior definition and the raising of the event in the
SAVE sequence represents the runtime behavior of the respective event.

136 PUBLIC Learn
RAP BO as Event Consumer
A RAP BO can consume released events in with an Event Consumption Model that establishes design time
consumption of an event from the SAP Event Mesh. For more information, see .
Event Consumption in a Cross-Product Landscape
In this cross-system communication scenario, the SAP Event Mesh acts as a messaging broker for events
defined and implemented in a RAP BO. Applications can consume the events by subscribing to the respective
messaging queues. Prerequisite to using the SAP Event Mesh, is a configured communication arrangement for
inbound and outbound communication for your respective product.
For more information about the SAP Event Mesh, see SAP Event Mesh.
2.3.2.2 Business Object Provider API
The implementation of business object functionality is done in a special type of class pool, which refers to
the behavior definition, in which the behavior for the business object is defined. For the implementation type
unmanaged, application developers must implement essential components of the REST contract themselves.
For this, all desired operations (create, update, delete) must be specified in the corresponding behavior
definition artifact by using the Behavior Definition Language (BDL) before they are implemented
with ABAP. For the implementation type managed, standard operations, such as create, update and delete
are assumed by the framework and application developers only have to implement the components of the
business logic that are part of the specific application logic as non-standard behavior.
The implementation is carried out in a special type of class pool, the behavior pool, which refers to the behavior
definition. The global class is defined with the following syntax:
CLASS ClassName DEFINITION

PUBLIC ABSTRACT FINAL
FOR BEHAVIOR OF BehaviorDefinition.
ENDCLASS.
CLASS ClassName IMPLEMENTATION.

ENDCLASS.
The concrete implementation of the business logic is based on the ABAP language and the Business Object
Behavior API.
The implementation tasks are roughly divided into an interaction phase and a save sequence. The interaction
phase is represented by the local handler class and the save sequence by the local saver class.
 Remember
There are some specific rules for assigning names to local classes in a behavior pool. Both handler
classes and saver classes are recognized by derivation from the respective system base class. The names
LCL_HANDLER and LCL_SAVER are suggested by ADT when you create the class pool, but can be changed.
We recommend applying naming conventions for behavior pools and local handler and saver classes
corresponding to Naming Conventions for Development Objects [page 306].

Learn PUBLIC 137
At the top of the class hierarchy for the BO API is the class CL_ABAP_BEHV. This class is the foundation
class for the handler and the saver class. It defines some fundamental data types to be used in the behavior
processing (such as field names in derived type structures) and also provides message creation methods.
The classes that derive from this base class are:
• CL_ABAP_BEHAVIOR_HANDLER – This class is the base class for the handler.

• CL_ABAP_BEHAVIOR_SAVER – This class is the base class for the saver. It specifies the signature of all
methods used to implement the save sequence of a business object provider.
Hierarchy Tree of the BO Behavior API
Detailed Information
• Implementing Handler Classes [page 139]

• Implementing Saver Classes [page 149]
• Using Implicit Response Parameters [page 151]
• Derived Data Types [page 150]

138 PUBLIC Learn
2.3.2.2.1 Handler Classes
To implement the behavior specified in the behavior definition, a special global ABAP class, the behavior pool is
used. This global class is implicitly defined as ABSTRACT and FINAL. So, the behavior implementation cannot
be found from outside the BO. A behavior pool can have static methods, CLASS-DATA, CONSTANTS and TYPES.
The application may place common or even public aspects of its implementation here.
The real substance of a behavior pool is located in Local Types. Here you can define two types of special local
classes: handler classes for the operations within the interaction phase and saver classes for the operations
within the save sequence.
Within the global behavior pool one or multiple local handler classes are defined. Each such local class inherits
from the base class CL_ABAP_BEHAVIOR_HANDLER. The signature of the handler methods are type-based on
the entity that is defined by the keyword FOR [OPERATION] entity. If there is an alias defined in the behavior
definition, the alias has to be used.
Syntax: Definition of the Local Handler Class

CLASS lcl_handler DEFINITION INHERITING FROM cl_abap_behavior_handler.
PRIVATE SECTION.
/* FOR MODIFY method declaration */
METHODS modify_method FOR MODIFY

[IMPORTING]

create_import_parameter FOR CREATE entity
update_import_parameter FOR UPDATE entity
delete_import_parameter FOR DELETE entity
action_import_parameter FOR ACTION entity~action_name

[REQUEST requested-fields]

[RESULT action_export_parameter]

create_ba_import_parameter FOR CREATE entity\_association.
/* FOR AUTHORIZATION method declaration */
METHODS auth_method FOR AUTHORIZATION

[IMPORTING] keys REQUEST requested_features FOR entity

RESULT result_parameter.
/* FOR FEATURES method declaration */
METHODS feature_ctrl_method FOR FEATURES


/* FOR GLOBAL FEATURES method declaration */
METHODS get_global_features FOR GLOBAL FEATURES

[IMPORTING] REQUEST requested_features FOR entity

/* FOR LOCK method declaration */


/* FOR READ method declaration */
METHODS read_method FOR READ

[IMPORTING] read_import_parameter FOR READ entity

RESULT read_export_parameter.
/* FOR READ by association method */
METHODS read_by_assoc_method_name FOR READ

[IMPORTING] read_ba_import_parameter FOR READ entity\_association

FULL full_read_import_parameter
RESULT read_result_parameter
LINK read_link_parameter.
ENDCLASS.


Learn PUBLIC 139
Method Summary
Method Description
<method> FOR MODIFY Handles all changing operations (create, update, delete, and specific actions as they are
specified in the behavior definition) of an entity
<method> FOR Implements authorization checks for accessing entities.

AUTHORIZATION
<method> FOR FEATURES Implements the dynamic feature control of entities
<method> FOR GLOBAL Implements the global feature control of entities

FEATURES
<method> FOR LOCK Implements the locking of entities corresponding to the lock properties in the behavior
definition
<method> FOR READ Handles the processing of reading requests
Method Details
• <method> FOR MODIFY [page 140]

• <method> FOR LOCK [page 44]
• <method> FOR READ [page 145]
• Authorization Implementation [page 86]
• FOR GLOBAL FEATURES (ABAP- Keyword Documentation)
• FOR INSTANCE FEATURES, FEATURES (ABAP- Keyword Documentation)
2.3.2.2.1.1 <method> FOR MODIFY
Handles all changing operations of an entity.
The FOR MODIFY method implements the standard operations create, update, delete, and application-specific
actions, as they are specified in the behavior definition.
 Tip
The FOR MODIFY method can handle multiple entities (root, item, sub item) and multiple operations
during one processing step. In some cases, it might be useful to split the handler implementation into
separate methods. Then, multiple behavior handlers, that is, multiple local behavior classes within one
global behavior pool or even in multiple global behavior pools, can be defined.

140 PUBLIC Learn
Declaration of <method> FOR MODIFY
The declaration of the <method> FOR MODIFY expresses what changing operations this method is
responsible for. In extreme cases, this is the total number of all changing operations that are possible according
to the behavior definition.
Each individual specification within the declaration of modify_method FOR MODIFY consists of a
combination of an operation with an entity or an entity part. To refer to the entities, the alias given in behavior
definition is used - if there is any.
Each operation type has an import parameter <operation>_import_parameter for the incoming
instance data and. Its name is freely selectable. The method includes an export parameter
action_export_parameter if the operation type expects one. Action, for example, can have export
parameters for their results.
The import parameters for CREATE, UPDATE and CREATE by association include the control structure
%control to identify which fields have been filled by the caller.
You can declare all operations in a single <method> FOR MODIFY:
METHODS modify_method FOR MODIFY

[IMPORTING]

update_import_parameter FOR UPDATE entity
delete_import_parameter FOR DELETE entity
action_import_parameter FOR ACTION entity~action_name

[REQUEST requested-fields]

[RESULT action_export_parameter]

create_ba_import_parameter FOR CREATE entity\_association.
You can also declare a <method> FOR MODIFY for each operation. In many cases, it can be beneficial to
implement the individual MODIFY operations in separate methods. This may be particularly the case if the
implementations for the respective operations are more extensive.

METHODS:
create_entity_method FOR MODIFY

[IMPORTING] create_import_parameter FOR CREATE entity,

update_entity_method FOR MODIFY

[IMPORTING] update_import_parameter FOR UPDATE entity,

delete_entity_method FOR MODIFY

[IMPORTING] delete_import_parameter FOR DELETE entity,

action_method FOR MODIFY

[IMPORTING] action_import_parameter FOR ACTION entity~action_name

RESULT action_export_parameter,
create_by_association FOR MODIFY

[IMPORTING] create_ba_import_parameter FOR CREATE entity\_association.

For the sake of better readability, the keyword IMPORTING can be specified before the first import parameter.
The parameters can also be explicitly declared as REFERENCE(...); However, the declaration as VALUE(...)
is not allowed and therefore the importing parameters cannot be changed in the method.
 Note
The data types with which the parameters are implicitly provided by the ABAP compiler are derived types
resulting from the behavior definition. They usually contain at least the instance key according to the
CDS definition, or even the full row type, as well as other components that result from the model (action

Learn PUBLIC 141
parameter) or other features of the BO, such as %pid in case of late numbering. For more information, see
Derived Data Types [page 150].
The method FOR MODIFY has three implicit changing parameters failed, mapped, and reported. These
parameters can (but do not need to) be explicitly declared (developers may find this explicit declaration
helpful), like this:

METHODS method_name FOR MODIFY

[IMPORTING]

...
mapped TYPE DATA

reported TYPE DATA.
Since the derived types also come here into play, you cannot explicitly write them down. The ABAP compiler
accepts the generic type DATA and replaces it with the respective derived types resulting from the behavior
definition.
Each of FAILED, MAPPED, REPORTED is a structure type with one component per entity from the behavior
definition (that is, per entity in a business object). The names of the components are the aliases defined in the
behavior definition or else the original entity names.
All parameters and components of these structures are tables to allow mass processing. Together with the
bundling of multiple operations in a method, it is possible to implement large modification requests in a single
FOR MODIFY method call.
Implementation of <method> FOR MODIFY
When is the FOR MODIFY Method Called?
The FOR MODIFY method is called when the BO framework processes a change request that contains at least
one of the operations defined in the method FOR MODIFY.
The FOR MODIFY method can determine which operations are specifically given, for example, in this way:

... parameter IS [NOT] INITIAL.

 Example

IF create_import_parameter IS NOT INITIAL.
... " code for creating entities

ENDIF.
Sequence of Processing of Individual Operations
The BO framework does not specify an order for the processing of individual operations within a FOR MODIFY
call. It is therefore assumed that the application layer processes all the individual operations that are passed
in a meaningful order for them. For example, it is usually useful to process create operations before update
operations.

142 PUBLIC Learn
Sequence of Operations Processing within a FOR MODIFY Method call – An Example
Retrieving Results from Operation Processing

To get the output of an action call with a defined RESULT, the named export parameter
action_export_parameter must be filled.
There are no explicit return parameters to be filled for all other operations. However, the three returning
structures failed, reported, and mapped must be filled when the corresponding events happen. Their
construction results in a fairly readable pattern, for example, to report failed instances or to store messages for
instances:

APPEND ... TO failed-Item.
APPEND ... TO reported-Root.

All derived types also contain components that do not originate from the line type of the entity and begin with
the character % to avoid naming conflicts with original components. For example, the row type of a failed
table contains a component %fail to store the symptom for a failed instance; Also, an include structure
%key that summarizes the primary key fields of the entity. %key is part of almost all derived types, including
operation parameters. An overview of all derived types is given in

Learn PUBLIC 143
Thus, the above pattern can be as follows:

APPEND VALUE #( %KEY = <item>-%KEY %FAIL = IF_ABAP_BEHV=>CAUSE-... %CID = ...)
TO failed-Item.

Related Information
2.3.2.2.1.2 <method> FOR LOCK
Implements the lock for entities in accordance with the lock properties specified in the behavior definition.
The FOR LOCK method is automatically called by the orchestration framework before a changing (MODIFY)
operation such as update is called.
Declaration of <method> FOR LOCK
In the behavior definition, you can determine which entities support direct locking by defining them as lock
master.
 Note
The definition of lock master is currently only supported for root nodes of business objects.
In addition, you can define entities as lock dependent. This status can be assigned to entities that depend
on the locking status of a parent or root entity. The specification of lock dependent contains the association
by which the runtime automatically determines the corresponding lock master whose method FOR LOCK is
executed when change requests for the dependent entities occur.
The declaration of the predefined LOCK method in the behavior definition is the following:



The keyword IMPORTING can be specified before the import parameter. The name of the import parameter
lock_import_parameter can be freely selected.
Import Parameters
The row type of the import table provides the following data:
• ID fields

144 PUBLIC Learn
 Note
The compiler-generated structures %CID, %CID_REF, and %PID are not relevant in the context of locking
since locking only affects persisted (non-transient) instances.
Changing Parameters
The LOCK method also provides the implicit CHANGING parameters failed and reported.
• The failed parameter is used to log the causes when a lock fails.
• The reported parameter is used to store messages about the fail cause.
You have the option of explicitly declaring these parameters in the LOCK method as follows:

IMPORTING lock_import_parameter FOR LOCK entity
reported TYPE DATA.

Implementation of method FOR LOCK
The RAP lock mechanism requires the instantiation of a lock object. A lock object is an ABAP dictionary object,
with which you can enqueue and dequeue locking request. For tooling information about lock objects, see .
The enqueue method of the lock object writes an entry in the global lock tables and locks the required entity
instances.
An example on how to implement the method FOR LOCK is given in Implementing the LOCK Operation [page
544].
Related Information
2.3.2.2.1.3 <method> FOR READ
Implements a handler for processing reading requests.
The FOR READ method is used to return the data from the application buffer. If the buffer is empty, the data is
read from the database (which typically populates the application buffer).
There are two options to read data from the application buffer:
• Direct READ, see Declaration of <method> FOR READ [page 146].

Learn PUBLIC 145
• READ by association, see Declaration of <method> FOR READ By Association [page 147].
Declaration of <method> FOR READ
Similar to <method> FOR MODIFY, the handler <method> FOR READ is also implemented to handle mass
requests. It is also designed to bundle multiple operations.

METHODS method_name FOR READ

[IMPORTING] read_import_parameter FOR READ entity

RESULT read_result_parameter.

Again, for the sake of better readability, the keyword IMPORTING can be specified before the import parameter.
The name of the import parameter read_import_parameter can be freely selected. It imports the key(s) of
the instance entity to be read and indicates which elements are requested.
The placeholder entity refers to the name of the entity (such as a CDS view) that you want to read from or to
the alias defined in the behavior definition.
The parameter RESULT is a changing parameter. Its name can be freely selected.
Import Parameters
The row type of the import table read_import_parameter provides the following:
• ID fields
• %CONTROL
The control structure reflects which elements are requested by the consumer.
Exporting Parameters
• read_result_parameter
Returns the successfully read data.
The row type of this table provides all elements that are specified in the element list of the entity that is
read. Only the requested elements, which are indicated in the %control structure, must be filled.
Changing Parameters
In addition to the explicitly declared return parameter, the READ method also provides the implicit CHANGING
parameters failed, mapped and reported.
• The failed parameter is used to log the entries that could not be read. You can specify the fail cause for
the READ, for example not_found.
• The mapped parameter must not be filled in READ implementations.
• The reported parameter must not be filled in READ implementations.
For more information about the implicitly declared parameters, see Implicit Response Parameters [page 151].

146 PUBLIC Learn
Declaration of <method> FOR READ By Association
The syntax for the READ by association is similar to the one for the direct READ.

METHODS
method_name FOR READ

[IMPORTING] read_ba_import_parameter FOR READ entity\_association

FULL full_read_import_parameter
RESULT read_result_parameter
LINK read_link_parameter.

As for the other operation implementations, the keyword IMPORTING can optionally be specified explicitly. All
parameter names can be freely selected.
The importing parameter read_ba_import_parameter imports the key(s) of the entity instance whose
associated entity instance shall be read. In addition, it indicates which elements from the associated entity
shall be read.
behavior definition, which is the source of the association.
The placeholder association refers to the association along which you want to read data, for example
_booking if you want to read all bookings associated to one travel instance.
The parameter full_read_import_parameter indicates whether the RESULT parameter must be filled or if
only the LINK parameter must be filled. It has a boolean value.
The parameter RESULT is an exporting parameter. It returns the requested elements that are indicated in the
importing parameter if the FULL parameter is set.
The parameter LINK is also an exporting parameter. It returns the key elements of the source and target
entities no matter if the FULL parameter is set.
Import Parameters
• The row type of the import table read_ba_import_parameter provides the following data:
• ID fields
• %CONTROL
The control structure reflects which elements of the associated entity are requested by the consumer.
• The type of the import parameter full_read_import_parameter is a character with boolean value.
Exporting Parameters
• read_ba_import_parameter: Returns the successfully read data from the associated entity if the FULL
parameter is set.
• read_link_parameter: Returns the source and target key of the successfully read entity instances.

Learn PUBLIC 147
Changing Parameters
In addition to the explicitly declared parameters, the method for READ by association also provides the implicit
CHANGING parameters failed, mapped, and reported.
• read_ba_import_parameter: Returns the successfully read data from the associated entity if the FULL
parameter is set.
• read_link_parameter: Returns the source and target key of the successfully read entity instances.
• The failed parameter is used to log the entries that could not be read. You can specify the fail cause for
the READ, for example not_found.
• The mapped parameter must not be filled in READ implementations.
• The reported parameter must not be filled in READ implementations.
2.3.2.2.1.4 <method> FOR FEATURES
This method implements the dynamic feature control for entities.
Dynamic feature control can be used for the standard operations update, delete, and
create_by_association, for actions and on field level. Depending on the feature conditions is the operation
executable or not. The <method> FOR FEATURES is called by the RAP runtime engine for every operation or
field that is dynamically controlled.
Declaration of <method> FOR FEATURES
The operations or fields that are dynamically controlled are defined in the behavior definition with features:
instance.
The dynamic feature control for an entity is implemented in a handler class using the method
feature_ctrl_method. The signature of this handler method is defined by the keyword FOR FEATURES,
followed by the input parameters keys and the requested_features of the entity.

METHODS feature_ctrl_method FOR FEATURES


RESULT result.
Again, for the sake of better readability, the keyword IMPORTING can be specified before the import parameter.
 Note
The name of the <method> FOR FEATURES can be freely chosen. Often get_features is used as
method name.

148 PUBLIC Learn
Import Parameters
• keys
The table type of keys includes all elements that are specified as a key for the related entity.
• requested_features
The structure type of requested_features reflects which elements (fields, standard operations and
actions) of the entity are requested for dynamic feature control by the consumer.
Export Parameters
The export parameter result is used to return the feature control values. It includes, besides the key fields,
all the fields of the entity, standard operations and actions for which the features control was defined in the
Export Parameters
In addition to the explicitly declared export parameter, the FOR FEATURE method also provides the implicit
CHANGING parameters failed and reported.
Related Information
2.3.2.2.2 Saver Classes
The save sequence is called for each business object after at least one successful modification was performed
using the BO behavior APIs in the current LUW.
For more information, see Save Sequence Runtime [page 225].
Method Details
• FINALIZE [page 228]

• CHECK_BEFORE_SAVE [page 229]
• ADJUST_NUMBERS [page 230]
• SAVE [page 231]
• CLEANUP [page 233]
• CLEANUP_FINALIZE [page 234]

Learn PUBLIC 149
2.3.2.2.3 Derived Data Types
In the behavior implementation of a business object, you make use of data types which the ABAP compiler
implicitly derives from the involved CDS views and the behavior definition. These derived data types contain
key and data fields of CDS entities and ensure the type-safe access to RAP BOs.
Derived Data Types in Method Signatures
The parameters of method signatures for RAP operations are mainly typed with derived data types.
 Example
The following method signature originates from the managed flight reference scenario (/DMO/
FLIGHT_MANAGED).

METHODS copyTravel FOR MODIFY IMPORTING keys FOR ACTION travel~copyTravel.
Based on this signature, the ABAP compiler determines the following import and changing parameters with
the corresponding derived data types:

IMPORTING keys TYPE TABLE FOR ACTION IMPORT /DMO/I_TRAVEL_M\
\travel~copytravel
CHANGING mapped TYPE RESPONSE FOR MAPPED EARLY /DMO/I_TRAVEL_M
failed TYPE RESPONSE FOR FAILED EARLY /DMO/I_TRAVEL_M
reported TYPE RESPONSE FOR REPORTED EARLY /DMO/I_TRAVEL_M

The parameters mapped, failed and reported are response parameters that are implicitly added during
design time.
For more information on response parameters, see Implicit Response Parameters [page 151].
Explicit Declaration of Derived Data Types
Derived data types can also be used to explicitly declare variables. For example, an internal table can be
declared with the type TYPE TABLE FOR:
travels TYPE TABLE FOR CREATE /DMO/I_Travel_M\\travel
This variable can then be used in EML to create instances of the travel entity.
For further information on EML, see Entity Manipulation Language (EML) [page 235].
For further information on the explicit decaration with derived data types, see Declaration of Variables with
BDEF Derived Types (ABAP-Keyword Documentation).

150 PUBLIC Learn
Components of Derived Data Types
Internal structures and tables declared with derived data types do not only contain key and data fields, but
also other components that do not derive their line type from the entity. These components have special,
tailor-made line types that provide additional information required in the context of transactional processing.
The names of those RAP components begin with % to avoid naming conflicts with components of the CDS
entities. Among the components, there are component groups available for summarizing groups of table
columns under a single name. They begin with % as well and simplify the handling of derived types for
developers. For example, %key summarizes all primary keys. The use of the components depends on the RAP
operation and/or context, for example, %pid is only available for late numbering scenarios.
Components of derived data types can also be used to type internal structures or tables:

TYPES: it_booking_update TYPE TABLE FOR UPDATE /DMO/I_Travel_M\\travel,
ltype_for_update TYPE LINE OF it_booking_update,

ltype_for_key TYPE ltype_for_update-%key.
For further information on the components of derived data types, see Components of BDEF Derived Types
2.3.2.2.4 Implicit Response Parameters
When implementing a BO contract, you make use of implicit response parameters. These parameters do not
have fixed data types and instead are assigned by the compiler with the types derived from behavior definition.
The implicit parameters can be declared explicitly as CHANGING parameters in the method signature of the
handler classes by using the generic type DATA:

METHODS method_name FOR MODIFY | READ | LOCK

[IMPORTING]

<operation>_import_parameter FOR <OPERATION> entity
...

[mapped TYPE DATA] "Relevant for CREATE only

reported TYPE DATA.

The ABAP compiler replaces the type DATA with the respective derived types resulting from the concrete

Learn PUBLIC 151
Implicit Parameters
Parameter Description
FAILED This exporting parameter is defined as a nested table which contains one table for each entity
defined in the behavior definition.
The failed tables include information for identifying the data set where an error occurred:
• %CID and
• ID of the relevant BO instance.
The reason for the failure is specified by the predefined component:
• %FAIL, which stores the symptom of the failure.
Accessing Element Information for Failed Parameter Type (F2)

152 PUBLIC Learn
Parameter Description
REPORTED This exporting parameter is used to return messages. It is defined as a nested table which con-
tains one table for each entity defined in the behavior definition.
The reported tables include data for instance-specific messages.
The data set for which the message is relevant is identified by the following components:
• %CID
• ID of the relevant instance
• %MSG with an instance of the message interface IF_ABAP_BEHV_MESSAGE
• %ELEMENT which refers to all elements of an entity.
Accessing Element Information for a Reported Parameter Type (F2)
 Note
Messages that are not related to a specific (entity) instance can be returned using the
%OTHERS component.
MAPPED This mapped parameter is defined as a nested table which contains one table for each entity
defined in the behavior definition.
The mapped parameters provide the consumer with ID mapping information. They include the
information about which key values were created by the application for given content IDs. The BO
runtime passes the created key values in any subsequent calls in the same request and in the
response.
The relevant data set is identified by the following components:
• %CID
• %KEY
(Copied Content from derived types topic)
• MAPPED [LATE] - The mapped result parameters provide the consumer with ID mapping information.
By default, the mapping information is already available in the interaction phase (early mapped). The CID

Learn PUBLIC 153
is then mapped to the real key or to the PID. Using the addition LATE, you specify that the mapping
information is only available in the save sequence. This plays a role when providing the late numbering (see
also: ADJUST_NUMBERS [page 230]) where the PID is mapped to the real key.
• FAILED [LATE] - The failed parameters include information for identifying the data set where an error
occurred. (Early) FAILED is provided during the interaction phase and contains the CID or the KEY to
indicate instances for which an operation failed. FAILED with the additional specification LATE is only
provided during the save sequence and contains the PID or the KEY, but not the CID.
• REPORTED [LATE] - The reported parameters are used to return messages in case of failure. (Early)
REPORTED is provided during the interaction phase and contains the CID or the KEY to indicate instances
for which an operation failed. REPORTED with the additional specification LATE is only provided during the
save sequence and contains the PID or the KEY, but not the CID.
• READ RESULT
Components of Derived Data Types
All derived data types in the context of the ABAP RESTful programming model also contain components that
do not originate from the row type of the entity and begin with the character % to avoid naming conflicts with
original components. For example, the row type of a failed table contains a component %fail to store the
symptom for a failed instance and also an include structure %key that contains all primary key fields of the
entity.
EXAMPLE: Usage of %... components in a failed parameter

APPEND #VALUE(%KEY = ... %FAIL = ...) TO failed-entity.

The following list provides you with a description of the most common %... components:
Component Description
%CID The content ID %CID is a temporary primary key for an instance, as long as no primary key was
created by the BO runtime.
The content ID is always provided by the SADL framework. It is only needed in case of internal
numbering and/or late numbering. The content ID provides the reference between the related
entity instances. A good example is a DEEP INSERT for multiple parent/child instances with
internal numbering and/or late numbering. In this case, the references between the child and
parent instances are established using the content ID %CID.
%CID_REF A reference to the content ID %CID.
%tky Contains all key elements of an entity (CDS view) including the derived key components, for
example %IS_DRAFT in draft scenarios.
%tky is part of almost all derived types, including trigger parameters in the for modify( )
method.

154 PUBLIC Learn
Component Description
%PID Defines the preliminary ID, before the final key is set in the ADJUST_NUMBERS method..
The preliminary ID is only available when LATE NUMBERING is defined in the behavior definition
without the addition IN PLACE.
%CONTROL Reflects which elements are requested by the consumer.
The fields of the %CONTROL structure provide information, depending on the operation, about
which elements of the entity are supplied in the request (for CREATE and UPDATE operations) or
which elements are requested in the read request (for READ operations).
For each entity element, this control structure contains a flag which indicates whether the corre-
sponding field was provided/requested by the consumer or not.
The element names of the entity have the uniform type ABP_BEHV_FLAG.
 Note
The possible constants are defined in the basis handler interface if_abap_behv=>mk-
<...>. For example, the elements that have the value if_abap_behv=>mk-on in the
%CONTROL structure are used to handle delta updates within the UPDATE operation.
%DATA Contains all data elements of an entity (CDS view).
%FAIL Stores the symptom for a failed data set (BO instance).
 Note
The possible values (unspecific, unauthorized, not_found, and so on) are defined
by the ENUM type IF_ABAP_BEHV=> T_FAIL_CAUSE.
%MSG Provides an instance of the message interface IF_ABAP_BEHV_MESSAGE.
 Tip
The component %MSG of type REF TO IF_ABAP_BEHV_MESSAGE includes

IF_T100_DYN_MSG. If you do not need your own implementation of this interface, then
you can benefit from the provided standard implementation by using the inherited methods
new_message( ) or new_message_with_text( ).
%ELEMENT Refers to all elements of an entity.
%PARAM Holds the import/result type of actions.

Learn PUBLIC 155
2.3.3 RAP BO Best Practices
Here you can find best practices for RAP BO providers and consumers. Best practices also include
recommended guidelines about how to model your RAP business object.
RAP Business Object Contract [page 156]

The RAP business object contract defines a set of rules for the business object provider and consumer
implementation to ensure consistency and reliability.
Strict Mode [page 184]

The strict mode ensures that a RAP business object is lifycycle-stable and upgrade-save.
2.3.3.1 RAP Business Object Contract
The RAP business object contract defines a set of rules for the business object provider and consumer
implementation to ensure consistency and reliability.
A RAP business object represents a typed API that is integrated in the ABAP language. When consuming a RAP
BO, either via EML or via service binding (eg OData), the consumer must be sure that the result of any request
is reliable and consistent and that every request returns the same results under the same circumstances. It's
the provider's responsibility to ensure these correct results, no matter if the RAP BO provider is managed or
unmanaged.
 Example
Given the situation that a RAP consumer executes a create request. It is expected that the RAP BO either
returns a new instance (represented by the primary key of this instance), or reports a fail cause in case the
create request was not executable.
The RAP business object contract defines the expectations for a BO consumer and at the same time provides
guidelines for the provider of what needs to be implemented to fulfill these expectations. It is defined by a set
of rules, which is illustrated in the following topics. These rules will help you, as an application developer, to
implement the RAP handler methods correctly.
Some of the contract rules are enforced by runtime checks. For example, using an EML MODIFY statement in a
read-only implementation results in a runtime error. Other contract rules can be checked by running the ABAP
test cockpit, see . For your applications to be upgrade-stable and sustainable, it is absolutely indispensable that
you stick to the guidelines that are presented in the following sections.
You will find general RAP BO provider rules as well as information for each RAP implementation method.
General RAP BO Implementation Contract [page 157]
Implementation Contract: READ [page 164]
Implementation Contract: READ-BY-ASSOCIATION [page 166]
Implementation Contract: CREATE [page 168]
Implementation Contract: CREATE-BY-ASSOCIATION [page 169]
Implementation Contract: UPDATE [page 172]

156 PUBLIC Learn
Implementation Contract: DELETE [page 173]
Implementation Contract: LOCK [page 174]
Implementation Contract: Action [page 176]
Implementation Contract: Function [page 179]
Implementation Contract: Feature Control [page 180]
2.3.3.1.1 General RAP BO Implementation Contract
This topic explains general rules that apply to all behavior implementation methods of a RAP business object.
Each RAP BO provides a typed API with which the BO provider and consumer can communicate. Dedicated
methods are provided by the RAP framework to implement the behavior for a RAP business object. The
RAP runtime framework ensures stability and consistency of RAP business objects and thus expects certain
implementation in the dedicated handler and saver methods. Consequently, there are statements that do
not coincide with the predefined functionality of these RAP implementation methods and which are therefore
forbidden.
General Rules
Scope Forbidden Statements
Forbidden ABAP statements in all RAP handler methods

• EML COMMIT ENTITIES
• EML ROLLBACK ENTITIES
• COMMIT WORK
• ROLLBACK WORK
•  Home CALL FUNCTION function IN
UPDATE TASK
•  Home CALL FUNCTION IN BACKGROUND
UNIT
•  Home SUBMIT AND RETURN
•  Home Any SCREEN- / SAP GUI-related statement,
for example
• CALL SCREEN
• SET SCREEN
• MESSAGE
• CALL DIALOG
• CALL TRANSACTION
Forbidden ABAP statements in read-only RAP handler meth-

• EML MODIFY ENTITIES
ods
Forbidden ABAP statements in all RAP saver methods

•  Home SUBMIT AND RETURN

Learn PUBLIC 157
Scope Forbidden Statements
Forbidden ABAP statements in late save phases

•  Home CALL FUNCTION function IN
(ADJUST_NUMBERS, SAVE)
UPDATE TASK
•  Home CALL FUNCTION IN BACKGROUND
UNIT
Importing Parameters
The importing parameters differ among the RAP handler and saver classes. Some methods require a complete
set of instance data, other don't operation on instances at all. There are, however, common components of
these importing parameters.
Instance-Bound Operations
Implementation methods for instance-bound operations always import the instance identifier to identify the
instance on which the operation is to be executed. The instance identifier can either be %tky or %cid_ref.
Both instance identifiers need derived types components such as %is_draft or %pid to uniquely identify an
instance if more than one version can be available on the transactional buffer. Whereas %tky contains these
components, they must accompany %cid_ref in referencing operations.
Static Operations
Implementation methods for static (non-instance bound) methods do not import an identifier of an instance.
Instead, it is indispensable that they import the content identifier %cid as an identifier of the operation on a
specific instance.
Input Identifiers
The identifying components, which are either instance identifier or content identifier, of the importing
parameter are called input identifiers in the following.
The following tables give an overview of rules and guidelines for components of importing parameters.
Importing Parameter Components Expected Provider Implementation
%tky It is recommended to use the transactional key %tky for

all implementation methods. It contains the actual key fields
along with other components that are needed for unique
identification of a certain entity instance depending on the
scenario.
In draft scenarios, the transactional key contains the draft

indicator %is_draft to differentiate between draft instan-
ces and active instances on the buffer.
content identifier %cid For operations that require a content identifier on consump-
tion, %cid must always be reflected in the response struc-
tures, even if the %cid was replaced with an instance identi-
fier during the interaction phase.

158 PUBLIC Learn
Importing Parameter Components Expected Provider Implementation
An imported content identifier is always unique across all

operations of one modify request. The RAP runtime engine
checks this before calling the RAP handler method.
%cid_ref The derived type component %cid_ref is used in opera-

tions that reference an instance that is identified with %cid
in prior operations in the same LUW.
The component %cid_ref always refers to a content iden-

tifier in the same request.
In draft-enabled BOs, the component %is_draft must

always correspond to the instance of the referenced con-
tent identifier. Only the combination of %cid_ref and
is_draft can clearly identify an instance of a draft BO.
For operations that use %cid_ref to identify a new in-

stance, %cid_ref must always be reflected in the re-
sponse structures, even if the %cid_ref was replaced with
an instance identifier during the interaction phase by the
RAP runtime engine. This is the case if creating operation
and referencing operation are implemented in separate han-
dler methods.
In a handler method that returns failed for a referencing

operation (one that uses %cid_ref), the implementation
returns %cid_ref in failed-%cid and the determined
%tky in failed-%tky.
If the creating operation (one that uses %cid) and the refer-
encing operation are implemented in separate handler meth-
ods, the determined %tky is imported into the referencing
%cid_ref-operation by the RAP runtime engine.
If the operations are implemented in one handler method,

the implementation determines the %tky in the creating op-
eration and sets it as the failed-%tky of the referencing
operation.
Response Parameters
The RAP implementation methods have a common response pattern for which general rules apply. The
provider makes use of these predefined and typed response structures to return information about the
executed operation back to the consumers. The guidelines and rules on how to implement RAP handler
and saver methods and how to fill these response parameters are subject to this documentation. The
following table contains general provider information and rules for the common response parameters and
their components.

Learn PUBLIC 159
Response Parameters
Response Parameter Expected Provider Implementation
failed The failed response parameter only contains a subset (0

- n) of input identifiers.

160 PUBLIC Learn
The component %fail must contain the correct fail cause.
The following fail causes are available:
Fail Cause Usage
not_found For instance operation han-

dler methods if the re-
quested instance does not
exist.
locked For the lock handler method

if the requested instance is
already locked by another
user.
unauthorized • Is set by the RAP

runtime engine if
an authorization han-
dler method returns
unauthorized in
result.
• In modify handler
methods of unmanaged
BOs if authorization
is not implemented in
authorization handler
methods.
disabled • Is set by the RAP run-

time engine if a feature
control handler method
returns disabled for
operations in result.
BOs if feature control
feature control handler
methods.
readonly • Is set by the RAP run-

time engine if a feature
control handler method
returns disabled for
fields in result.

Learn PUBLIC 161
Fail Cause Usage
BOs if feature control

feature control handler
methods.
dependency • Is set by the RAP run-

time engine for depend-
ent operations with
%cid_ref if the cor-
responding operation
with %cid fails.
• In the create-by-associ-
ation handler method
for the target instance
if the CBA fails on the
source instance.
conflict Is only set by the RAP run-

time engine.
unspecific Any other failures.
For other fail causes than not_found or locked, the

failed operation in %op must be provided.
Exception:
No operation is provided for
• failed output instances in an instance factory action.

• failed target instances in a create-by-association opera-
tion.
 Example
If a create-by-association operation fails with fail

cause not_found on the source instance, the
target instances are listed in the target entity's
failed parameter with fail cause dependency.
But %create is only used for direct creates, and
not for create-by-association.
mapped The mapped response parameter only contains a subset (0

- n) of input identifiers.
The mapped response parameter does not contain dupli-

cate entries.

162 PUBLIC Learn
All input identifiers that are not part of mapped must be

part of failed in the relevant implementation methods.
If the mapped response parameter is not relevant, it stays

empty. For example in instance actions.
reported The reported response parameter can always be filled by

the implementation to return messages.
For severe fail causes the severity error is provided.
For the following fail causes, the reported response pa-

rameter must be filled:
• unspecific
• locked
• unauthorized
• disabled
• readonly
• dependency
The component %op must always be filled to indicate the

operation the message relates to.
The reported response parameter contains a subset (0 -

n) of input identifiers.
Exception:
For entity instances of a lock dependent or an authorization

dependent entity, the instance identifier provided in the re-
ported structure is not the input instance identifier. In this
case, the reported structure provides the instance identifier
of every entity instance of the composition structure up to
the root.
 Example
If the fail cause of an operation on a child instance

(lock dependent) is locked, the reported response
parameter contains the key of the root instance (lock
master).
State messages in reported must always refer to an in-

stance with an instance identifier. They cannot refer to a
content identifier.

Learn PUBLIC 163
State messages are not allowed in the response of the fol-

lowing behavior implementation methods:
• read
• functions
• authorization control
• feature control
• lock
• precheck
• early numbering
• any behavior implementation of newly defined behavior
in the projection behavior definition.
result The result response parameter always contains a subset

of input identifiers (o..n).
The result response parameter does not contain dupli-

cate entries.
All input identifiers that are not part of result must be

part of failed (if result cardinality is greater or equal than
1).
Input identifiers may only appear as often as the highest

value of the result cardinality unless there are duplicates in
the input.
 Example
If result cardinality is 1 or 0..1, one input instance iden-

tifier can only be listed once at most.
The result response parameter must contain at least all

requested fields. It may contain others.
2.3.3.1.1.1 Implementation Contract: READ
This topic explains the rules for implementing the read operation in a RAP business object.
The read operation is used to read data from the transactional buffer.
The implementation is done in the ABAP behavior pool in the method <method> FOR READ [page 145].
A BO consumer triggers the read operation with an ABAP EML read request by specifying the key value of the
requested instance. The BO consumer expects the data of the requested instance to be returned by the read
operation, if an instance with the given key exists. It is the BO provider's responsibility to return consistent and
reliable results for any valid request. For more information, see READ [page 241].

164 PUBLIC Learn
Input
The following list defines which components are imported into the read handler method.
Obligatory
• Instance identifier: %tky
Output
The following table summarizes the provider rules for the read implementation.
Read Implementation Specific Rules

Expected Provider Imple-
Description mentation Example Further information
Successful read operation. Implementation returns ex- Existing instance identifiers. result [page 164]
actly one row for each ex-
Duplicate existing instance
isting instance identifier in
identifiers.
result. It does not return
duplicate entries.
At least the requested

fields are returned, optionally
more.
For source and target in-

stances that do not have
any changes on the transac-
tional buffer, the implemen-
tation returns exactly the
same result as an ABAP
SQL select on the cor-
responding CDS entities re-
turns form the database. The
result may only differ in BOs
with suppressed or mod-
ify-enabled fields. (field
(suppress) and field
(modify))
Read operation as check. Implementation returns ex- Check if an instance for a re- failed [page 160]
actly one row for each non- spective key exists
existing instance identifier in
failed. It does not return
duplicate entries or result.

Learn PUBLIC 165
Unsuccessful read operation. Implementation returns one Non-existing (duplicate) in- failed [page 160]
row for each non-existing instance identifiers. (Fail cause
stance identifier in failed. not_found.)
It lists the instance identifier
Unauthorized read access.
with the correct fail cause
(Fail cause not_found.)
and initial %op. (Duplicates
may appear.)
2.3.3.1.1.2 Implementation Contract: READ-BY-ASSOCIATION
This topic explains the rules for implementing the read-by-association (RBA) operation in a RAP business
object.
The read-by-association operation is used to read data from the transactional buffer, or from the CDS entity if
the relevant entity is not yet present in the transactional buffer, by following an association from a source entity
instance to all associated target instances.
The implementation is done in the ABAP behavior pool in the method <method> FOR READ [page 147].
A BO consumer triggers the RBA operation with an ABAP EML read request by specifying the key value of
the source entity instance. The BO consumer expects that the read-by-association implementation returns
the data of the associated instances, if a source instance with the given instance identifier exists. It is the BO
provider's responsibility to return consistent and reliable results for any valid request. For more information,
see READ BY Association [page 242].
Input
The following list defines which components are imported into the RBA handler method.
Obligatory
• Instance identifier: %tky

• Flag for full result
Output
The following table summarizes the provider rules for the RBA implementation.

166 PUBLIC Learn
Read-By-Association Implementation Specific Rules
Successful RBA operation. If full result is requested: Existing source instance result [page 164]
Implementation returns ex- identifiers.
actly one row for each found
Duplicate existing source in-
target instance of an existing
stance identifiers.
source instance identifier in
result. It lists all existing
target instances. It does not
return duplicate entries. At
least the requested fields of
the target instances are re-
turned, optionally more.
For source and target in-

stances that do not have
any changes on the transac-
tional buffer, the implemen-
tation returns exactly the
same result as an ABAP
SQL select on the cor-
responding CDS entities re-
turns form the database. The
result may only differ in BOs
with suppressed or mod-
ify-enabled fields. (field
(suppress) and field
(modify))
If link table is requested:

Implementation returns ex-
actly one row for each com-
bination of source and target
instance. In every row it lists
the source instance identifier
with the associated target in-
stance identifier.
Unsuccessful RBA operation. Implementation returns one Non-existing (duplicate) in- failed [page 160]
Failure on source instance. row for each non-existing stance identifiers. (Fail cause
source instance identifiers in not_found.)
failed. It lists the source
not_found.)
instance identifiers with the
correct fail cause and ini-
tial %op. (Duplicates may ap-
pear.)

Learn PUBLIC 167
2.3.3.1.1.3 Implementation Contract: CREATE
This topic explains the rules for implementing the create operation in a RAP business object.
The create operation is used to create new entity instances of a RAP BO on the transactional buffer.
The implementation is done in the ABAP behavior pool in the method <method> FOR MODIFY [page 140].
A BO consumer triggers the create operation with an ABAP EML create request. The BO consumer expects
that the keys of successfully created instances are returned by the create operation. For more information, see
MODIFY [page 244].
Input
The following list defines which components are imported into the create handler method.
Obligatory
• Content identifier for output instances: %cid

• Any target field that is mandatory on create.
Optional
• Instance identifier for output instances: %tky

• Any target field that is not read-only.
Output
The following table summarizes the provider rules for the create implementation.
Create Implementation Specific Rules

Successful create operation. Implementation returns ex- Distinct content identifiers. mapped [page 162]
actly one row for every cre-
Non-existing instance identi-
ated instance in mapped.
fiers for output instances.
It lists the content identifier
with the corresponding map-
ped instance identifier of the
new instance.

168 PUBLIC Learn
Unsuccessful create opera- Implementation returns one Existing instance identifiers failed [page 160]
row for each failed instance
tion. for output instances. (Fail
identifier in failed. It lists
cause unspecific.)
the content identifier with
the correct fail cause and Duplicate instance identifi-
flags the %create compo- ers: For duplicate instance
nent.
identifiers with distinct con-
For every input identifier tent identifiers, the imple-
listed in failed, there is mentation can decide if all in-
one related error message stances fail, or all except one.
returned in reported. (Fail cause unspecific.)
Unauthorized for create op-

eration. This is only applica-
ble if authorization is imple-
mented in modify handlers
in an unmanaged BO. (Fail
cause unauthorized.)
Feature-control disabled
field/operation. This is only
applicable if feature control is
implemented in modify han-
dlers in an unmanaged BO.
(Fail cause disabled or
readonly.)
2.3.3.1.1.4 Implementation Contract: CREATE-BY-

ASSOCIATION
This topic explains the rules for implementing the create-by-association operation in a RAP business object.
The create-by-association (CBA) operation is used to create new entity instances on the transactional buffer by
following an association from a source entity in a RAP BO.
A BO consumer triggers the create-by-association operation with an ABAP EML create request. The BO
consumer expects that the keys of successfully created associated instances are returned by the CBA
operation. For more information, see MODIFY [page 244].
Input
The following list defines which components are imported into CBA handler method.

Learn PUBLIC 169
Obligatory
• Source instance identifier: source-%tky and source-%cid_ref
• Target content identifier: target-%cid
• Any target field that is mandatory on create.
Optional
• Target instance identifier: target-%tky
• Any target field that is not read-only.
Output
The following table summarizes the provider rules for the CBA implementation.
Create-By-Association Implementation Specific Rules

Successful CBA operation. Implementation returns ex- Existing source instance mapped [page 162]
actly one row for every identifiers.
created target instance in
Non-existing target instance
the target entity's mapped
identifiers.
structure. It lists the content
identifier of every created
target instance mapping it to
the target instance identifier.

170 PUBLIC Learn
Unsuccessful CBA operation. Implementation returns one Non-existing source in- failed [page 160]
row for each failed source instance identifier. (Fail
Failure on source instance.
put identifier in the source cause not_found on
entity's failed structure. source instance, fail cause
It fills the correct fail cause dependency on target in-
and flags the %assoc com- stances.)
ponent on the correct associ-
Unauthorized for CBA oper-
ation.
ation. This is only applica-
Implementation returns one ble if authorization is imple-
row for each target instance mented in modify handlers
that was to be created in an unmanaged BO. (Fail
in failed with fail cause cause unauthorized.)
dependency. Feature-control disabled
For every input identifier field/operation. This is only
listed in failed with applicable if feature control is
fail cause other than implemented in modify han-

dlers in an unmanaged BO.
not_found, there is one re-
lated error message returned (Fail cause disabled or
in reported. readonly.)
Unsuccessful CBA operation. Implementation returns one Existing instance identifiers failed [page 160]
row for each target instance for target instances. (Fail
Failure on target instance.
that was to be created in the cause unspecific
failed structure of the tar-
unspecifc). (Duplicate
get entity. It lists the target
target content identifier can-
content identifiers with an
not reach implementation
adequate fail cause.
method. There will be a run-
For every input identifier time error before.)Duplicate
listed in failed with target instance identifiers:
fail cause other than For duplicate target instance
not_found, there is one re- identifiers with distinct con-
lated error message returned tent identifier, the implemen-
in reported. tation can decide if all target
instances fail, or all except
one. (Fail cause
field. This is only applicable
if feature control is imple-
cause readonly.)

Learn PUBLIC 171
Unsuccessful dependent The RAP runtime engine Duplicate target instance failed [page 160]
CBA operation in the same
adds the entries for failed identifiers: For duplicate tar-
handler. (CBA that uses
get instanceThe create and
%cid_ref in the same han- and reported for the tar-
the CBA operation are im-
dler as the corresponding op- get instances. The implemen-
plemented in the same han-
eration with %cid.) tation must not fill them.
dler and the create operation
fails. The dependent opera-
tion CBA fails accordingly.
2.3.3.1.1.5 Implementation Contract: UPDATE
This topic explains the rules for implementing the update operation in a RAP business object.
The update operation is used to change entity instances of a RAP BO on the transactional buffer.
A BO consumer triggers the update operation with an ABAP EML update request. The BO consumer expects
the update is successful or that the keys of unsuccessful updates are returned by the update operation
implementation in the failed response parameters. For more information, see MODIFY UPDATE [page 247] .
Input
The following list defines which components are imported into the update handler method.
Obligatory
• Instance identifier: %tky and %cid_ref
Optional
• Any field that is not read-only.
Output
The following table summarizes the provider rules for the update implementation.

172 PUBLIC Learn
Update Implementation Specific Rules
Successful update operation. Implementation changes Existing instance identifiers.

data for instances on the
Unsuccessful update opera- Implementation returns one Non-existing (duplicate) in- failed [page 160]
tion. row for each failed instance stance identifiers. (Fail cause
identifier in failed. It lists not_found.)
the instance identifiers with
Unauthorized for update op-
the correct fail cause and
flags the %update compo-
nent. (Duplicates may ap-
pear.)
For every input identifier cause unauthorized.)
listed in failed with
fail cause other than
not_found, there is one re- applicable if feature control is
lated error message returned implemented in modify han-
in reported. dlers in an unmanaged BO.
readonly.)
2.3.3.1.1.6 Implementation Contract: DELETE
This topic explains the rules for implementing the delete operation in a RAP business object.
The delete operation is used to delete entity instances of a RAP BO on the transactional buffer.
A BO consumer triggers the update operation with an ABAP EML delete request. The BO consumer expects
that the delete is successful or that the keys are returned by the delete operation implementation in the
failed response parameter. For more information, see DELETE [page 248] .
Input
The following list defines which components are imported into the delete handler method.
Obligatory
• Instance identifier: %tky and %cid_ref

Learn PUBLIC 173
Output
The following table summarizes the provider rules for the delete implementation.
Delete Implementation Specific Rules

Successful delete operation. Implementation deletes the Existing instance identifiers.

requested entity instance on
the transactional buffer.
Unsuccessful delete opera- Implementation returns one Non-existing (duplicate) in- failed [page 160]
tion. row for each failed instance stance identifiers. (Fail cause
identifier in failed. It lists not_found.)
the instance identifiers with
Unauthorized for delete op-
the correct fail cause and
flags the %delete compo-
nent. (Duplicates may ap-
pear.)
For every input identifier cause unauthorized.)
field/operation. This is appli-
not_found, there is one re- cable if feature control is
readonly.)
Delete operation on a draft

instance. Draft instances can
only be deleted via the draft
action Discard. A delete on
a draft instance fails with fail
cause disabled.
2.3.3.1.1.7 Implementation Contract: LOCK
This topic explains the rules for implementing the lock operation in a RAP business object.
The lock operation is used to lock entity instances of a RAP BO.
The implementation is done in the ABAP behavior pool in the method <method> FOR LOCK [page 44].
A BO consumer triggers the lock operation with an ABAP EML lock request. The BO consumer expects that the
lock is successful or that the keys are returned by the lock operation implementation in the failed response
parameter. For more information, see SET LOCKS [page 255].

174 PUBLIC Learn
Input
The following list defines which components are imported into the lock handler method.
Obligatory
• Instance identifier: %key
Output
The following table summarizes the provider rules for the lock implementation.
Lock Implementation Specific Rules

Successful lock operation. Implementation locks the re- Existing instance identifiers.
quested entity instance.
identifiers. They are merged
by the RAP runtime engine
before they reach the lock
handler.
Non-existing instance
identifiers. (Fail cause
not_found or locked.)
The lock operation can, but
does not have to check the
existence of the input instan-
ces.
Unsuccessful lock operation. Implementation returns one Non-existing instance locked [page 161]
row for each failed instance identifiers. (Fail cause
identifier in failed. It lists not_found or locked.)
the instance identifier with The lock operation can, but
the correct fail cause and ini- does not have to check the
tial %op. (Duplicates may ap- existence of the input instan-
pear.) ces.
Instances are already locked

by another user. (Fail cause
locked.)

Learn PUBLIC 175
2.3.3.1.1.8 Implementation Contract: Action
This topic explains the rules for implementing an action operation in a RAP business object.
The action operation is used to modify entity instances of a RAP BO on the transactional buffer based on
custom logic.
The implementation is done in the ABAP behavior pool in a method FOR MODIFY, see Action Implementation
[page 106].
A BO consumer triggers the action operation with an ABAP EML modify request executing an action. The BO
consumer expects that the action is successful or that the input identifier is returned by the action operation
implementation in the failed response parameter. For more information, see MODIFY ACTION [page 248].
Input
The following table defines which components are imported into the action handler method.
Input Components for Actions

Action Type Obligatory Input Components
Instance non-factory action

Instance identifier: %tky and %cid_ref
Static non-factory action

Content identifier: %cid
Instance factory action

Instance identifier: %tky and %cid_ref
Static factory action

Output
The following table summarizes the provider rules for the action implementation.

176 PUBLIC Learn
Action Implementation Specific Rules
Successful non-factory ac- If the action has a result Existing instance identifiers result [page 164]
tion. parameter, the implementa- on instance actions.
tion fills the response param-
Distinct content identifiers of
eter result. For every out-
static actions.
put parameter instance, it
lists the input identifier and
the calculated action result
in %param. The parameter
mapped must not be filled
for non-factory actions.
Successful factory action. Implementation returns ex- Existing instance identifiers mapped [page 162]
actly one row for every cre- on instance actions.
ated instance in mapped.
Distinct content identifiers.
It lists the content identifier
with the corresponding map-
ped instance identifier of the
new instance.
Unsuccessful non-factory ac- Implementation returns one Non-existing instance identi- failed [page 160]
tion. row for each failed input fier for instance actions. (Fail
identifier in failed. It lists cause not_found)
the input identifier with the
Unauthorized for action op-
correct fail cause and flags
the %action component
on the correct action. (Dupli-
cates may appear)
For every input identifier cause unauthorized)
not_found, there is one re- applicable if feature control is
readonly).

Learn PUBLIC 177
Unsuccessful factory action. Implementation returns one Non-existing instance identi- failed [page 160]
Failure on input instance. row for each failed input fier. (Fail cause not_found
(Only applicable for instance identifier in failed. It lists for input instance.)
factory actions.) the input identifier with the
Unauthorized for action op-
the %action component on
the correct action.
It also lists the content in an unmanaged BO. (Fail
identifier of the output in- cause unauthorized for
stance in failed with fail input instance.)
cause dependency. The Feature-control disabled

%action component is not field/operation. This is only
flagged for the output in- applicable if feature control
stance, as the action belongs is implemented in modify
to the input instance. handlers in an unmanaged
For every input identifier BO. (Fail cause disabled
listed in failed with or readonly for input in-
fail cause other than stance.)

lated error message returned
in reported.
Unsuccessful factory action. Implementation returns one failed [page 160]

Failure on output. (Applicable row for the failed output in-
for instance and static fac- stance in failed. It lists the
tory actions.) content identifier with the
correct fail cause.
For static factory actions:

Implementation flags the
%action component on the
correct action. (Instance fac-
tory actions do not flag the
%action component on the
output. )
For every content identifier

listed in failed, there is
one related error message
returned in reported.

178 PUBLIC Learn
2.3.3.1.1.9 Implementation Contract: Function
This topic explains the rules for implementing a function operation in a RAP business object.
The function operation is used to return calculated information based on reading entity instances of a RAP BO
on the transactional buffer.
The implementation is done in the ABAP behavior pool in a method FOR READ, see Function Implementation
[page 114].
A BO consumer triggers the function operation with an ABAP EML read request executing a function. The BO
consumer expects that the function is successful or that the instance identifier is returned by the function
operation implementation in the failed response parameter.
For more information, see READ ENTITY, ENTITIES (ABAP - Keyword Documentation) .
Input
The following table defines which components are imported into the function handler method.
Input Components for Functions

Function Type Obligatory Input Components
Instance function
Instance identifier: %tky
Static function
Output
The following table summarizes the provider rules for the function implementation.
Function Implementation Specific Rules

Successful function opera- If the function has a result Existing instance identifiers result [page 164]
tion. parameter, the implementa- on instance functions.
tion fills the response param-
Distinct content identifiers of
eter result. For every out-
static functions.
put parameter instance, it
lists the input identifier and
the calculated function result
in %param.

Learn PUBLIC 179
Unsuccessful function opera- Implementation returns one Non-existing instance identi- failed [page 160]
tion. row for each failed input fier for instance functions.
identifier in failed. It lists (Fail cause not_found.)
the input identifier with the
Unauthorized for function
operation. This is only
the %action component on
applicable if authorization
the correct function. (Dupli-
is implemented in mod-
cates may appear)
ify handlers in an un-
For every input identifier managed BO. (Fail cause
listed in failed with unauthorized.)

Feature-control disabled op-
not_found, there is one re- eration. This is only applica-
lated error message returned ble if feature control is imple-
in reported. mented in modify handlers
cause disabled.)
2.3.3.1.1.10 Implementation Contract: Feature Control
This topic explains the rules for implementing the RAP behavior methods for feature control.
Feature control is used to return permission values for operation, field, action and function control. Depending
on the permission value a RAP consumer is allowed to execute an operation, action or function, or change a
field on the transactional buffer of a RAP BO.
The implementation is done in the ABAP behavior pool in the method FOR FEATURES and method FOR
GLOBAL FEATURES, see FOR INSTANCE FEATURES, FEATURES (ABAP- Keyword Documentation) and FOR
GLOBAL FEATURES (ABAP- Keyword Documentation).
A BO consumer triggers the feature control with an ABAP EML get permissions request. The BO consumer
expects that the feature control implementation returns the requested permission values for existing instance
identifiers. For more information, see GET PERMISSIONS [page 251].
Input
The following list defines which components are imported into the feature control handler method.

180 PUBLIC Learn
Input Components for Feature Control
Feature Control Type Obligatory Input Components
Instance feature control

Requested features
Global feature control Requested features
Output
The following table summarizes the provider rules for the feature control implementation.
Feature Control Implementation Specific Rules

Successful instance feature Implementation returns ex- Existing instance identifiers. result [page 164]
control. actly one row for each ex-
identifiers.
result. It lists the input
identifier and the feature
control permission values.
At least the requested fea-

tures are returned, optionally
more.
Successful global feature Implementation returns the result [page 164]

control. feature control permission
values in result.

more.

Learn PUBLIC 181
Unsuccessful feature control. For instance feature control, Non-existing (duplicate) in- failed [page 160]
the implementation returns stance identifiers. (Fail cause
one row for each failed in- not_found.)
stance identifier in failed.
It lists the source instance
identifiers with the correct
fail cause and initial %op.
(Duplicates may appear.)
The global feature control im-

plementation does not return
failed.
For every input identifier

in reported.
2.3.3.1.1.11 Implementation Contract: Authorization Control
This topic explains the rules for implementing the RAP behavior methods for authorization control.
Authorization control is implemented in RAP BOs to manage authorizations for executing a standard operation,
an action or a function. The authorization can either be based on the status of a BO instance (instance
authorization), or it can be instance-independent (global authorization).
The implementation is done in the ABAP behavior pool in the method FOR INSTANCE AUTHORIZATION and
method FOR GLOBAL AUTHORIZATION, see Authorization Control [page 80].
A BO consumer triggers authorization control with an ABAP EML get permissions request. The BO consumer
expects that the authorization handler methods return the requested permission values for existing instance
identifiers in case of instance authorization, or permission values that are valid globally. For more information,
see GET PERMISSIONS [page 251].
Input
The following list defines which components are imported into the authorization control handler method.

182 PUBLIC Learn
Input Components for Authorization Control
Action Type Obligatory Input Components
Instance authorization control

Requested features
Global authorization control Requested features
Output
The following table summarizes the provider rules for the authorization control implementation.
Authorization Control Implementation Specific Rules

Successful instance authori- Implementation returns ex- Existing instance identifiers. result [page 164]
zation control. actly one row for each ex-
identifiers.
result. It lists the input
identifier and the authoriza-
tion control permission val-
ues.

more.
Successful global authoriza- Implementation returns the result [page 164]

tion control. authorization control permis-
sion values in result.

more.

Learn PUBLIC 183
Unsuccessful authorization For instance authorization Non-existing (duplicate) in- failed [page 160]
control. control, the implementation stance identifiers. (Fail cause
returns one row for each not_found.)
failed instance identifier in
failed. It lists the source
instance identifiers with the
correct fail cause and ini-
tial %op. (Duplicates may ap-
pear.)
For every input identifier

in reported.
The global authorization con-

trol implementation does not
return failed.
2.3.3.2 Strict Mode
The strict mode ensures that a RAP business object is lifycycle-stable and upgrade-save.
About Strict Mode
 Note
It's recommended to use the highest version of strict mode for all RAP BOs.
The strict mode represents the best practices regarding modeling and implementing a RAP business object.
When a BO is defined as strict, this set of best-practice rules is technically enforced with additional syntax
checks on specific design and implementation requirements to make sure that a BO is lifecycle-stable,
upgrade-safe, and best-practice compliant.
Strict mode exists in different versions. It's recommended to always use the hightest version to ensure the
strictest checks are applied to your RAP BO. The highest version always applies all checks of the previous
versions and additional own checks.
When strict mode is defined, some syntax checks that lead to warnings without strict mode then lead to
runtime errors.
The syntax checks in strict mode ensure that:

184 PUBLIC Learn
• the syntax in the behavior definition is up to date.
• all available operations are declared explicitly including draft actions.
• RAP best practices are enforced, like, for example, authorization implementation is mandatory.
Strict mode is currently mandatory and a prerequisite for BOs that are released with a release contract.
For more information strict mode implementation requirements, refer to Strict Mode - Implementation
Requirements [page 185] for an overview.
Definition
You enable the strict mode with the addition strict directly after the implementation type in the behavior
definition. The strict mode is available for the implementation types managedand unmanaged. For more
information about strict, see CDS BDL - strict (ABAP - Keyword Documentation).
2.3.3.2.1 Strict Mode - Implementation Requirements
Defining strict or strict(2) for your base or projection behavior definition results in specific
implementation and modeling requirements that reflect the RAP best practices. If you define strict mode
for an already existing RAP business object, your implementations or modeling may need to be adapted. To
support the transition, the following list provides details about all implementation and modeling requirements
that come along with strictor strict(2) mode:
• Strict Mode: Transactional Behavior Definition [page 186]

• Strict Mode: Abstract Behavior Definition [page 193]
The table columns offer the following information:
• Requirement: Indicates the best practice implementation expected by the strict mode
• Implementation Type: Indicates for which implementation type a corresponding requirement is valid.
• Strict Mode Version: Indicates whether an implementation requirement result from strict or strict(2)
• Affects: Indicates which RAP artifact is affected by errors once strict and additional syntax checks are
active.
• More Information: Links to further information in the documentation (column can be added with Switch/
Hide Column).

Learn PUBLIC 185
Transactional Behavior Definitions
Strict Mode Implementation: Transactional BDEFs
Strict Mode Ver-

Requirement Implementation Type sion Affects More Information
Define strict for • Managed • Strict mode ver- • Projection Behav-

the base behavior def- • Unmanaged sion 1: strict ior Definition
inition, if you want
to define strict in
the projection behavior
definition.
Define strict(2) • Managed • Strict mode • Base Behavior Im- • RAP Extensibility-
for the base and pro- • Unmanaged version 2: plementation Enablement [page
jection behavior defini- strict(2) • Projection Behav- 949]
tion, if you want to ior Implementa-
release the BO for tion
the Extend (C0) or
ABAP for Cloud
Development
(C1) release contract.
With strict(2), • Managed • Strict mode • Base Behavior Im-
%ASSOC is not part of • Unmanaged version 2: plementation
the respective derived strict(2) • Projection Behav-

types, when child no- ior Implementa-
des define tion
authorization:u
pdate.
Define the root entity • Managed • Strict mode ver- • Base Behavior • Concurrency Con-
as lock master and all
child nodes as lock de-
• Unmanaged sion 1: strict Definition Root trol [page 33]
pendent. • Base Behavior

Definition Child
Nodes
Define the root entity • Managed • Strict mode ver- • Base Behavior • Authorization
as authorization
• Unmanaged sion 1: strict Definition Root Control [page 80]
master and all
• Base Behavior
child nodes as
Definition Child
authorization
Nodes
dependent.

186 PUBLIC Learn
Strict Mode Ver-
Define each BO node • Managed • Strict mode ver- • Base Behavior • ETag Definition
either as etag master [page 35]
or etag master/etag
• Unmanaged sion 1: strict Definition Root
dependent unless a • Base Behavior

node is defined as Definition Child
abstract. Nodes
In strict mode, • Managed • Strict mode ver- • Base Behavior Im-

derived types and
• Unmanaged sion 1: strict plementation
ready-results are only
compatible with them-
• Projection Behav-
selves in the imple- ior Implementa-

mentation. tion
 Note
Without strict,
derived types and
ready-results were
implicitly compati-
ble with structur-
ally identical data
types in some im-
plementation sce-
narios. Now, the
compatibility must
be defined explic-
itly in the imple-
mentation with
CORRESPONDIN
G.
Access the derived • Managed • Strict mode ver- • Methods in the • Derived Data
types for the following
operation types only
• Unmanaged sion 1: strict RAP behavior Types [page 150]
pool:
from provider side:
• FOR FEATURES
• Authorizations
•
• Features • FOR INSTANCE
• Determinations AUTHORIZATIO
• Validations N
• Additional save • Determinations
• Validations

Learn PUBLIC 187
Strict Mode Ver-
Build a projection be- • Managed • Strict mode ver- • Projection Behav-

havior definition on a
BDEF with implemen-
• Unmanaged sion 1: strict ior Definition No-
des
tation type managed
or unmanaged.
 Note
Projection BDEFs
can't be based on
abstract base be-
havior definitions.
Create child instances • Managed • Strict mode ver- • Base Behavior • Create by Asso-
only with explicitly
• Unmanaged sion 1: strict Definition Child ciation Operation
stated Creates-By-
Nodes [page 97]
Association. A di-
rect CREATE on a sub-
node isn't allowed in
most cases.
Implement the • Managed • Strict mode ver- • Base Behavior • ADJUST_NUM-

ADJUST_NUMBERS
• Unmanaged sion 1: strict Definition Nodes BERS [page 230]
method in the behavior
pool, if you've defined
late numbering.
Explicitly enable all ex- • Managed • Strict mode ver- • Base Behavior
pected behavior in the
• Unmanaged sion 1: strict Definition Nodes
 Note ior Definition
Strict mode en-

forces explicit def-
inition of all ex-
pected behavior
and any implicit
enablement is
suppressed, like,
for example, im-
plicit read-enable-
ment in toPar-
ent compositions
or implicit enable-
ment of CUD oper-
ations for a man-
aged RAP busi-
ness object.

188 PUBLIC Learn
Strict Mode Ver-
Use only derived types • Managed • Strict mode ver- • Base Behavior Im-
from explicitly enabled
operations in your im-
plementation. • Projection Behav-

ior Implementa-
tion
Use the newest syntax • Managed • Strict mode ver- • Base Behavior For EML:
in your behavior defini-
tion and implementa-
• Unmanaged sion 1: strict Definition and Im- • Examples for Ac-
plementation cessing Business
tion.
• Projection Behav- Objects with EML
 Note ior Definition and [page 240]
Implementation
Strict mode re-
sult in syntax er-
rors if deprecated
syntax is used in
the behavior def-
inition or imple-
mentation.
Only use EML invoca- • Managed • Strict mode ver- • Base Behavior
tions for explicitly en-
abled standard opera-
• Unmanaged sion 1: strict Definition and Im-
plementation
tions.
 Note ior Definition and
Implementation
You can only im-
plement an EML
delete for a RAP
BO, if the DELETE
is enabled in the
corresponding be-
havior definition.
Ensure that feature • Managed • Strict mode ver- • Base Behavior

control isn't used
in combination with
• Unmanaged sion 1: strict Definition
readonly.
ior Definition

Learn PUBLIC 189
Strict Mode Ver-
Explicitly define all • Managed (only if • Strict mode ver- • Base Behavior • Draft Actions
draft actions if your BO
draft-enabled) sion 1: strict Definition [page 53]
is draft-enabled:
• Unmanaged (only
• draft action re- if draft-enabled)
sume;
• draft action Edit;
• draft action Acti-
vate;
• draft action Dis-
card;
• draft determine
action Prepare { }
Explicitly display all • Managed (only if • Strict mode ver- • Projection Behav- • Draft Actions
draft actions in your
draft-enabled) sion 1: strict ior Definition [page 53]
projection BDEF, if the
projection is defined as • Unmanaged (only
strict: if draft-enabled)
• use action Re-

sume;
• use action Edit;
• use action Acti-
vate;
• use action Dis-
card;
• use action Pre-
pare;
Define the draft deter- • Managed (only if • Strict mode ver- • Base Behavior
mine action Prepare draft-enabled) sion 1: strict Definition
without authorization
control.
• Unmanaged (only
if draft-enabled)
Define functions as • Managed • Strict mode ver- • Base Behavior Im-

FOR FUNCTION in
the method definition
of your behavior imple-
mentation. ior Implementa-

tion
 Note
The definition FOR

ACTION for a
function results in
a syntax error.

190 PUBLIC Learn
Strict Mode Ver-
Rename actions in • Managed • Strict mode ver- • Projection Behav-

the BDEF projection
• Unmanaged sion 1: strict ior Definition
with the addition as
*ActionName*, if
another action has the
same identifier.
Use view entities as • Managed • Strict mode ver- • Projection Behav- •

data sources for a RAP
business objects. CDS
• Unmanaged sion 1: strict ior Definition
views aren't supported

in strictmode.
Use late • Managed • Strict mode ver- • Base Behavior

numbering instead • Unmanaged sion 1: strict Definition and Im-
of late numbering plementation
in place.
Don't use the • Unmanaged • Strict mode ver- • Base/Projection
MAPPED parameter
sion 1: strict Behavior Imple-
in your READ/LOCK mentation
implementation and
don't use IMAGE in
your READ implemen-
tation .
Define EML calls of • Managed • Strict mode ver- • Base Behavior Im-
static actions or func-
tions explicitly as in
local mode if nec-
ior Implementa-
essary.
tion
Ensure that toPar- • Managed • Strict mode ver- • Base/Projection

ent/toChild associa-
tions aren't defined as
• Unmanaged sion 1: strict Behavior Defini-
tion
internal and are
explicitly defined in the
Only use CDS abstract • Managed • Strict mode ver- • Base/Projection

entities or classic DDIC
types in your action
• Unmanaged sion 1: strict Behavior Imple-
mentation
or function implemen-
tation.
Ensure that your ac- • Managed • Strict mode ver- • Base/Projection

tion or function imple-
mentation has either
• Unmanaged sion 1: strict Behavior Imple-
mentation
$self, entity, CDS
abstract entities, or a
DDIC type as returning
parameter.

Learn PUBLIC 191
Strict Mode Ver-
Define an • Managed • Strict mode ver- • Base Behavior

implementation
in class
*Implementation
ior Definition
Class* unique for
each BO node where
an implementation is
required.
Ensure that your com- • Managed • Strict mode ver- • Base Behavior
position hierarchy is
modeled consistently
and without any gaps: • Projection Behav-

That means that pa- ior Definition
rent entities must al-
ways be defined in
the behavior definition
if their child entity is
defined. However, you
can define a parent en-
tity without its depend-
ent entities.
Ensure that you define • Managed • Strict mode ver- • Base Behavior
the associations in the
behavior definition if
the respective entity is • Projection Behav-

defined in the behavior ior Definition
definition:
 Example
In a composition
with a travel
entity as root node
and a booking
entity as child en-
tity the following
applies:
If booking is defined
with Define
behavior for
*booking_entity
*, the travel entity
must contain
association
_Booking {...}.

192 PUBLIC Learn
Strict Mode Ver-
If you've defined late • Managed • Strict mode ver- • Base Behavior

numbering for a pa- • Unmanaged sion 1: strict Definition
rent entity, it recom-
mended use late num-
bering also for its child
entit'ses. However, the
%PID isn't inherited
implicitly by child enti-
ties in strict mode.
Abstract Behavior Definition
Strict Mode Implementation: Abstract BDEFs

Requirement Implementation Type Affects More Information
Use abstract CDS entities as • Abstract • (Abstract) Base Behav-

data sources , if you want to ior Definition
define an abstract behavior
definition.
Define an abstract behavior • Abstract • (Abstract) Base Behav-

definition without any trans- ior Definition
actional behavior like:
• Feature Control
• Standard or Non-Stand-
ard Operations
• Locks
• Etag handling
• Foreign Entity
• ...
Only define behavior defini-

tion elements such as asso-
ciations and compositions ,
or mappings for an abstract
BDEF.
Related Information
Strict Mode [page 184]

Learn PUBLIC 193
2.3.3.3 Business Object Modelling
2.3.3.3.1 Business Object Interface
From a technical perspective, a BO interface layer consists of a CDS projection view with the provider contract
transactional_interface and a Behavior Definition Interface with the keyword interface in its
header. A RAP BO interface is a specific BDEF type without a runtime handler and thus without implementation
class and behavior pool, that specifies a subset of elements from a RAP base BO.
The interface layer is built on top of the base BO layer as single point of access to the base BO:
Each RAP base BO can have multiple interfaces ([0,*]) to comply with different consumer requirements and
use cases, for example one BO interface that exposes draft capabilities and another interface with the same
RAP base BO that doesn't expose the draft capabilities and only allows access to active instances.
For more information about the syntax, refer to CDS DDL - CDS Projection View, Transactional Interface (ABAP-
Keyword Documentation) and for more information about the provider contract, refer to CDS DDL - PROVIDER
CONTRACT transactional_interface (ABAP- Keyword Documentation).
What are RAP Business Object Interfaces?
A RAP Business Object Interface is an additional abstraction layer between a RAP base BO and
its business service projection layer. With RAP BO interfaces, you can technically decouple requirements
for stable consumption from the behavior and data model of the underlying RAP base BO. The interface
layer distinctly specifies a subset of elements or behaviors from a RAP base BO like fields or actions in a
consolidated consumption view. This single point of entry ensures lifecycle-stable consumption for RAP BO
consumers : To ensure lifecycle-stability, development objects are released for specific API states, e.g. for Use

194 PUBLIC Learn
System-Internally (C1). Released development objects must abide by specific stability criteria, change,
and development restrictions to guarantee lifecycle stability and upgrade-safety. With an interface layer, you
can avoid unnecessary development restrictions on the RAP base BOs. When the BO interface is consequently
released for Use System-Internally (C1), e.g., for extensions, the restrictions resulting from the API state
only apply to elements specified for consumption in the interface layer. Other elements that are only contained
in the RAP base BO remain unaffected and can be changed without influencing the runtime of applications that
consume the base BO via the RAP BO interface.
Since a RAP BO interface only acts as a consolidated consumption view for a RAP base BO, it doesn't have its
own runtime handler. So, all incoming requests are delegated to the underlying RAP base BO and its respective
behavior pool and implementation.
You can only newly define or redefine static feature control on the interface layer for elements from the RAP
base BO. For example, you can define a fields as readonly in a BO interface when the same field doesn't
have any static feature control in the underlying base BO. Other than static feature control, it's not possible to
introduce new behavior or change existing behavior on interface level.
For an example about how to implement RAP BO interfaces, refer to Develop APIs [page 770].
Releasing RAP BO Interfaces as APIs
To make a RAP BO interface available to consumers in other software components, you can release
the interface using the release contract Use System-Internally (C1) and visibility Use in Cloud
Development.
For more information about the release contract and its stability requirements, see
 Note
For proper usability, it’s recommended to release both the CDS projection view and the BDEF interface.
The layer beneath a released SAP interface can't be accessed or consumed directly, but must always be
accessed via the released interface layer of the RAP base BO.
BO Interfaces and Extensions
The BO interface layer is the basis for data model and behavior extensions. The BO interface is implicitly
extended with every behavior extension that applies the respective BO interface.
Behavior Extensions and BO Interfaces
A BDEF extension is always based on a Business Object Interface (BO Interface) through which the
implementation of the original RAP BO is accessed. A BDEF extension to the original BO technically extends
the base BDEF, but is consumed via the BO interface during the runtime.
For more information about extensions, see Extend [page 939].

Learn PUBLIC 195
Consuming RAP BO interfaces
EML Consumption
RAP BO interfaces can be consumed with EML.
To consume a RAP BO interface with EML, specify the name of the interface in the EML statement instead of
the base/projection layer:
MODIFY ENTITIES OF My_Interface

ENTITY BO_Entity
CREATE …

For more information about EML consumption, see Entity Manipulation Language (EML) [page 235].
Business Service Consumption
You can consume a custom or released RAP BO interface with an OData service. You can create a projection
layer on top of the BO interface and create your own business service for OData or Web API consumption.
For more information about UI Service and Web API consumption, see OData Service Consumption [page
1086].
2.3.3.3.2 Business Service
Definition
The ABAP development platform can act in the roles of a service provider and a service consumer (such as
SAP Fiori UI client).
In the context of the ABAP RESTful application programming model, a business service is a RESTful service
which can be called by a consumer. It is defined by exposing its data model together with the associated
behavior. It consists of a service definition and a service binding.
Business Services in the ABAP RESTful Application Programming Model
As illustrated in the figure below, the programming model distinguishes between the data model and behavior
and the service that is defined by exposing these data models together with the behavior. The data model and
the behavior layer contain domain-specific semantic entities like business objects, list views, and analytical
queries, and, in addition, related functionality such as value help, feature control, and reuse objects.

196 PUBLIC Learn
Business Service
A business object (BO) is a common term used to represent a real-world artifact in enterprise application
development such as the Product, the SalesOrder or the Travel. In general, a business object contains multiple
nodes such as Items and ScheduleLines (data model) and common transactional operations such as creating,
updating and deleting data and additional application-specific operations, such as the Approve action in a
SalesOrder business object. All modifying operations for all related business objects form the transactional
behavior model of an application.
Separation Between the Service Definition and the Service Binding
In a SAP Fiori UI, many role-based and task-oriented apps are based on the same data and related functionality
must be created to support end users in their daily business and in their dedicated roles. This is implemented
by reusable data and behavior models, where the data model and the related behavior is projected in a
service-specific way. The service definition is a projection of the data model and the related behavior to be
exposed, whereas the service binding defines a specific communication protocol, such as OData V2 or OData
V4, and the kind of service to be offered for a consumer. This separation allows the data models and service
definitions to be integrated into various communication protocols without the hassle of re-implementation.
Example
Let us assume that a business object SalesOrder is defined and implemented in the data model and the
behavior layer with the related value help and authorization management. The service definition might expose
the SalesOrder and several additional business objects such as the Product and the BusinessPartner as they
are included in a service binding for an OData V2 service.
The service requires the following artifacts:
• The service definition and the related projection views that project the service relevant parts of the data
model implemented in CDS and the behavior definition where it projects the operations that should

Learn PUBLIC 197
be exposed. For example, the SalesOrder BO might offer the operations: create, update, delete, and 10
different application-specific actions. However, for a concrete role-specific list report, only two actions
are required, so the remaining 8 actions and three standard operations are not included in the service
projection.
• If the service is used to create a user interface, additional UI semantics are required. These are
implemented by CDS UI annotations that are regularly stored in CDS metadata extensions (MDEs).
• The service binding that uses the package of artifacts that is defined in the service definition to bind the
package to a service type (Web API, UI service, INA service) and a protocol type (OData V2, OData V4).
Related Information
Service Definition [page 204]

Service Binding [page 207]
2.3.3.3.2.1 Business Object Projection
The business object projection in the ABAP RESTful Programming Model is an ABAP-native approach to
project and to alias a subset of the business object for a specific business service. The projection enables
flexible service consumption as well as role-based service designs.
Introduction
A service projection layer is required for a flexible service consumption of one business object. The basic
business object is service agnostic. That means, this BO is built independently from any OData service
application. The basic BO comprises the maximum range of features that can be applicable by a service
that exposes this BO. The projection layer is the first layer in the development flow of the ABAP RESTful
Programming Model that is service specific. When projecting the basic BO, you define the real manifestation of
a business object in an OData service. The business object projection entails that part (the subset) of the BO
structure and behavior that is relevant for the respective service, including denormalization of the underlying
data model. Furthermore, the projection layer contains service-specific fine-tuning which does not belong to
the general data model layer, for example UI annotations, value helps, calculations or defaulting.
Why Using Projections?
By using a projection layer for your business object, you gain flexibility in the service consumption. The general
business object can be extended without affecting the already existing business service. This layering with
projections enables robust application programming. The projection layer exposes the service specific subset
of the general business object and thus, the service remains stable under modification of the underlying
business object. In addition, aliasing in the projection views allows context-specific adaptions of the business
object for a service.

198 PUBLIC Learn
The projection layer also enables one business object to be exposed in an OData service for a Fiori UI and
for a stable Web API. The service-specific differences can then be implemented in the respective projection
layers. For example, UI specifications are defined only in the BO projection that is exposed for the UI service.
Furthermore, with projections, you cannot only define the type of the service, but you can also design
role-based services. One business object for general purpose is exposed for more than one context-specific
projection as specialized business object. The most prominent example is the business partner BO, which is
exposed as customer, vendor, or supplier. In the projection, you can use that subset of the business partner BO
that is relevant for the respective specialization.
 Example
The basic BO of a business partner contains a wide range of CDS elements and behavior options.
Depending on the concrete realization of the business partner, that is, depending on which role the
business partner is assigned to, the structure of the data model and the behavior in the BO projection
might vary. In the role of a customer, which is a typical projection of the business partner, the business
partner projection contains the standard data available for business partners and in addition, sales
arrangements. Sales arrangements contain data that is related to specific sales areas and used for the
purposes of sales. All these characteristics must already be available in the basic BO and are then selected
as a subset of the general business partner pool of elements and functionalities.
Imagine the business partner is enriched with characteristics for a new role of a business partner, for
example a supplier. You can add the necessary additional elements, for example delivery information, to
the data model and the behavior implementation in the business partner BO without affecting the already
existing BO projections.
Business Partner Projections

Learn PUBLIC 199
How to Use BO Projections?
The design time artifacts to create an OData service that includes a projection layer are the following:
Involved Development Objects
To create a projection layer for a business object, you need to create two projection artifacts:
• CDS Projection Views

The projection of the data model is done in one or more CDS projection views, depending on the number
of nodes of the underlying BO. The CDS projection views use the syntax element as projection on
<ProjectedEntity> to mark the relationship to the underlying projected entity. As opposed to the
former consumption views, they do not create another SQL view. Since they only provide the consumption
representation of the projected entity, they do not need an ABAP Dictionary representation.
If one BO entity is projected, the root and all parent entities must be projected as well. The root entity has
to stay the root entity and must be defined as root projection view. The compositions are redirected to the
new target projection entity.

200 PUBLIC Learn
Travel BO Projection
For a detailed description on CDS projection views and their syntax, see CDS Projection View [page 201].
• Projection Behavior Definition
The projection of the behavior is done in a behavior definition of type projection, which is declared in the
header of the behavior definition. According to this type, only syntactical elements for projections can be
used.
For more information on projection behavior definitions and their syntax, see Projection Behavior
Definition [page 203].
2.3.3.3.2.1.1 CDS Projection View
Projection views provide means within the specific service to define service-specific projections including
denormalization of the underlying data model. Fine-tuning, which does not belong to the general data model
layer is defined in projection views. For example, UI annotations, value helps, calculations or defaulting.
CDS projection views are defined in data definition development objects. The wizard for data definitions
provides a template for projection views. For a detailed description on how to create projection views, see .
For the CDS view projection, a subset of the CDS elements is projected in the projection view. These elements
can be aliased, whereas the mapping is automatically done. That means, the elements can be renamed to
match the business service context of the respective projection. It is not possible to add new persistent data
elements in the projection views. Only the elements, that are defined in the underlying data model can be
reused in the projection. However, it is possible to add virtual elements to projection views. These elements
must be calculated by ABAP logic.
You can add new read-only associations in the projection view. This can be relevant to display additional
information on the UI, like charts etc. It is not possible, however, to denormalize fields from new associated
entity in the projection view. New associated entities cannot be accessed transactionally. Associations,
including compositions, that are defined in the projected CDS view can be used in the projection CDS view.
However, associations or compositions might change their target, if the target CDS view is also projected. This
is especially relevant for compositions as the complete Data Model is projected and therefore the composition

Learn PUBLIC 201
target changes. In case of a changed target, the association or composition must be redirected to the new
target. The projection view comes with a new syntax element to express the target change.
For more details about the projection view syntax, see Define View Entity as Projection (ABAP Keyword
Documentation).
 Note
In transactional operations, including the transactional READ, the where clause in projection views isn't
respected. Applications must ensure that the instances that are created, updated, or read via the
projection conform to the where clause.
Annotation Propagation to Projection Views
Annotations that are defined in the projected entity on element level are completely propagated to the
projection view. That means, annotation values remain the same in the projection view. Once the same
annotation is used on the same elements in the projection view, the values are overwritten and only the new
values are valid for the respective element.
If you use an annotation with an element reference in the projected entity and the reference element is aliased
in the projection entity, the reference is not drawn to the element in the projection view, due to the name
change. In such a case, you have to redefine the annotation in the projection view and use the alias name of the
element in the annotation value.
 Example
The amount and currency elements are annotated in the underlying CDS view with @Semantics
annotations to support the semantic relationship of the elements.
define root view /DMO/I_Travel

...
{
key travel_id,
...
@Semantics.amount.currencyCode: 'currency_code'
total_price,
@Semantics.currencyCode: true
currency_code,
...}

Both @Semantics annotations are propagated to the projection view. However, the element
currency_code is aliased in the projection view and therefore the reference to the correct element is
not established. Hence, the relationship is broken and the metadata of a possible OData service will not
resemble this semantic relationship.
To avoid this, you have to reannotate the amount element with the reference to the aliased element.
define root view entity /DMO/C_Travel as projection on /DMO/I_Travel

...
{
key travel_id,
...
@Semantics.amount.currencyCode: 'CurrencyCode'
total_price as TotalPrice,
currency_code as CurrencyCode,

202 PUBLIC Learn
...}

Defining UI Specifics in the Projection Views
From a design time point of view, the projection layer is the first service-specific layer. If the resulting OData
service is a UI service, all UI specifications or other service-specific annotations must be defined in the CDS
projection views via CDS annotations. The following UI specifics are relevant on the projection BO layer:
• UI annotations defining position, labels, and facets of UI elements

• Search Enablement
• Text elements (language dependent and independent)
• Value Helps
 Restriction
In the current version of the ABAP RESTful Programming Model, CDS projection views can only be used to
project CDS view entities. Other entities, such as custom entities are not supported.
Related Information
Providing a Data Model for Projections [page 458]
2.3.3.3.2.1.2 Projection Behavior Definition
A projection behavior definition provides means to define service-specific behavior for a BO projection.
The behavior definition with type projection is created equally to other types of behavior definitions. When
creating a behavior definition based on a CDS projection view, the syntax template directly uses the projection
type. For more information, see .
In a behavior definition, only behavior characteristics and operations that are defined in the underlying
behavior definition can be defined for the BO projection. The syntax for this is use <Element>.
For details about the syntax of a projection behavior definition, see CDS BDL - implementation type (ABAP -
Explanation
The keyword use exposes the following characteristics or operations for the service-specific projection. In the
projection, only elements can be used that were defined in the underlying behavior definition. These elements
can be
• ETag
• standard operations

Learn PUBLIC 203
• actions
• functions
• create_by_association
Every operation that you want to expose to your service must be listed in the projection behavior definition.
New aliases can be assigned for actions and functions. Projection behavior definitions do not have a behavior
implementation. The complete behavior is realized by mapping it to the underlying behavior.
The definitions that already restrict the character of the underlying BO are automatically applied in the BO
projection and cannot be overwritten. This is the case for:
• locking
• authorization
• feature Control
If no static field control is defined in the underlying behavior definition, you can add this definition in the
projection behavior definition. If it is already defined in the underlying behavior definition, you cannot define
the opposite in the projection layer. If you do, you will get an error during runtime. New dynamic field control
cannot be defined in the projection behavior definition, as there is no option to implement the feature.
Related Information
Providing Behavior for Projections [page 476]
2.3.3.3.2.2 Service Definition
Definition
A business service definition (short form: service definition) describes which CDS entities of a data model are
to be exposed so that a specific business service, for example, Sales Order handling, can be enabled. It is
an ABAP Repository object that describes the consumer-specific but protocol-agnostic perspective on a data
model. It can directly access the standard ABAP Workbench functionality, such as transports, syntax checks,
element information, and activation. Its transport type is SRVD.
Use
A service definition represents the service model that is generically derived from the underlying CDS-based
data model.

204 PUBLIC Learn
You use a service definition to define which data is to be exposed as a business service using one or more
business service bindings (short form: service bindings). A service definition itself is independent from the
version or type of the protocol that is used for the business service.
 Remember
When going to expose a data model as a service, you can make use of a service definition only in
connection with at least one service binding.
 Note
You cannot expose an OData service that includes abstract entities. Whereas abstract entities are allowed
to be used in a service definition, the publishing of a service via a service binding causes a dump error.
For details about the syntax to define a service, see CDS SDL - DEFINE SERVICE (ABAP- Keyword
Documentation)
Explanation
The source code of the actual service definition is preceded by the optional CDS annotation
@EndUserText.label that is available for all objects which can contain CDS annotations. The annotation
value is a character string with a maximum of 60 characters. The specified text value should consist of a
meaningful short text that describes the service in the original language of the source code. The size of the
set of service-relevant CDS entities depends on the kind of functionality the service should provide to the
application scenario. However, the respective dependencies must be considered:
Depending on the needs of your scenario, further optional annotations @<Annotation_1> ...
@<Annotation_n> can be specified.
The service definition is initiated with the DEFINE SERVICE keyword followed by the name for the service
definition.
 Note
This name for the service definition follows the naming rules that are common to ABAP Repository objects:
• Names are not case-sensitive.

• A name can have a maximum of 30 characters.
• A name can consist of letters, numbers, underscores (_), and slashes (/).
• A name must start with a letter or a slash character (in the case of namespaces).
• The CDS keywords, as well as the CDS entity names cannot be used as names.
• Corresponding with naming conventions, there is no need for a prefix or suffix in the service definition
name. See also: Naming Conventions for Development Objects [page 306]
The source code of a service definition is created within a single bracket { ... } that is used to group all the
related CDS entities (including their associations with the relevant entities) which are to be exposed as part of
an individual service.
The name of each individual CDS entity to be exposed follows the EXPOSE keyword. This is followed by an
optional alias name, which is initiated by the AS keyword. An alias defines an alternative name for a CDS entity
to be exposed. As a result, when accessing the service, the alias names are used instead of the current entity
names. Thus, you have the option of assigning syntactically uniform identifiers in the service definition and
thus decoupling the service semantics from the concrete technical names resulting from the data definition.

Learn PUBLIC 205
Similar to the CDS syntax rules, each statement is completed by a semicolon.
 Restriction
For Web APIs and UI services you cannot use CDS abstract CDS entities in service definitions that are used
by service bindings. Only use CDS view entities or CDS custom entities.
However, abstract entities can be used in a service definition, but only if they are created using OData client
proxy tools (service consumption use case).
Example
/DMO/Travel, defines associations to the entities /DMO/Customer and /DMO/Agency. In addition,
associations to the entities I_Currency and I_Country must be included.
Data model for the TRAVEL service
The following example shows the corresponding source code for the service definition /DMO/TRAVEL. The
travel management service to be defined in this way includes all dependencies that come from the root
entity /DMO/I_TRAVEL.

@EndUserText.label: 'Service for managing travels'
define service /DMO/TRAVEL
{
expose /DMO/I_TRAVEL as Travel;
expose /DMO/I_AGENCY as TravelAgency;
expose /DMO/I_CUSTOMER as Passenger;
expose I_Currency as Currency;
expose I_Country as Country;
}

 Note
In this example, the service definition is based on CDS entities that originate from different namespaces.

206 PUBLIC Learn
Related Information
Service Binding [page 207]
2.3.3.3.2.2.1 Service Definition Extension
A RAP Service Definition Extension extends an existing service definition to include extension nodes in
the service binding.
A Service Definition Extension contains extension nodes you want to expose in your service binding. If
you add a new extension BO node to a RAP BO, you must extend an existing Service Definition to expose
the new BO entity to the consumer in the service binding. For more information about creating an extension
node, see Node Extensions [page 985].
2.3.3.3.2.3 Service Binding
Definition
The business service binding (short form: service binding) is an ABAP Repository object used to bind a service
definition to a client-server communication protocol such as OData. Like any other repository object, the
service binding uses the proven infrastructure of the ABAP Workbench, including the transport functionality.
Use
As shown in the figure below, a service binding relies directly on a service definition that is derived from the
underlying CDS-based data model. Based on an individual service definition, a plurality of service bindings can
be created. The separation between the service definition and the service binding enables a service to integrate
a variety of service protocols without any kind of re-implementation. The services implemented in this way are
based on a separation of the service protocol from the actual business logic.
Relationship Between the Data Model, the Service Definition and the Service Binding
Parameters
The following parameters are used to characterize a service binding:

Learn PUBLIC 207
Service Name
Defines a unique system-wide name for the service and is identical to the name of the service binding.
 Tip
We recommend using the prefix API_ for Web API services and the prefix UI_ for UI services.
Binding Type
The binding type specifies the service type and the specific protocol which is implemented with the service
binding.
The CDS data models can be exposed with the following protocols:
• OData version 2.0 (ODATA V2)

For more information, see https://www.odata.org/documentation/odata-version-2-0/ .
For more information about Fiori Elements apps based on OData V2 Models, see OData V2 Model.
 Note
In OData V2 services, unit and currency types are automatically added to the service metadata as
built-in entity sets. With this feature, unit and currency values are always displayed correctly and
validated regarding decimals on a UI.
• OData version 4.0 (ODATA V4)

For more information, see https://www.odata.org/documentation/ .
OData V4 services have a wider scope than OData V2 services. Use OData V4 wherever possible for
transactional services.
 Note
Full support for Fiori Elements UIs based on OData V4 services is only granted for draft-enabled
scenarios.
For more information about Fiori Elements app based on OData V4 Models, OData V4 Model.
• InA (Information Access)
Analytical data models are exposed with InA for live data access.
• SQL
Access published ABAP-managed database API objects with open SQL.
 Remember
The Open Data Protocol (OData) enables the creation of HTTP-based services, which allow resources
identified using Uniform Resource Identifiers (URIs) and defined in an abstract data model to be published
and edited by Web clients using HTTP messages. OData is used to expose and access information from
a variety of sources including, but not limited to, relational databases, file systems, content management
systems, and traditional Web sites.
This parameter also determines the way a service is offered to a consumer. There are two options:

208 PUBLIC Learn
UI UI service
A UI service makes it possible to add a SAP Fiori elements UI or other UI clients to the service.
Currently, UI services are supported for OData and InA services.
Web API Service exposed as Web API
A service that is exposed as Web API is used for all other use cases apart from UIs. Web APIs can
be consumed by an unknown consumer via OData. Web APIs can be extended.
Currently, Web APIs are supported for OData and SQL services.
Service Version
The versioning of services is made by a version number which is assigned to a service binding.
The next higher version is created by adding another service definition to the existing service binding. By
means of this further service definition, functional changes or extensions (compared to the previous version)
are exposed. And, vice versa, the version number can be decreased by removing a service definition from the
service binding.
Publishing
The local service endpoint of an OData service must be published via the Publish button in the service binding
editor. This triggers several task lists to enable the service for consumption. By publishing the service binding
the service is only enabled for the current system. It is not consumable from other systems.
 Note
The service binding needs to be active to be published. To activate the service binding use the activation
button in the tool bar.
Service URL
The derived URL (as a part of the service URL) is used to access the OData service starting from the current
ABAP system. It specifies the virtual directory of the service by following the syntax: /sap/opu/odata/
<service_binding_name>
For more information about the service binding, see .
Preview
You can start a Fiori Elements Preview directly from the service binding. With this, you can test UI-related
features directly from your ABAP system.
 Home Service Transport
In an on-premise system, you can only use the service binding to enable your service locally and test it in the
development system. Transporting the service binding with all the related artifacts that are generated locally is
not possible. To enable your business service in a qualification or productive system, you have to disable the
service in your local system (Unpublish button). Then use Gateway tools to activate and maintain your service.

Learn PUBLIC 209
For more information, see Activate the Service (SAP Gateway Foundation) for OData V2 scenarios or Service
Development in Hub System (V4) for OData V4 scenarios.
Service Errors
The service binding shows errors that are related to the complete service. They are shown on creating the
service binding or when reopening the artifact in ADT. The errors that are shown in the service binding are also
appear in ATC checks.
Related Information
Service Definition [page 204]
2.3.3.3.3 RAP Reuse Data Elements
You can use specific data elements in all RAP application for typing administrative fields.
The following list of reuse data elements can be used for the administrative fields in RAP BOs of all
implementation types. These data elements are available for reuse in all systems.
Data Element Definition
ABP_CREATION_USER Identifier of the user who created the data.
ABP_CREATION_DATE Date on which the data was created.
ABP_CREATION_TIME Time at which the data was created.
ABP_CREATION_TSTMPL Timestamp at which the data was created.
ABP_CREATION_UTCL Timestamp at which the data was created.
ABP_LASTCHANGE_USER Identifier of the user who changed the local instance itself or
its compositional subtree last time.
ABP_LASTCHANGE_DATE Date on which the data of the local instance or its composi-
tional subtree was last changed.
ABP_LASTCHANGE_TIME Time at which the data of the local instance or its composi-
tional subtree was last changed.
ABP_LASTCHANGE_TSTMPL Timestamp at which the data of the local instance or its

compositional subtree was last changed.
ABP_LASTCHANGE_UTCL Timestamp at which the data of the local instance or its

compositional subtree was last changed.
ABP_LOCINST_LASTCHANGE_USER Identifier of the user who changed the local instance itself
(without considering its compositional subtree) last time.

210 PUBLIC Learn
Data Element Definition
ABP_LOCINST_LASTCHANGE_DATE Date on which the data of the local instance itself (without
considering its compositional subtree) was last changed.
ABP_LOCINST_LASTCHANGE_TIME Time at which the data of the local instance itself (without
considering its compositional subtree) was last changed.
ABP_LOCINST_LASTCHANGE_TSTMPL Timestamp at which the data of the local instance itself

(without considering its compositional subtree) was last
changed.
ABP_LOCINST_LASTCHANGE_UTCL Timestamp at which the data of the local instance itself

(without considering its compositional subtree) was last
changed.
Administrative data fields are relevant in RAP application to log data access and modification. This is especially
important when working with an OData ETag for optimistic concurrency control, or for the total ETag in draft
applications.
For more information about the OData ETag, see Optimistic Concurrency Control [page 33].
For more information about the total ETag, see Total ETag [page 51].
Managed Business Objects
In managed business objects, the relevant administrative fields are updated automatically by the managed
BO provider if the fields are annotated with the corresponding annotation in CDS. See Semantics Annotations
[page 1247].
Unmanaged Business Objects
In unmanaged business object, updating the administrative fields on data modification must be implemented
by the unmanaged BO provider in all relevant RAP handler methods.
 Example
When creating a new instance, the RAP handler method for create must ensure that the fields for the
creation user and the creation time are filled correctly.

Learn PUBLIC 211
2.3.3.3.4 Using Groups in Large Development Projects
This section introduces the concept of groups that can be used to divide operations, actions and other
implementation-relevant parts of the business logic into several groups for behavior implementation.
Use Case
Generally, the implementation of business object entity's operations and actions is done in the Local Types
include of the behavior pool (ABAP class that implements business object’s behavior) associated with that
entity – unless the control of the implementation classes using the IMPLEMENTATION IN CLASS syntax (at
entity level) has been completely dispensed.
Since the Local Types include can only be changed by one developer at a time, the efficiency of development
would be significantly reduced in case of larger implementations. Let us think about large business objects with
extensive business logic implementations, with many entities, each of which may contain a variety of elements.
As a solution, the operations and actions of an entity can be divided into several groups, whereby each of these
groups can then be assigned a different behavior pool as implementation class.
Especially in large development projects, the responsibilities for the implementation of application logic are
assigned to different members of a development team. To support this approach technically, we introduce the
concept of groups. This approach enables that a team of developers can implement parts of business logic
independently from each other. In addition, the group concept allows to tailor the functionality of business
objects according to semantic considerations.
Relationship Between Entities, Groups and Implementing Classes
For details about the syntax for defining groups for unmanaged business objects, see CDS BDL -
implementation grouping (ABAP- Keyword Documentation)
Syntax: Defining Groups for Managed Business Objects
Groups can be defined within a behavior definition for a business object of type managed by using the following
syntax:

[implementation] managed [implementation in class ABAP_ClASS [unique]];


persistent table DB_TABLE
...
{

[create;]

[update;]

[delete;]

[read;]

[association AssociationName [abbreviation AbbreviationName] {[create;] } ]

212 PUBLIC Learn

group groupName_1 implementation in class ABAP_CLASS_1 unique
{
// Implementation-relevant content of the entity
}
{
}
// It is possible to assign the same behavior pool as the implementation class
in different groups
{
}
group ...
}

Explanatory Notes
(1) The group name is defined locally within the entity’s behavior definition and must not conflict with actions,
determinations, or validations of the same name.
(2) The implementation in class syntax can only be used on groups, but no longer on individual entity’s
behavior definition itself. A group requires a behavior pool ABAP_CLASS_* and the addition of unique.
 Note
With the addition implementation in class ABAP_ClASS in the header of the behavior definition, you
have the option to implement the remaining functionality for all entities in a common behavior pool. For
example, the save sequence for all entities of a business object could be implemented in a single behavior
pool ABAP_CLASS.
It is possible to specify the same behavior pool as the implementation class in different groups. In the syntax
above, the implementation-relevant content of groupName_1 and of groupName_3 must be implemented in
ABAP_CLASS_1.
(3) The implementation-relevant content of an entity can be:
• Actions
• Instance-based feature control
• Determinations - for managed implementation type only
• Validations - for managed implementation type only.
 Note
In the case of unmanaged implementation type, the standard operations (CREATE, UPDATE, DELETE)
as well as READ and CREATE by association must be assigned to a group. In the managed case however, the
standard operations (that are implemented by the framework) and READ and CREATE for associations can
be specified either inside or outside groups.
(4) Information on mapping (which is never relevant to implementation) must always be specified outside of
groups.

Learn PUBLIC 213
(5) Implicit standard operations (defined automatically and don't have to be explicitly specified) must be
explicitly specified within one and the same group in the unmanaged case (where they are implementation-
relevant):
• read; - for READ operations of an entity

• lock; - for LOCK operations of an entity that is defined as lock master.
Examples
Listing: Groups in the behavior definition of an unmanaged business object

implementation unmanaged implementation in class /DMO/BP_TRAVEL_U;
// behavior definition for the TRAVEL root entity
define behavior for /DMO/I_Travel_U alias travel
etag LastChangedAt
lock master
{
group travel_cud implementation in class /dmo/bp_travel_cud unique
{
field ( read only ) TravelID;
field ( mandatory ) AgencyID, CustomerID, BeginDate, EndDate;
field(features:instance) overall_status;
create;
update(features:instance);
delete;
read; // read and lock must be assigned explcitly to a group
lock;
}
group travel_cba implementation in class /dmo/bp_travel_cba unique
{
association _Booking { create; }
}
group travel_main_actions implementation in class /dmo/bp_travel_main_a unique
{
action(features : instance) set_status_booked result [1] $self;
action getTravel result [1] $self;
action copyTravel result [1] $self;
}
group travel_aux_actions implementation in class /dmo/bp_travel_aux_a unique
{
action(features:instance) getMaxDate result [1] $self;
action(features:instance) getminDate result [1] $self;
}
mapping for /dmo/travel
{
...
}
}
// behavior defintion for the BOOKING child entity
define behavior for /DMO/I_Booking_U alias booking
lock dependent ( travel_id = travel_id )
{
group booking_rud implementation in class /dmo/bp_booking_rud unique

{
read;
update;
delete;
}
group booking_fc implementation in class /dmo/bp_booking_fc unique
{
field ( read only ) TravelID, BookingID;
field ( mandatory ) CustomerID, AirlineID, ConnectionID, FlightDate;
action(features:instance) confirmBooking result [1] $self;

214 PUBLIC Learn
}
mapping for /dmo/booking
{
...
}
}

Listing: Groups in the behavior definition of a managed business object

implementation unmanaged implementation in class /DMO/BP_TRAVEL_M;
// behavior definition for the TRAVEL root entity
define behavior for /DMO/I_Travel_M alias travel
persistent table /dmo/travel_m
with additional save
lock master
authorization master ( instance )
etag LastChangedAt
{
create;
delete;
group travel_fc implementation in class /dmo/bp_travel_fc unique
{
field ( read only ) TravelID;
field(features:instance) overall_status;
}
group travel_cba implementation in class /dmo/bp_travel_cba unique
{
}
group travel_actions implementation in class /dmo/bp_travel_a unique
{
action(features : instance) set_status_booked result [1] $self;
action getTravel result [1] $self;
action ( authorization : none ) copyTravel result [1] $self;
action(features:instance) getMaxDate result [1] $self;
action(features:instance) getminDate result [1] $self;
}
group booking_det_val implementation in class /dmo/bp_booking_det_val unique
{
determination determineDiscount on modify { create; }
validation validateAgency on save { field Agency_ID; }
validation validateCustomer on save { field Customer_ID; }
validation validateDates on save { field Begin_Date, End_Date; }
validation validateStatus on save { field overall_Status; }
}
mapping for /dmo/travel

{
...
}
}
// behavior definition for the BOOKING child entity
define behavior for /DMO/I_Booking_M alias booking
{
read;
update;
delete;
mapping for /dmo/booking
{
...
}
group booking_fc implementation in class /dmo/bp_booking_fc unique
{
field ( read only ) TravelID, BookingID;

Learn PUBLIC 215
action(features:instance) confirmBooking result [1] $self;
}
group booking_det_val implementation in class /dmo/bp_booking_det_val unique
{
determination totalBookingPrice on modify { field Flight_Price; }
determination determineCustomerStatus on modify { create; }
// internal action: triggered by determination
internal action SetCustomerStatus;
}
}

Implementation-Related Aspects
(1) The name of the group and which operations are associated with this group do not matter to external
users (and can therefore be changed retrospectively by the developer). This means that external operations
and actions are still accessed by the usual syntax, in which only the name of the entity, the operation, and, if
applicable, the action/determination/validation or association plays a role, but not the name of the group.
However, there are exceptions: the name of the group is relevant for the implementation of instance-based
feature control - the corresponding implementations then control only those features that are associated
with their respective group. (The framework merges the information for the external consumers.) The
corresponding syntax entity-group can only be used within the implementation class associated with that
group. Specifically, the following declarations are concerned:
Syntax for methods ... for features

methods method_name for features key_param

request request_param for entity~group_name

result result_parameter.

Syntax for types/data ... for features

type|data ... type table|structure for features key|request|result
entity~group_name.

 Note
This declaration can also be done in the public section of the implementation class to make the
group-dependent type public outside. Because it makes the changes to group assignment incompatible
with external users, such publishing is not recommended.
Example: Declaration of local handler for feature control implementation
Within the implementation class, the syntax methods ... for features for instance-based feature control
can only be defined by specifying the group name:

class lhc_travel_fc definition inheriting from cl_abap_behavior_handler.
private section.
methods get_features for features


216 PUBLIC Learn
importing keys request requested_features for travel~group_name result
result.

endclass.

(2) Because associations with the usual association syntax can only be assigned as a whole to a group, it is
not possible to implement the association's CREATE operation in an implementation class other than the READ
operation.
Example: Local behavior implementation of create by association

class lhc_travel_cba definition inheriting from cl_abap_behavior_handler.
private section.
methods create_bookings for modify
importing entities for create travel\_Booking.
methods read_bookings for read
importing keys for read travel\_Booking full result_requested
result result link association_links.
endclass.
class lhc_travel_cba implementation.
method create_bookings.
...
endmethod.
method read_bookings.
...
endmethod.
endclass.

2.3.3.3.5 Using Client-Independent Database Tables
The RAP managed BO runtime supports transactional scenarios with client-independent database tables in
scenarios with and without draft capabilities. This topic provides information about things you need to consider
when using client-independent tables.
Creating Client-Independent Database Tables
The procedure for creating client-independent database tables is the same as described in Procedure: Creating
Tables [page 383]. You can simply remove the client field in the template for database tables.
The following code block shows the travel database table without a client field. The following example depicts
a table for an active instance, but the respective draft table has an identical structure and can only be
differentiated by the table name.
@EndUserText.label : 'Flight Reference Scenario: Managing Travels'

@AbapCatalog.enhancementCategory : #NOT_EXTENSIBLE
@AbapCatalog.tableCategory : #TRANSPARENT
@AbapCatalog.deliveryClass : #A
@AbapCatalog.dataMaintenance : #RESTRICTED
define table /dmo/travel_m {
agency_id : /dmo/agency_id;
customer_id : /dmo/customer_id;

Learn PUBLIC 217
begin_date : /dmo/begin_date;
end_date : /dmo/end_date;
@Semantics.amount.currencyCode : '/dmo/travel_data.currency_code'
booking_fee : /dmo/booking_fee;
@Semantics.amount.currencyCode : '/dmo/travel_data.currency_code'
total_price : /dmo/total_price;
currency_code : /dmo/currency_code;
description : /dmo/description;
overall_status : /dmo/overall_status;
@AbapCatalog.anonymizedWhenDelivered : true
created_by : syuname;
created_at : timestampl;
last_changed_by : syuname;
last_changed_at : timestampl;

}
Modeling Business Objects with Client-Independent Tables
A business object must be consistent with regard to the client fields in the database tables for the active
and the draft instance. This means that CDS views that are used for the data model in scenarios with client-
independent tables must not contain a client element and the same applies to draft tables: If a managed
business object has client-independent data sources, the automatically created draft tables are created client-
independently. For more information about how to generate draft database tables, refer to Draft Database
Table [page 50].
In addition, the created SQL-view of a CDS V1 view must not contain such a client element. When using CDS
V2, the client handling of the CDS view is implicitly defined by the underlying data source.
There must be client-consistency among the entities in the business object composition structure. You can't
to have one entity that is client-dependent and another one that is client-independent with a compositional
relationship between them.
Business Object Runtime with Client-Independent Tables
The client field in database tables influences the runtime of business objects during lock. While locks are set on
entity instances only for one specific client in client-dependent tables, locks in client-independent tables lock
instances for all clients.
 Note
In scenarios in which you have client-dependent database tables, but join client-independent fields from
other database tables to your CDS view, the managed BO runtime locks the instances specific to the client.
This means only the fields from the client-dependent database tables are locked. If you also want to lock
the client-independent fields, you have to implement an unmanaged lock.
 Note
In scenarios, in which you use an unmanaged save in the managed scenarios, the managed BO runtime
always sets a client-specific lock. If you want to lock client-independently, you have to use an unmanaged
lock.

218 PUBLIC Learn
Related Information
Lock Definition [page 42]

Integrating Unmanaged Save in Managed Business Objects [page 447]
2.3.4 RAP BO Runtime
Here you can find detailed information about the RAP BO runtime like the interaction phase and the save
sequence.
The RAP Transactional Model for the SAP LUW [page 219]
This topic describes how RAP supports the transactional model of a SAP LUW. The logical unit of
work (LUW) is the sum of all operations and work processes that are used to transfer data from one
consistent state to another.
Save Sequence Runtime [page 225]

The save sequence is part of the business object runtime and is called after at least one successful
modification was performed during the interaction phase.
2.3.4.1 The RAP Transactional Model for the SAP LUW
This topic describes how RAP supports the transactional model of a SAP LUW. The logical unit of work (LUW)
is the sum of all operations and work processes that are used to transfer data from one consistent state to
another.
The transactional handling in RAP ensures transactional consistence during one LUW for RAP applications. To
make sure that an application and all involved parties (for example other business objects) work consistently
and aligned with all LUW prerequisites, the transactional modeling of highly complex scenarios can become
cumbersome and unforeseeable. When developing with RAP, you achieve a consistent transactional modeling
that includes all involved parties. This is ensures by adhering to the framework RAP provides, which entails
checks for all different use cases. Adhering to the rules of RAP ensures that your application is consistent and
stable, also when more than one BO is involved.
RAP divides the LUW into the interaction phase and the save sequence. Data can be changed and created
in an inconsistent state on the transactional buffer during the interaction phase. The save sequence ensures
that the new state of data is consistent and ready to be written to the database. The final database commit is
then also executed during the save sequence. An LUW is terminated when the database commit is executed
successfully and the transactional buffer is cleared, or, if the database commit is unsuccessful. In the latter
case, all work processes of the current LUW must be completely rolled back. That means, the LUW must not
leave any remains, neither on any database, nor on the transactional buffer. This is also true for BO-external
procedures. The RAP framework offers options to trigger this clean-up work. See The Save Sequence [page
221].
The RAP transactional model is seamlessly embedded in a SAP LUW. The statements to terminate a SAP
LUW COMMIT WORK and ROLLBACK WORK trigger COMMIT ENTITIES and COMMIT WORK and thus terminate
the LUW with RAP procedures. For more information about the SAP LUW, see SAP LUW (ABAP- Keyword
Documentation).

Learn PUBLIC 219
 Note
COMMIT WORK and ROLLBACK WORK are forbidden statements in RAP handler methods. For more
information, see General RAP BO Implementation Contract [page 157].
Every BO entity instance that is involved in one LUW must be locked to avoid conflicting access. Locking is
tightly coupled to the lifetime of the LUW. A lock for a BO entity instance lasts as long as the LUW. With every
database commit or with a rollback, the lock is released and the same BO instance can be used in a new LUW.
For more information about the locking concept in RAP, see Pessimistic Concurrency Control (Locking) [page
38].
The Interaction Phase
Working with data of a RAP business object implies manipulating data on the database: You can create
new data, or you can modify existing data. Both approaches require an additional memory area to store
the data that is currently being worked on. This area is called transactional buffer. In managed BOs, the
transactional buffer is fully handled by the managed BO provider. For unmanaged BOs, the transactional buffer
is implemented by the application developer within the unmanaged BO provider. Newly created data, that is,
new BO instances are created in the transactional buffer and are further processed from there. Existing data
is retrieved from the database and loaded into the transactional buffer for further processing, for example
changing values of the BO instance. During this time, the data on the database remains in a consistent state.
In other words, while the BO instance is consistent on the database table, the state of the BO instance on the
transactional buffer can become inconsistent.
The following diagram shows how data is retrieved from the database table and modified on the transactional
buffer.

220 PUBLIC Learn
Data modification on the transactional buffer is done via RAP operations during the interaction phase, see
Operations [page 88] and Determinations [page 119]. During this phase the data does not have to be in a
consistent state.
 Caution
There is no consistency check during the interaction phase. That means, the data that is being worked on is
always potentially inconsistent. Hence, it is not allowed to trigger any procedure that directly changes data
on the database during that phase. This would be based on a potentially inconsistent data state and there
is no mechanism that checks the data before saving.
If any work process during the interaction phase fails, the consumer is notified and is able to restart the
request.
The Persisted Transactional Buffer in Draft Scenarios

Due to the stateless approach of draft scenarios, the logical LUW can be split into more than one ABAP session
in such scenarios. Technically, one logical LUW is then divided into several technical LUWs. The state of the
transactional buffer must be stored intermediately and there must be durable locks that survive a termination
of the ABAP session. When working with draft-enabled business objects, every change on the transactional
buffer, which is the set of changed within one technical LUW, is persisted to the draft database table. This
ensures that draft data don't get lost. Like this, inconsistent data can reach the draft database table. The
content of this database table, however, is not process-relevant.Writing the latest transactional buffer to the
draft persistence is part of the interaction phase and therefore the save sequence is not relevant for the
draft persistence. For more information, about the interaction between the transactional buffer and the draft
database table, see Draft Runtime [page 56].
The following diagram shows the persistence of the transactional buffer on the draft table.
The Save Sequence
The data changes during the interaction phase are saved to the persistent database table during the save
sequence. It is invoked with the EML request COMMIT ENTITIES, which can be invoked by an EML consumer

Learn PUBLIC 221
or by the RAP transactional engine, for example when processing OData changesets. For more detailed
information about the save sequence and its phases, see Save Sequence Runtime [page 225].
The save sequence ensures that the BO instances of all involved BOs on the transactional buffer are in a
consistent state and ready to be saved to the database. If this is not the case, the early phases (FINALIZE or
CHECK_BEFORE_SAVE) of the save sequence fail and the COMMIT ENTITIES request returns sy-subrc=4. In
this case, the saver method CLEANUP_FINALIZE for all touched BOs is called, which ensures the clearing of
the transactional buffer for all BOs that are involved in the current LUW. Then, the save sequence is terminated
without any database commit and the BO instance can be further modified to reach a consistent state.
If the early save phases are successful, the actual saving to the database is triggered and must be executed
successfully. The responsible saver methods are ADJUST_NUMBERS and SAVE. The former draws final numbers
in late numbering scenarios. The latter method finally saves the data and executes the database commit.
Numbers of other referenced objects can be fetched via CONVERT_KEY. This terminates the SAP LUW. The
COMMIT ENTITIES request returns sy-subrc=0. External work processes that rely on a successful database
commit can be triggered.
RAP BOs can also fail during the late save phase (SAVE). A COMMIT ENTITIES request returns sy-subrc=8.
In this case the current LUW is inconsistent and all changes must be rolled back to the last consistent state.
Hence, it is not allowed to trigger any procedure that cannot be withdrawn by ROLLBACK ENTITIES at any
point in time during the LUW, but especially not during the late save phase. If such a fail happens, the ABAP
session can be rescued with an explicit subsequent ROLLBACK ENTITIES for EML, and subsequent OData
change sets will be processed regularly.
Information Flow in RAP during a SAP LUW
Sometimes it is necessary to pass information related to a BO instance from the interaction phase to the save
sequence, without the information being relevant for the data model. Such an information can be relevant to
evaluate if external or asynchronous processes must be triggered during the late save phases.
 Example
It might be necessary to inform an external RAP BO consumer about a change on the database. This
notification process can only be triggered on saving the data to the database, because any step before
can fail in the LUW and the consumer might be informed about changes that effectively did not happen.
Therefore such processes or notifications can only be triggered during the actual save step or the
additional save in the save sequence.
To evaluate if such a process must be triggered during the save phase in the save sequence, an auxiliary field
can be added to the transactional data model in CDS. This field does not need to have a persistence on the
database, but is only added in CDS as a virtual field (technically done by a cast). This auxiliary field can be filled
during the interaction phase with information that is relevant during the save phase in the save sequence and
evaluated when the actual save happens.
 Caution
It must always be ensured that a procedure that is triggered during the late save phases can be rolled back
entirely without any leftovers in the current SAP LUW.

222 PUBLIC Learn
RAP Activities during a SAP LUW
The following diagram shows the activities during an LUW in RAP.

Learn PUBLIC 223
RAP Activities during a SAP LUW

224 PUBLIC Learn
2.3.4.2 Save Sequence Runtime
The save sequence is part of the business object runtime and is called after at least one successful
modification was performed during the interaction phase.
The save sequence starts with FINALIZE, in which final calculations involving all BOs in the current
LUW are executed before data can be persisted. These changes are done by determinations for managed
implementation scenarios, or in the corresponding implementation method for unmanaged implementation
scenarios. The FINALIZE step is the last option to change data on the transactional buffer. After the FINALIZE
step, EML modify requests result in runtime errors. For more information, see FINALIZE [page 228].
 Note
The SAVE sequence is always triggered, when a MODIFY request on a BO is executed, even when the BO
buffer is not changed and solely delegates the request, for instance to another BO.
If the subsequent CHECK_BEFORE_SAVE step is positive for all transactionally involved business objects, the
point-of-no-return is reached. From now on, a successful SAVE must be guaranteed for all involved BOs. The
checks are performed via validations in managed implementation scenarios, or in the corresponding method
for unmanaged implementation scenarios. For more information, see CHECK_BEFORE_SAVE [page 229].
After the point-of-no-return, the ADJUST_NUMBERS call can occur to take care of late numbering. For more
information, see ADJUST_NUMBERS [page 230].
The SAVE step persists all BO instance data from the transactional buffer for all involved business objects in the
database. For more information, see SAVE [page 231].
The CLEANUP step clears the transactional buffer. For more information, see CLEANUP [page 233].
You can use the CLEANUP_FINALIZE method to clear the transactional buffer if the FINALIZE or the
CHECK_BEFORE_SAVE fails in any BO that is involved in the current LUW. For more information, see
CLEANUP_FINALIZE [page 234].
The following runtime diagram illustrates the main agents' activities during the save sequence.

Learn PUBLIC 225


226 PUBLIC Learn
• Validations [page 123]
• Validations [page 123]
• SAVE [page 231]
• SAVE [page 231]
• SAVE [page 231]
• SAVE [page 231]
• The RAP Transactional Model for the SAP LUW [page 219]
• COMMIT ENTITIES [page 255]
• SAVE [page 231]
• Implementing Additional Save [page 441]
A detailed description of the activities during the interaction is illustrated in separate diagrams, see

Related Information
FINALIZE [page 228]

CHECK_BEFORE_SAVE [page 229]
ADJUST_NUMBERS [page 230]
SAVE [page 231]
CLEANUP [page 233]
CLEANUP_FINALIZE [page 234]
Determinations [page 119]

Learn PUBLIC 227
Validations [page 123]
2.3.4.2.1 FINALIZE
Finalizes data changes before they can be persisted on the database.
The FINALIZE implementation is called as a first step in the save sequence. This step executes final
calculations based on the results of the interaction phase for all involved BOs in the current LUW. FINALIZE is
the last chance to change BO instances on the transactional buffer via EML modify calls. After this step, EML
modify requests result in runtime errors.
Managed BOs
In managed BOs, final modifications are done via determinations, see Determinations [page 119].
Unmanaged BOs
In unmanaged BOs, final calculations are done in the corresponding method in the behavior pool.
Method FINALIZE
The method FINALIZE must be redefined in the local saver class to implement it.
CLASS lcl_saver DEFINITION INHERITING FROM cl_abap_behavior_saver.

PROTECTED SECTION.
METHODS finalize REDEFINITION.
ENDCLASS.
CLASS lcl_save IMPLEMENTATION.
METHOD finalize.
// ** implement finalize **//

ENDMETHOD.
Changing Parameters
• FAILED
The parameter FAILED is filled to log the entities for which FINALIZE went wrong.
• REPORTED
You can fill the parameter REPORTED to return messages in case of failure.
Related Information

228 PUBLIC Learn
2.3.4.2.2 CHECK_BEFORE_SAVE
Checks the transactional buffer for consistency.
The CHECK_BEFORE_SAVE implementation is called during the save sequence before the point-of-no-return.
This step checks the consistency of the transactional buffer to ensure a successful save.
If the check for all involved BOs returns positive feedback based on all transactional changes, the point-of-no-
return is reached. From now on, a successful SAVE must be guaranteed for all involved BOs and the data is
persisted.
If on the other hand, errors are reported in the changing parameter FAILED, the save sequence is aborted.
Managed BOs
In managed BOs, the final check for all involved BOs is done via validations, see Validations [page 123].
Unmanaged BOs
In unmanaged BOs, the final check for all involved BOs is done in the corresponding method in the behavior
pool.
Method CHECK_BEFORE_SAVE
The method CHECK_BEFORE_SAVE must be redefined in the local saver class to implement it.

PROTECTED SECTION.
METHODS check_before_save REDEFINITION.
ENDCLASS.
METHOD check_before_save.
// ** implement check_before_save here **//

ENDMETHOD.
Changing Parameters
• FAILED
The parameter FAILED is filled to log the entities for which there is no positive feedback.
• REPORTED
You can fill the parameter REPORTED to return messages in case of failure.
Related Information

Learn PUBLIC 229
2.3.4.2.3 ADJUST_NUMBERS
Implements late numbering.
The ADJUST_NUMBERS implementation is called during the save sequence after the point-of-no-return. At this
point in time, the transactional buffer is in a consistent state and all instances can receive their final number.
The implementation of ADJUST_NUMBERS is only possible if late numbering is modeled in the behavior
definition. For more information, see Late Numbering [page 28]. The method must be implemented by the
application developer in late numbering scenarios. Usually the final key value is assigned by number range
objects and the adjusted number is then mapped in the mapped response parameter.
In scenarios with late numbering, BO instances are identified via the transactional key (%tky) during the
interactions phase. In late numbering scenarios %tky contains %pky, which contains at least two components:
%pid and %key, the actual key fields. Both components might contain preliminary key values, which must be
mapped to the final keys in ADJUST_NUMBERS.
The values of the component group %pky, which is used during the interaction phase for preliminary
identification, are assigned to the component group %pre in ADJUST_NUMBERS. To differentiate potential
preliminary key values in the key fields from the actual final key values, the preliminary in-place key values are
assigned to the component group %tmp in ADJUST_NUMBERS. The final keys in %key must be mapped to the
preliminary identifiers in %pre in ADJUST_NUMBERS. The following compilation illustrates the identifiers during
the interaction phase and in ADJUST_NUMBERS.
Identifiers in Late Numbering Scenarios
The mapping in ADJUST_NUMBERS is done from %pre to %key in the mapped response parameter. The
following example shows a mapping, where both components of %pky are used for unique identification during
the interaction phase. This isn't mandatory, you can also use only %pid or the key fields.
 Example
METHOD adjust_numbers.

...
* Fill %key-<key_field> with the adjusted number
APPEND VALUE #( %pre-%pid = 'MyPID'
%pre-%tmp-<key_field> = 'MyPreliminaryKey_InPlace'
%key-<key_field> = 'MyFinalKey'
) TO mapped-<entity>.

ENDMETHOD.
For more information about derived type components, see Components of BDEF Derived Types (ABAP -

230 PUBLIC Learn
Implementation
The method ADJUST_NUMBERS must always be implemented when late numbering is used.
Method ADJUST_NUMBERS
The method for ADJUST_NUMBERS must be redefined in the local saver class to implement it.

PROTECTED SECTION.
METHODS adjust_numbers REDEFINITION.
ENDCLASS.
// ** implement adjust_numbers here **//

ENDMETHOD.
Changing Parameter
• MAPPED
• REPORTED
Messages can be reported via the implicit changing parameter REPORTED. As consumer errors must not
appear after CHECK_BEFORE_SAVE, REPORTED should only contain success or information messages,
such as Material stock is low.
 Note
The method must not fail and thus needs no FAILED parameter, as the exchange of temporary IDs takes
place after the point-of-no-return. If the application needs to stop the transaction, it can only produce a
short dump.
Related Information
2.3.4.2.4 SAVE
Saves the data from the transactional buffer to the database.
The SAVE implementation is called during the save sequence to save the current state of the transactional
buffer to the database. All business object instances (including instances from cross-BO relationships) that are
involved in the current LUW are saved.
Managed BOs
In managed business objects, the SAVE is done by the managed BO provider.

Learn PUBLIC 231
If the business scenario requires an alternative save implementation, it is possible to define an additional or
an unmanaged save in the managed scenario. This is done by adding the following syntax in the behavior
definition.
define behavior for Entitiy [alias Alias]

implementation in class ABAP_CLASS unique
...
with additional | unmanaged save [with full data]
...

{ … }
The option is available for each BO entity separately.
The implementation is done in the corresponding method save_modified in the behavior pool. If the addition
with full data is used in the behavior definition, once an instance is modified, then not only the changed
fields but all fields are provided into the save_modified method.
It is also possible to self-implement a cleanup, if an additional or unmanaged save is defined, see CLEANUP
[page 233].
Method SAVE_MODIFIED
The method for SAVE_MODIFIED must be redefined in the local saver class to implement it.

PROTECTED SECTION.
METHODS save_modified REDEFINITION.
ENDCLASS.
METHOD save|save_modified..
// ** implement save here **//

ENDMETHOD.
Importing Parameters
The method imports a parameter for all defined modify operations.
• CREATE
This parameter entails information of instances that were created during the LUW.
• UPDATE
This parameter entails information of instances that were updated during the LUW.
• DELETE
This parameter entails information of instances that were deleted during the LUW.
Changing Parameter
• REPORTED
Messages can be reported via the implicit returning parameter REPORTED. As consumer errors must not
appear after CHECK_BEFORE_SAVE, REPORTED should only contain success or information messages,
such as Booking has been saved.
 Note
The method must not fail and thus needs no FAILED parameter. If the application needs to stop the
transaction, it can only raise a short dump.

232 PUBLIC Learn
Unmanaged BOs
For unmanaged business objects, the SAVE must always be implemented by the application developer.
The implementation is done in the corresponding method in the behavior pool.
Method SAVE
The method SAVE must be redefined in the local saver class to implement it.

PROTECTED SECTION.
METHODS save REDEFINITION.
ENDCLASS.
METHOD save.
// ** implement save here **//

ENDMETHOD.
Changing Parameter
The changing parameter REPORTED behaves like the one in SAVE_MODIFIED, see Changing Parameters in
SAVE [page 232].
Related Information
2.3.4.2.5 CLEANUP
Clears the transactional buffer.
The cleanup implementation is called after the save sequence has run, or after a ROLLBACK ENTITIES
statement for any kind of instance access during the interaction phase. The cleanup empties the transactional
buffer from any remaining instance data to terminate the LUW. It is called whenever instance data was written
to the application buffer. That means, it is called for all touched BOs during the interaction phase, no matter if
failed or successful.
After the data is persisted, or the interaction has failed, it is expected that the transactional buffer is cleared,
since the same ABAP session might be used for more than one LUW and any remaining changes in the
transactional buffer could lead to inconsistencies.
Managed BOs
In managed business objects, the CLEANUP is done by the managed BO provider.

Learn PUBLIC 233
If an additional or an unmanaged save is implemented in a managed BO, the cleanup step can also be
implemented by the application developer. This is done by adding the following syntax in the behavior
definition.
define behavior for Entitiy [alias Alias]

implementation in class ABAP_CLASS unique
...
with additional | unmanaged save and cleanup
...

{ … }
Unmanaged BOs
For unmanaged business objects, the CLEANUP must always be implemented by the application developer.
Method CLEANUP
The CLEANUP method must be redefined in the local saver class to implement it.

PROTECTED SECTION.
METHODS save|save_modified REDEFINITION.
METHODS cleanup REDEFINITION.
ENDCLASS.
METHOD cleanup.
// ** implement clean up here **//

ENDMETHOD.
This method does not have any parameters.
2.3.4.2.6 CLEANUP_FINALIZE
Clears the transactional buffer if the phase FINALIZE or CHECK_BEFORE_SAVE fails.
The method CLEANUP_FINALIZE can be redefined in the saver class of an ABAP behavior pool to implement
the buffer cleanup. It is only called if the phase FINALIZE or CHECK_BEFORE_SAVE of any BO that is involved in
the current LUW returns failed keys.
Typically, CLEANUP_FINALIZE is used in cross-BO consumption scenarios with dependencies in the early save
phases. You can then use this method to clear the transactional buffer and to revoke changes of external side
effects.

234 PUBLIC Learn
Method CLEANUP_FINALIZE
To use the method CLEANUP_FINALIZE, redefine the method in the saver class of the ABAP behavior pool.
It does not have to be defined in the behavior definition. If this method is not explicitly redefined, the buffer
clean-up only happens after the save sequence by OData explicitly or by an explicit COMMIT ENTITIES via
EML.

PROTECTED SECTION.
METHODS cleanup_finalize REDEFINITION.
ENDCLASS.
METHOD cleanup_finalize.
// ** implement cleanup_finalize here **//

ENDMETHOD.
This method does not have any parameters.
2.3.5 Entity Manipulation Language (EML)
The Entity Manipulation Language (EML) is a part of the ABAP language that enables access to RAP business
objects.
Because the consumption of business objects via the OData protocol requires a Fiori UI or a web API, EML
enables a type-safe access to business objects directly by using ABAP. EML interacts with business objects by
triggering their operations for specified entities. An operation can only be triggered by EML if the operation is
specified for the relevant entity in the behavior definition and if it implemented accordingly.
Use Cases
EML can be used to provide behavior for business objects. For example, you can implement an action that first
triggers a create and then an update operation using EML. This action enables the creation of instances with
default values and is implemented in the behavior pool of the business object for which the behavior is to be
provided.
EML can also be used to consume business objects. Typical scenarios are unit's tests that are implemented in
a class separate from the business objects to be tested. These unit tests use EML to check the transactional
behavior of business objects by triggering their operations. Other scenarios involve cross BO applications,
where business objects use each others' operations to implement their behavior or the consumption of
released business objects.
 Note
Apart from the standard EML API, which is described in this guide, there’s also a generic EML API. The
generic EML API enables the generic integration of business objects in other frameworks and isn’t covered
by this guide.

Learn PUBLIC 235
EML Scenarios
The following table gives you can overview of the different EMLscenarios, what to take into account and where
to find examples and further information:
Scenario Description Relevant Statements
Develop (BO with in IN LOCAL MODE In an EMLdevelop scenario, you • READ [page 241]
in its own behavior pool) use EML to provide functionality • READ BY Association [page 242]
for your own business object in • CREATE and CREATE BY Associa-
its own behavior pool. When the tion [page 244]
EML accesses instances of the re- • UPDATE [page 247]
spective BO with READ/READ-BY- • DELETE [page 248]
ASSOCIATION, CREATE/CREATE- • EXECUTE [page 248]
BY-ASSOCIATION, UPDATE, • AUGMENTING BY Association
[page 249]
DELETE, and EXECUTE, you can
add IN LOCAL MODE to bypass
access controls, as well as authoriza-
tion and feature control implementa-
tions. That means , for example, that
you can update a field that is defined
as READONLY in an EML develop sce-
nario.
Consume (Business Object from other In an EML consumption scenario, you • READ [page 241]
can use EML to consume business
behavior pool/released business ob-
objects in cross BO relationships or
• READ BY Association [page 242]
jects)
you can consume released business ob- • CREATE and CREATE BY Associa-
jects. In consumption scenarios, you tion [page 244]
can't add IN LOCAL MODE to the • UPDATE [page 247]
statements to bypass access controls, • DELETE [page 248]
as well as authorization and feature • EXECUTE [page 248]
control implementations.
• GET PERMISSIONS [page 251]
• SET LOCKS [page 255]
Test In an EML test scenario, you use EML • READ [page 241]
to test a business object outside of an
ABAP behavior pool. That requires us-
• READ BY Association [page 242]
ing COMMIT ENTITIES to end the • CREATE and CREATE BY Associa-

RAP LUW. When your're implementing tion [page 244]
inside the behavior pool, this is handled • UPDATE [page 247]
by the framework. • DELETE [page 248]
• EXECUTE [page 248]
• GET PERMISSIONS [page 251]
• SET LOCKS [page 255]
• COMMIT ENTITIES [page 255]

236 PUBLIC Learn
EML Statements
This section provides an overview on operations that can be triggered using the respective EML statements.
For detailed information as well as code examples for each statement, see Examples for Accessing Business
Objects with EML [page 240].
For more information about the syntax, see ABAP for Consuming RAP Business Objects (ABAP - Keyword
Documentation).
READ
The READ statement includes all operations that don't change data of entity instances (read-only access). It's
possible to read data from the selected entities and from associated entities. You can trigger multiple read
operations within one READ statement.
For an implemented example, see READ [page 241].
For more information about the syntax, see READ ENTITY, ENTITIES (ABAP - Keyword Documentation) .
MODIFY
The MODIFY statement includes all operations that change data of entity instances. You can trigger the
standard operations CREATE, UPDATE, and DELETE as well as the nonstandard operations actions and
functions. For BOs containing a projection layer, you can furthermore augment incoming requests by adding
data or modifying operations before the requests are passed to the base business object. An example use
case is augmenting a create request with instance data in order to set default values for new instances in the
augmentation implementation. It's possible to trigger multiple modify operations by one MODIFY statement.
If these operations don't depend on each other (e.g. multiple update operations on different entities), their
execution sequence isn't determined. To ensure a certain execution sequence in this case, use separate
MODIFY statements.
 Note
If a MODIFY statement triggers a create and a create-by-association operation using %cid_ref in the
same call, instance feature and instance authorization implementations are not executed. Depending on
the business logic, you need to implement respective checks by means of prechecks and/or validations.
For an implemented example, see MODIFY [page 244].
For more information about the syntax, see MODIFY ENTITY, ENTITIES (ABAP - Keyword Documentation) .
COMMIT ENTITIES
The COMMIT ENTITIES statement triggers the persistence of data from the transactional buffer to the
database for all business objects that were changed within the LUW.
In the context of an application consisting of RAP and non-RAP implementations, the statement COMMIT WORK
implicitly triggers COMMIT ENTITIES and with it the RAP save sequence to persist all the data from the
transactional buffer to the database. If the saving of data from the RAP implementation fails, for example
because validations triggered during the save sequence, the commit is aborted and all changes committed
until this point are rolled back to ensure data consistency. The COMMIT WORK is aborted when the COMMIT
ENTITIES fails. To avoid this, you can use COMMIT ENTITIES IN SIMULATION MODE to check if the save
sequence runs without a problem. The simulation mode triggers the save sequence, but doesn't persist any
data.

Learn PUBLIC 237
For an example for COMMIT ENTITIES, see COMMIT ENTITIES [page 255].
For more information about the syntax, see COMMIT ENTITIES (ABAP - Keyword Documentation).
For an example for COMMIT ENTITIES in SIMULATION MODE refer to ABAP EML - COMMIT ENTITIES IN
SIMULATION MODE (ABAP - Keyword Documentation).
ROLLBACK ENTITIES
The ROLLBACK ENTITIES statement rolls back all changes since the last commit and resets the transactional
buffer.
For an example, see ROLLBACK ENTITIES [page 259].
For more information about the syntax, see ROLLBACK ENTITIES (ABAP - Keyword Documentation).
GET PERMISSIONS
The GET PERMISSIONS statement is used to retrieve information about feature control and authorization
permissions from business objects on global and instance level.
For an example, see GET PERMISSIONS [page 251].
For more information about the syntax, see SET LOCKS (ABAP - Keyword Documentation) .
SET LOCKS
The SET LOCKS statement locks entity instances and thus prevents their modification by other users.
For an example, see SET LOCKS [page 255].
EML Operands
IN LOCAL MODE
Implementing IN LOCAL MODE is only possible if the EML implementation consumes instances of a RAP BO in
its own behavior pool. The addition IN LOCAL MODE ensures that a BO is accessed directly without checking
access control, authorization control or feature control or prechecks. For more information about the syntax,
see IN LOCAL MODE (ABAP - Keyword Documentation) and EML Operands [page 238] .
IN LOCAL MODE has the following effects for the different operations:

238 PUBLIC Learn
Affected Methods in Behav-
Operation IN LOCAL MODE Effect ior Pool Example
• READ IN LOCAL MODE by- • Access Controls: Inde- • If an EML READ acceses
• READ BY passes:: pendent of Behavior data sources with de-
ASSOCIATION Pool fined access controls
• Access Controls
• EXECUTE FUNCTION • Authorization Checks: and the operand IN
• Authorization Checks
• Method FOR LOCAL MODE, all data
GLOBAL sets are returned inde-
AUTHORIZATION pendently of the defined

access controls.
• Method FOR
INSTANCE
AUTHORIZATION
• CREATE IN LOCAL MODE by- • Authorization Checks: • You can update a read
• UPDATE passes: • Method FOR only field via EML with
• DELETE • Authorization Checks GLOBAL IN LOCAL MODE.
• EXECUTE ACTION • Feature Control AUTHORIZATION
• Precheck on projection • Method FOR
and base BO level INSTANCE
AUTHORIZATION
• Feature Control::
• Method FOR
GLOBAL
FEATURES
• Method FOR
INSTANCE
FEATURES
• Precheck:
• Method FOR
PRECHECK (Pro-
jection Layer)
• Method FOR
PRECHECK (Base
BO Layer)
For an example implementation with IN LOCAL MODE, see READ [page 241]
PRIVLEGED
Implementing PRIVILEGED enables the consumer for privileged access, e.g. to circumvent authority checks.
As a consumer, you can use privileged access to a RAP BO to circumvent authority checks for a BO. The
privileged mode must have been defined by the provider using authority contexts in the RAP BO interface that
you want to consume.PRIVILEGED can only be used, if the RAP BO entity you want to consume is defined with
with privleged mode.
For more information about syntax, see ABAP EML - PRIVILEGED (ABAP- Keyword Documentation).

Learn PUBLIC 239
Basic Statement Components
Despite variety of functions, EML statements usually contain a set common components.
MODIFY ENTITIES OF Business_Object

ENTITY BO_Entity
Operation FIELDS ( RelevantField1 RelevantField2 ) WITH internal_table | FROM
internal_table
[FAILED failed]
[MAPPED mapped]

[REPORTED reported].
Every EML statement starts with a keyword for the statement type indicating the purpose of the EML
statement, e.g. or specifiestheof theEMLREADor one or multiple entities whose instances are to be worked
on. For statements like MODIFY covering different operation types, the actual operation of the EML statement is
indicated after the entity specification part.
Depending on the operation, you must pass relevant values to identify the related instance or to pass values for
the instances. EML expects that you explicitly mark the fields that are relevant for the operation and for which
the values should be used. These fields can be either specified with the fields statement or by filling the control
structure.
The responses of the operations triggered by an EML statement are stored in typed response parameters. The
structure failed for example is used to store the keys of instances for which the triggered operations have
failed whereas the table result contains the results returned by a READ operation or by an action.
2.3.5.1 Examples for Accessing Business Objects with EML
This topic offers code examples to demonstrate how you can access business objects using the Entity
Manipulation Language (EML).
Reference Business Object
The following sections cover different EML statements that you can use for interacting with business objects.
Unless otherwise stated, the described EML statements derive from or refer to the draft business object
described in the development guide Developing Transactional Apps with Draft Capabilities [page 578].
EML can be used to trigger operations specifically for draft instances. Moreover, EML can trigger draft
actions that consider the specific characteristics of draft enabled business objects. For information on the
draft-specific usage of EML, see Draft [page 46].
READ [page 241]
MODIFY [page 244]
GET PERMISSIONS [page 251]
SET LOCKS [page 255]
COMMIT ENTITIES [page 255]
ROLLBACK ENTITIES [page 259]

240 PUBLIC Learn
Common Response Parameters [page 260]
2.3.5.1.1 READ
General Information: READ
The READ statement provides read access to entity instances and returns the requested instances and fields.
This statement can be used as a basic operation that provides necessary data to work with in subsequent
business logic.
For more information regarding the implementation contract, refer to Implementation Contract: READ [page
164].
Implementation with IN LOCAL MODE

Consumption
BO external consumption includes scenarios like unit tests that are implemented in a class separate from
the business objects to be tested. Other scenarios are cross BO applications, where business objects use
each others' operations to implement their behavior or the consumption of released business objects in the
behavior pool of a custom RAP BO. In these cases, access controls, authorization control and feature control
implementations are always triggered during a request and can't be bypassed. When consuming released
business objects, only the released part of the BO (projection ) can be consumed in the behavior pool of a
custom RAP BO.
Example: READ
The following statement reads the begin date, the end date, and the semantic ID of travel instances identified
by the importing parameter keys. In the behavior pool of the reference business object, this READ statement
is used in the validation validateDates to provide the data to be validated in subsequent checks. For further
contextual information and for the complete code of this validation, see Validate Dates [page 639].
READ ENTITIES OF /DMO/R_Travel_D IN LOCAL MODE

ENTITY Travel
FIELDS ( BeginDate EndDate TravelID )
WITH CORRESPONDING #( keys )
RESULT DATA(travels)

FAILED DATA(failed)


Learn PUBLIC 241
REPORTED DATA(reported).
The READ statement is introduced by the keywords READ ENTITIES OF followed by the behavior definition of
the business object the statement refers to.
Since this statement is contained in the behavior pool of the business object it refers to, the keywords IN
LOCAL MODE are used. They ensure priviledged access to the underlying CDS views that returns all data sets
even if access controls are defined in a DCL.
The statement at hand reads the data of travel instances, hence the ENTITY Travel is specified. Here, we use
the alias specified for the entity in the behavior definition.
The next line states the fields whose values are to be included in the read result.
The keywords WITH CORRESPONDING #( keys ) indicate that the read operation will be performed on
instances with the primary keys contained in the internal table keys. This internal table is provided as an
importing parameter of the validation method.
The internal table specified after the keyword RESULT acts as a response parameter that contains the result
of the read operation. The type of this response parameter is derived from the specified entity and from the
triggered read operation by the framework.
For information on the response parameters FAILED and REPORTED, see Common Response Parameters
[page 260].
2.3.5.1.1.1 READ BY Association
General Information: READ BY Association
The READ BY association statement uses an association of the entity specified in the EML statement in
order to read instances of an associated entity.
For more information about the implementation contract, refer to Implementation Contract: READ-BY-
ASSOCIATION [page 166].
Consumption

242 PUBLIC Learn
custom RAP BO.
Example: READ BY Association
The following statement uses the to-parent-association of booking instances identified by the importing
parameter keys in order to read the UUID of their travel instance. In the behavior pool of the reference
business object, this READ statement is used in the determination calculateTotalPrice of the booking
entity to determine that travel UUID, for which a travel price recalculation needs to be executed. For further
contextual information and for the complete code of this determination, see Calculate Total Price [page 611].

ENTITY Booking BY \_Travel
FIELDS ( TravelUUID )

LINK DATA(link)
FAILED DATA(failed)

The read statement is introduced by the keywords READ ENTITIES OF followed by the behavior definition of
the business object the statement refers to.
Since this read statement is contained in the behavior pool of the business object it refers to, the keywords IN
LOCAL MODE are used. They ensure priviledged access to the underlying CDS views that returns all data sets
even if access controls are defined in a DCL.
The statement at hand reads the data of travel instances, but the association specified for the booking entity is
used. Hence, the ENTITY Booking is specified. Here, we use the alias specified for the entity in the behavior
definition.
To indicate that the read operation is to be performed by an association, the syntax BY \ is used. After that,
the name of the association specified in the according CDS entity is used.
The next line states that only the value of the field TravelUUID is to be included in the read result.
The keywords WITH CORRESPONDING #( keys ) indicate that the read operation will be performed for
instances with those primary keys that are contained in the internal table keys. This internal table is provided
as an importing parameter of the determination method.
The internal table specified after the keyword RESULT acts as a response parameter which contains the result
of the read operation. The type of this response parameter is derived from the specified entity and from the
triggered read operation by the framework.
The internal table declared after the keyword LINK acts as another response parameter. It contains the
primary keys of the source and the target entity instances involved in the read-by-association operation. Since
the association _Travel is used in this case, the source is a booking instance and the target is a travel
instance. The type of this response parameter is derived from the specified entity and from the triggered read
operation by the framework. The response parameter LINK is not used in the determination mentioned above.
[page 260].

Learn PUBLIC 243
2.3.5.1.2 MODIFY
The MODIFY statement is used to change data of entity instances. The following sections provide examples for
operations that can be triggered using this statement.
For more information about the syntax, see MODIFY ENTITY, ENTITIES (ABAP - Keyword Documentation) .

Consumption
custom RAP BO.
General Information: CREATE and CREATE BY Association

The CREATE statement enables the creation of entity instances. The CREATE BY association statement
uses an association of the entity specified in the EML statement in order to create instances of its child entity.
For more information about the implementation contract, refer to Implementation Contract: CREATE [page
168] and Implementation Contract: CREATE-BY-ASSOCIATION [page 169].
Example: CREATE and CREATE BY Association

The MODIFY statement below involves two create operations. The first one creates an instance of the entity
travel using the prepopulated internal table create. The second one triggers a create-by-association operation
that creates two booking instances based on the created travel instance. The following code can be used in a
separate unit test class to test the create operations of the reference business object.
*Declare internal table using derived type

DATA create TYPE TABLE FOR CREATE /DMO/R_Travel_D.
*Select valid flight data
SELECT SINGLE AirlineID, ConnectionID, FlightDate FROM /DMO/I_Flight INTO
@DATA(flight).
*Populate internal table for travel instance
create = VALUE #( ( %cid = 'create_travel'
%is_draft = if_abap_behv=>mk-off
CustomerID = '1'
AgencyID = '70006'
BeginDate = flight-FlightDate
EndDate = flight-FlightDate
Description = 'Travel 1'
) ).
*Create a travel instance and two associated booking instances
MODIFY ENTITIES OF /DMO/R_Travel_D
ENTITY Travel
CREATE FIELDS ( CustomerID AgencyID BeginDate EndDate Description )
WITH create

244 PUBLIC Learn
CREATE BY \_Booking
FIELDS ( CustomerID AirlineID ConnectionID FlightDate ) WITH
VALUE #( ( %cid_ref = 'create_travel'
%target = VALUE #( ( %cid = 'create_booking_1'
CustomerID = '1'
AirlineID = flight-AirlineID
ConnectionID = flight-ConnectionID
FlightDate = flight-FlightDate )
( %cid = 'create_booking_2'
CustomerID = '1'
AirlineID = flight-AirlineID
ConnectionID = flight-ConnectionID
FlightDate = flight-FlightDate )
) ) )
MAPPED DATA(mapped)
REPORTED DATA(reported)
FAILED DATA(failed).
*Persist transactional buffer

COMMIT ENTITIES.
Before an internal table can be used for creating the travel instance, the type of this internal table needs to be
derived from the corresponding CDS entity and its behavior definition. The modify operation the internal table
is used for needs to be stated in its type declaration as well. As a result, the declared internal table contains all
CDS elements and components necessary to perform the intended modify operation.
To ensure the usage of valid flight data, we now select the airline ID, the connection ID, and the flight date from
an arbitrary row of the flight database and save its values in the local structure flight.
In the next step, the internal table is populated with the values for the travel instance using the value
operator. Here, we also use the values from the structure flight. Since the target business object supports
managed internal numbering, the primary key values don't need to be specified in the internal table. Instead,
the content ID for the travel instance provided, which can be freely selected. A content ID is used as preliminary
identifier as long as no primary key for the instance exists. In the example, it is referred to in the subsequent
create-by-association operation. Using the draft indicator %is_draft we can determine whether we want to
create active or draft instances. Since we want to create active instances, we set the draft indicator to false.

Learn PUBLIC 245
The MODIFY statement is introduced by the keywords MODIFY ENTITIES OF followed by the behavior
definition of the business object the statement refers to.
The statement at hand triggers the create and the create-by-association operation of the travel entity, hence
the ENTITY Travel is specified. Here, we use the alias specified for the entity in the behavior definition.
The keywords CREATE FIELDS are followed by the names of the fields to be populated. After the keyword
WITH we specify the name of the internal table based on which the travel instance is to be created. The derived
type assigned to the internal table ensures the type-safe creation of the travel instance. It's best practise
to use this syntax as it provides direct feedback when trying to override fields that are defined as readonly.
Furthermore, it´s not possible to set initial values for fields when the syntax SET FIELDS WITH is used
instead.
The create-by-association operation is specified by the keywords CREATE BY \ followed by the name of the
association.
After specifying the fields to be populated for the associated entity, the keyword WITH introduces the
specification of input parameters that are expected in the form of an internal table. This internal table is
constructed using the value operator containing data for two booking instances. Since we already specified the
fields to be modified, we don´t need to additionally activate them in the %control structure. As the primary
key of the travel instance for which the booking instances are to be created doesn't exist yet, the travel instance
is referred to using its content id create_travel.
The structure specified after the keyword MAPPED acts as a response parameter. It contains the information on
which primary keys were provided by the create operations for the given content IDs. The type of this response
parameter is derived from the specified entity and from the triggered operation by the framework.
[page 260].
Finally, the persistence of data to the database is triggered via the COMMIT ENTITIES statement. For more
information on this statement, see COMMIT ENTITIES [page 255].
AUTO FILL CID

For static operations like CREATE and CREATE BY ASSOCIATION, the addition AUTO FILL CID can be used
to ensure that %cid is filled with a content ID (CID). Note that, if %cid_ref is to be used, then AUTO FILL CID
must not be used for the referenced instance as %cid_ref can't refer to automatically created content IDs. In
the example below, a travel instance is created using an internal table, for which no content ID is specified. The
content ID is generated automatically during the creation of the travel instance using AUTO FILL CID.

SELECT SINGLE FlightDate FROM /DMO/I_Flight INTO @DATA(flight).
*Populate internal table for travel instance, %cid does not need to be specified
create = VALUE #( ( %is_draft = if_abap_behv=>mk-off
CustomerID = '1'
AgencyID = '70006'
BeginDate = flight
EndDate = flight
) ).
*Create a travel instance using AUTO FILL CID
ENTITY Travel
CREATE AUTO FILL CID FIELDS ( CustomerID AgencyID BeginDate EndDate
Description ) WITH create

246 PUBLIC Learn
MAPPED DATA(mapped)
REPORTED DATA(reported)

COMMIT ENTITIES.
The mapping information between the generated content ID and the key of the instance is stored in the MAPPED
structure.
General Information: UPDATE

The UPDATE statement enables the editing of entity instances.
For more information about the implementation contract, refer to Implementation Contract: UPDATE [page
172].
Example: UPDATE
The following UPDATE statement sets the status of two booking instances to 'Accepted'. Unlike on a UI, with
EML you've the choice between modifying draft or active instances. In this case, we want to update the active
instances directly. You can use the following code in a separate unit test class to test the update operation of
the reference business object. Note that the placeholders for the booking UUIDs need to be replaced before
according to the existing data.

ENTITY Booking
UPDATE FIELDS ( BookingStatus )
WITH VALUE #( ( BookingUUID = '<Booking_UUID>'
BookingStatus = 'A' )
( BookingUUID = '<Booking_UUID>'
BookingStatus = 'A' ) )
FAILED DATA(failed)
COMMIT ENTITIES.

The statement at hand triggers the update operation of the booking entity, hence the ENTITY Booking is
specified. Here, we use the alias specified for the entity in the behavior definition.
The next line states that the values of the field BookingStatus are to be updated.

Learn PUBLIC 247
The keywords WITH VALUE introduce the construction of an internal table that indicates which instances are
to be updated with which values. Within the constructor operator VALUE, the instances are first identified by
its booking UUIDs, then their values for the booking status field are specified respectively. Using the draft
indicator %is_draft we can determine whether we want to update active or draft instances. Since we want to
update the active instances directly, we set the draft indicator to false.
[page 260].
General Information: DELETE

The DELETE statement enables the deletion of entity instances.
For more information about the implementation contract, refer to Implementation Contract: DELETE [page
173].
Example: DELETE
The following statement deletes an instance of the entity travel. It can be used in a separate unit test class to
test the delete operation of the reference business object. Note that the placeholder for the travel UUID needs
to be replaced before according to the existing data.

ENTITY TRAVEL
DELETE FROM VALUE #( ( TravelUUID = '<Travel_UUID>'
%is_draft = if_abap_behv=>mk-off ) )
FAILED DATA(failed)

COMMIT ENTITIES.
The statement at hand uses the delete operation of the travel entity, hence the ENTITY Travel is specified.
Here, we use the alias specified for the entity in the behavior definition.
The value operator specifies the key of the instance that is to be deleted. Using the draft indicator %is_draft
we can determine whether we want to delete active or draft instances. Since we want to delete an active
instance, we set the draft indicator to false.
[page 260].
General Information: EXECUTE Action

This statement enables the execution of actions.
For more information about the implementation contract, refer to Implementation Contract: Action [page 176].
Example: EXECUTE Action

The following statement triggers an action that recalculates the total travel price based on changed values.
The action is executed for those instances whose keys have been determined by the READ BY association

248 PUBLIC Learn
statement. In the behavior pool of the reference business object, the following EXECUTE statement is used
in the determination calculateTotalPrice for the entities booking and booking supplement. For further
contextual information and for the complete code of this determination, see Calculate Total Price [page 611].

MODIFY ENTITIES OF /DMO/R_Travel_D IN LOCAL MODE
ENTITY Travel
EXECUTE reCalcTotalPrice
FROM CORRESPONDING #( travels )

RESULT DATA(result)

Since this statement is contained in the behavior pool of the business object it refers to, the keywords IN
LOCAL MODE are used. They ensure that authorization and feature control implementations aren't triggered.
The statement at hand executes the action for instances of the travel entity, hence the ENTITY Travel is
specified. Here, we use the alias specified for the entity in behavior definition.
The keyword EXECUTE is followed by the name of the action that is to be executed.
The action is executed only for the respective parent travel instances. Hence, the field expression FROM selects
the internal table travels has been filled with the required travel UUIDs by the READ BY association
statement described above.
The table declared after the keyword RESULT contains the result returned by the action. Since the triggered
action doesn't have a result, RESULT is filled in this case.
[page 260].
General Information: AUGMENTING
With the statement AUGMENTING you can add data or modify incoming modify requests on the projection layer
by augmenting requested modify operations before the requests are passed to the base business object.
For more information about the syntax, see MODIFY AUGMENTING ENTITY (ABAP - Keyword Documentation).
Example: AUGMENTING
The following method enables the maintenance of the entity Supplement contains a denormalized field
Description. This field is defined in the associated child entity SupplementText. Without this augmentation
method, incoming modify requests on the supplement entity can't consider the description field since it
derives from another entity. The AUGMENTING statement is used in this case to augment an incoming create
request by a create-by-association operation. This ensures that incoming create requests do not only lead
to the creation of supplement instances but also to the creation of corresponding supplement text instances
which contain the changed description field. The augmentation of incoming update requests isn't considered
in the code sample shown below. For further information on this augmentation scenario, see Editing Language-
Dependent Fields [page 854].

METHOD augment.
...

"Handle create requests including SupplementDescription
LOOP AT entities_create INTO DATA(supplement_create).
"Count Table index for uniquely identifiably %cid on creating
supplementtext

Learn PUBLIC 249
APPEND sy-tabix TO relates_create.
"Direct the Supplement Create to the corresponding SupplementText Create-

By-Association using the current language
APPEND VALUE #( %cid_ref = supplement_create-%cid
%is_draft = supplement_create-%is_draft
%key-supplementid = supplement_create-%key-SupplementID
%target = VALUE #( ( %cid = |
CREATETEXTCID{ sy-tabix }|
%is_draft =
supplement_create-%is_draft
%key-supplementid =
supplement_create-SupplementID
languagecode = sy-
langu
description =
supplement_create-SupplementDescription
%control = VALUE
#( supplementid = if_abap_behv=>mk-on
languagecode = if_abap_behv=>mk-on
description = supplement_create-%control-SupplementDescription )
) )
) TO suppltext_for_new_suppl.
ENDLOOP.

*Augment Create by a Create by Association

MODIFY AUGMENTING ENTITIES OF /DMO/I_Supplement
ENTITY Supplement
CREATE BY \_SupplementText
FROM suppltext_for_new_suppl
RELATING TO entities_create BY relates_create.

...
ENDMETHOD.

The augmentation method receives the supplement instances to be created via the importing parameter
table entities_create. For each of these instances the current table index is appended to the internal
table relates_create, which will be used by the subsequent AUGMENTING statement. Moreover, the
required instance data for the subsequent create-by-association operation are stored in the internal table
suppltext_for_new_suppl. As a result, each row of this table contains the data of the supplement instance
referenced using the component cid_ref as well as the data for the associated supplement text instance that
is to be created. This table is used in the following AUGMENTING statement.
The AUGMENTING statement is introduced by the keywords MODIFY AUGMENTING ENTITIES OF followed by
the behavior definition of the business object the statement refers to. Since AUGMENTING statements can only
refer to entities of base business objects, the business object /dmo/i_supplement is specified.
The statement at hand uses the create-by-association operation of the supplement entity, hence the ENTITY
Supplement is specified. Here, we use the alias specified for the entity in the behavior definition.
The create-by-association operation is specified by the keywords CREATE BY \ followed by the name of the
association.
The operation is performed using the prepared internal table suppltext_for_new_suppl.
It can happen that the base business object returns entries in the FAILED and REPORTED structures for
augmented requests. To relate these responses to the original request, if the augmented request contains new
instances, the AUGMENTING statement offers the addition RELATING TO allows to relate augmented instances
to original instances. The runtime uses this information to transform FAILED keys of new instances back to the
keys of the related original instances. If an augmented instance - in this case a supplement text instance - fails,

250 PUBLIC Learn
the related original instance - in this case the supplement instance - is included in the FAILED response of the
overall request.
2.3.5.1.3 GET PERMISSIONS
General Information: GET PERMISSION
This statement is used to check whether permissions in terms of authorization and feature control exist on
global and instance level. Information about permissions can be retrieved for the operations create, create-by-
association, update, and delete as well as for actions and fields. The following sections cover dedicated EML
statements for different permission types.
For general information about authorization and feature control, see Authorization Control [page 80] and
Feature Control [page 128].
For more information about the implementation contract for authorization and feature control, see
Implementation Contract: Feature Control [page 180] and Implementation Contract: Authorization Control
[page 182].
Example: Global Authorization

Global authorization is used for all authorization checks that only depend on the user. You can define global
authorization to check if users are allowed to execute an operation in general.
The following code is used to check whether the logged on user has the permission for performing create
operations on the reference business object.

*Declare derived type for authorization request
DATA: request_ga TYPE STRUCTURE FOR PERMISSIONS REQUEST /DMO/R_Travel_D.
*Activate check for create operation
request_ga-%create = if_abap_behv=>mk-on.
*Perform authorization request
GET PERMISSIONS ONLY GLOBAL AUTHORIZATION ENTITY /DMO/R_Travel_D
REQUEST request_ga
RESULT DATA(result)
FAILED DATA(failed)

Before we perform the actual authorization request, we prepare a local structure containing the requested
permission. At first, we declare this local structure using the derived type for permission requests on the
reference business object. Then we activate the create component within the structure by means of the ABAP
interface if_abap_behv.
The GET PERMISSIONS statement is introduced by the keywords GET PERMISSIONS ONLY GLOBAL
AUTHORIZATION ENTITY followed by the entity the statement refers to.
The keyword REQUEST is followed by the local structure containing the requested operation permission.
The result is saved in a local structure named result.

Learn PUBLIC 251
[page 260].
Example: Instance Authorization
Instance authorization is used for all authorization checks that, in addition to the user role, depend on the state
of the entity instance in question. With instance authorization, you can define authorization that depends on a
field value of the instance.
The following code is used to check whether performing update operations on a given travel instance of the
reference business object is possible. According to the instance authorization logic of the business object, this
depends on whether the logged on user has the update permission for the country code of the instance. The
country code of the instance is defined by the CountryCode of the agency instance that is associated with the
travel instance. Note that the placeholder for the travel UUID needs to be replaced according to the existing
data.

*Declare derived type for authorization request
DATA: request_ia TYPE STRUCTURE FOR PERMISSIONS REQUEST /DMO/R_Travel_D.
*Activate check for update operation
request_ia-%update = if_abap_behv=>mk-on.
*Perform authorization request
GET PERMISSIONS ONLY INSTANCE AUTHORIZATION ENTITY /DMO/R_Travel_D
FROM VALUE #( ( TravelUUID = '<Travel_UUID>'
REQUEST request_ia
RESULT DATA(result)
FAILED DATA(failed)

Before we perform the actual authorization request, we prepare a local structure containing the requested
reference business object. Then we activate the update component within the structure by means of the ABAP
interface if_abap_behv.
The GET PERMISSIONS statement is introduced by the keywords GET PERMISSIONS ONLY INSTANCE
AUTHORIZATION ENTITY followed by the entity the statement refers to.
The value operator specifies the key of the instance whose permissions are to be checked. Using the draft
indicator %is_draft we can determine whether we want to check the permissions for the active or for the
draft instance. Since we want to check the active instance, we set the draft indicator to false.
The keyword REQUEST is followed by the local structure containing the requested operation permission.
[page 260].
Example: Instance Feature Control
You can use instance feature control to define which fields, operations, and actions have access restrictions.
These restrictions can depend on the state of the instance.
The following code is used to check the access restrictions of the field BookingFee that is defined for the
entity Travel in the reference business object. The access restrictions for the field depend on the value of the

252 PUBLIC Learn
field OverallStatus. If the value is 'A' (accepted), the field BookingFee is read-only. Else it's unrestricted.
Note that the placeholder for the travel UUID needs to be replaced according to the existing data.

*Declare derived type for feature control request
DATA: request_ifc TYPE STRUCTURE FOR PERMISSIONS REQUEST /DMO/R_Travel_D.
*Activate check for field
request_ifc-%field-BookingFee = if_abap_behv=>mk-on.
*Perform feature control request
GET PERMISSIONS ONLY INSTANCE FEATURES ENTITY /DMO/R_Travel_D
FROM VALUE #( ( TravelUUID = '<Travel_UUID>'
REQUEST request_ifc
RESULT DATA(result)
FAILED DATA(failed)

Before we perform the actual feature control request, we prepare a local structure containing the requested
reference business object. Then we activate the check for the field using the field component within the
structure by means of the ABAP interface if_abap_behv.
The GET PERMISSIONS statement is introduced by the keywords GET PERMISSIONS ONLY INSTANCE
FEATURES ENTITY followed by the entity the statement refers to.
The value operator specifies the key of the instance whose permissions are to be checked. Using the draft
indicator %is_draft we can determine whether we want to check the permissions for the active or for the
draft instance. Since we want to check the active instance, we set the draft indicator to false.
The keyword REQUEST is followed by the local structure containing the requested field permission.
[page 260].
Checking Results
The following screenshot shows the structure result resulting from the preceding instance feature control
permission request in the debugger. The permission request has been performed for a travel instance with the
overall status Accepted.

Learn PUBLIC 253
To interpret the returned permission value, we consult the ABAP interface if_abap_behv in the element
info. It contains a legend explaining the meaning for returned values. In the section containing the constants
for feature control, there's a subsection for fields. This subsection contains the meaning of field value '02':
read_only.
The values returned for the other get permissions statements shown above can be evaluated accordingly. Note
that the value returned for operations or fields that haven't been requested is always '00'.

254 PUBLIC Learn
2.3.5.1.4 SET LOCKS
General Information: SET LOCKS
Before entity instances can be modified, they need to be locked for the corresponding user. When performing
modify operations, this step is taken over implicitly by the framework. It isn't necessary to lock an instance
explicitly before performing a modify operation. However, to prevent other users from modifying an instance,
the SET LOCKS statement can be used. The instance is then locked for the corresponding user and can't be
modified by other users until the lock is released at the end of the transaction.
For more information about the implementation contract, see Implementation Contract: LOCK [page 174].
Example: SET LOCKS
The following statement locks an instance of the reference business object. Note that the placeholder for the
travel UUID needs to be replaced according to the existing data.

SET LOCKS OF /DMO/R_Travel_D
ENTITY TRAVEL
FROM VALUE #( ( TravelUUID = '<Travel_UUID>' ) )
FAILED DATA(failed)

The SET LOCKS statement is introduced by the keywords SET LOCKS OF followed by the entity the statement
refers to.
The statement at hand locks an instance of the travel entity, hence the ENTITY TRAVEL is specified.
The next line specifies the primary key of the instance that is to be locked.
[page 260].
2.3.5.1.5 COMMIT ENTITIES
COMMIT ENTITIES
General Information: COMMIT ENTITIES

The COMMIT ENTITIES statement triggers amongst others the save sequence, which persists data from the
transactional buffer to the database. The COMMIT ENTITIES statement triggers the persistence of data from

Learn PUBLIC 255
the transactional buffer to the database for all business objects that were changed within the LUW. COMMIT
ENTITIES needs to be specified explicitly for modify operations that are triggered outside of a behavior pools
to terminate the LUW. For modify request from within a behavior pool, COMMIT ENTITIES and subsequently
the save sequence is triggered by the framework.
For more information about the syntax, see COMMIT ENTITIES (ABAP - Keyword Documentation).
Example: COMMIT ENTITIES
The following example code shows a MODIFY CREATE statement followed by a COMMIT ENTITIES statement,
which are executed on the reference business object.

"Declare internal table using derived type
"Select valid flight data
"Populate internal table for travel instance
CustomerID = '1'
AgencyID = '70006'
BeginDate = flight
EndDate = flight
) ).
"Create travel instance
ENTITY Travel
CREATE FIELDS ( CustomerID AgencyID BeginDate EndDate Description ) WITH
create
MAPPED DATA(mapped_modify)
REPORTED DATA(reported_modify)
FAILED DATA(failed_modify).
"Persist travel instance
COMMIT ENTITIES
RESPONSE OF /DMO/R_Travel_D
FAILED DATA(failed_commit)

REPORTED DATA(reported_commit).
The created travel instance is persisted and visible in the database /DMO/A_TRAVEL_D.
Persisted Travel Instance
Simulation Mode
General Information: Simulation Mode
If the COMMIT ENTITIES statement is used with the addition IN SIMULATION MODE, the save sequence
is executed without actually saving any data. This means that in simulation mode, the methods finalize,
check_before_save, and cleanup_finalize are executed, but the methods adjust_numbers, save
and cleanup are not. Since determinations and validations are executed by the methods finalize and
check_before_save, the simulation mode can be used to check whether the finalized data could be
persisted, if a COMMIT ENTITIES statement without simulation mode was executed.

256 PUBLIC Learn
Example: Simulation Mode
The following example code shows a MODIFY CREATE statement followed by a COMMIT ENTITIES statement
in simulation mode, which are executed on the reference business object. The COMMIT ENTITIES statement in
simulation mode checks whether the created travel instance can be persisted.

"Populate internal table for create operation
CustomerID = '1'
AgencyID = '70006'
BeginDate = flight
EndDate = flight ) ).
ENTITY Travel
CREATE FIELDS ( CustomerID AgencyID BeginDate ) WITH create
FAILED DATA(failed_modify)
REPORTED DATA(reported_modify).
"Check whether saving is possible
COMMIT ENTITIES IN SIMULATION MODE

In order to determine whether the instance can be persisted, the response parameters FAILED and REPORTED
of the COMMIT ENTITIES statement can be checked. These parameters are populated by validations in case
of inconsistencies.
Failed Key for Travel Instance
The FAILED parameter contains an entry in its travel table for the created travel instance, which means
that this instance cannot be persisted. In order to determine the reason for the failed commit operation, the
response parameter REPORTED can be checked.

Learn PUBLIC 257
Reported Message
The %MSG component contains a reference to the corresponding message. Its text is displayed in the ABAP
Exception view after double clicking the %MSG component in the Variables tab.
Message Text
The failed key and the message have been returned by the validation validateDates, which prevents the
persistence of instance data in case of inconsistent dates. In this example, the end date is missing as the
corresponding field has not been specified in the FIELDS expression of the MODIFY statement. After adding
the field EndDate to the FIELDS expression, the instance data is consistent and can be persisted using a
COMMIT ENTITIES statement.

"Populate internal table for create operation
CustomerID = '1'
AgencyID = '70006'
BeginDate = flight
EndDate = flight ) ).
ENTITY Travel
CREATE FIELDS ( CustomerID AgencyID BeginDate EndDate ) WITH create
"Persist travel instance

COMMIT ENTITIES.

258 PUBLIC Learn
2.3.5.1.6 ROLLBACK ENTITIES
General Information: ROLLBACK ENTITIES
The ROLLBACK ENTITIES statement resets the transactional buffer. It is used outside of behavior pools to roll
back all changes done since the last COMMIT ENTITIES operation.
For more information about the syntax, see ROLLBACK ENTITIES (ABAP - Keyword Documentation).
Example: ROLLBACK ENTITIES
The following code demonstrates the effect of the ROLLBACK ENTITIES statement. After declaring and
populating internal tables which will be used for subsequent MODIFY statements, a first instance is created
using a MODIFY statement and persisted using a COMMIT ENTITIES statement. Then, after the creation of
the second instance, the transactional buffer is reset using the ROLLBACK ENTITIES statement. The following
COMMIT ENTITIES statement causes no change in the database as the transactional buffer has been emptied
by the ROLLBACK ENTITIES statement. At the end of the execution, the database only contains one travel
instance.
For more information on the COMMIT ENTITIES statement, see COMMIT ENTITIES [page 255].
 Expand the following code sample to view the source code
 Sample Code
*Declare internal tables using derived type

DATA travel1 TYPE TABLE FOR CREATE /DMO/R_Travel_D .
DATA travel2 TYPE TABLE FOR CREATE /DMO/R_Travel_D .
SELECT SINGLE FlightDate FROM /DMO/I_Flight INTO @DATA(flight1).
*Populating the internal tables
travel1 = VALUE #( ( %cid = 'create_travel_1'
CustomerID = '1'
AgencyID = '70006'
BeginDate = flight1
EndDate = flight1 ) ).
travel2 = VALUE #( ( %cid = 'create_travel_2'
CustomerID = '2'
AgencyID = '70007'
BeginDate = flight1
EndDate = flight1 ) ).
*Create first travel instance
ENTITY Travel
CREATE FIELDS ( CustomerID AgencyID BeginDate EndDate ) WITH travel1.
COMMIT ENTITIES
FAILED DATA(failed_commit1)
REPORTED DATA(reported_commit1).

Learn PUBLIC 259
*Create second travel instance
ENTITY Travel
CREATE FIELDS ( CustomerID AgencyID BeginDate EndDate ) WITH travel2.
*Reset transactional buffer
ROLLBACK ENTITIES.
*Persist (empty) transactional buffer
COMMIT ENTITIES
FAILED DATA(failed_commit2)
REPORTED DATA(reported_commit2).

2.3.5.1.7 Common Response Parameters
EML statements have their own response parameters. These response parameters receive data from the
operations triggered by the respective EML statement. Response parameters that can be used in many EML
statements are the structures FAILED and REPORTED. These structures contain nested tables for each entity
of the BO. The FAILED structure logs the keys of instances for which a triggered operation has failed. The
REPORTED structure logs messages that have been returned from a triggered operation. The types of both
response parameters are derived from the involved entity and operation by the framework.
The following example code shows a CREATE and a COMMIT ENTITIES statement which are executed on the
reference business object.

*Populate internal table for create operation
CustomerID = '1'
AgencyID = '70006'
BeginDate = flight ) ).
*Create travel instance
ENTITY Travel
CREATE FIELDS ( CustomerID AgencyID BeginDate ) WITH create
*Try to persist travel instance
COMMIT ENTITIES

The create operation is executed without errors and hence does not return any keys to the FAILED structure.
The commit operation however cannot be executed because the end date has not been provided for the travel
instance. The validation validateDates, which is executed as part of the commit operation, detects the
missing end date and returns the key of the failed instance to the FAILED structure of the COMMIT ENTITIES
statement. Moreover, a message indicating the reason for the failed persistence is returned to the REPORTED
structure.
Response parameters dedicated to specific operations like MAPPED or LINK are covered in the sections for the
respective EML statements.

260 PUBLIC Learn
2.3.6 Messages
This topic explains the basic message concepts relevant for the ABAP RESTful Application Programming
Model.
About Messages
Messages offer an important way to guide and validate consumer and user actions, and help to avoid and
resolve problems. Thus, messages are important to communicate problems to a consumer or user. Well-
designed messages help to recognize, diagnose, and resolve issues. That's why it's important to always use
messages consistently and optimize the interaction as a whole. Consequently, errors and warnings that require
action should be clearly stated and described in a way that helps to resolve the issue quickly and efficiently. It’s
recommended to provide a message for each entry in the fail structure to provide additional information.
There are different types of messages depending on whether they refer to the state of a business object
instance or only to the current request. State messages refer to a business object instance and transition
messages refer to a request. State messages must always be bound to a business object instance (bound),
whereas transition messages can either be bound or unbound (not related to a business object instance).
Messages in EML
When you execute a modify request, the keys of the failed instances are returned in the failed structure.
Messages for the related failed instance are returned with the reported structure whose components are
derived at runtime by the compiler depending on the returned values. The following components of the
reported structure are relevant for the message handling:
• REPORTED
• %CID: ID of the relevant instance
• %MSG: Filled with an instance of the message-wrapper class
• %ELEMENT: Lists all fields or associations of an entity the message relates to.
• %STATE_AREA: If this component of type String is filled in, the framework interprets a message as
state message.
• %OP: This component indicates to which executed operation the message relates to. This component is
only relevant for transition messages.
• %OTHER: The reported structure contains a table for each entity defined and in addition %OTHER
for all messages that aren’t entity-related. The %OTHER component is filled with an instance of the
message-wrapper class when a message isn’t related to a business object entity (Unbound messages)
• %path (only relevant for child entities): The path component maps a child entity to its parent. If there’s
a business object with several child entities, the %PATH component is extended to map the child entity
to its parent and the business object root.
With the %ELEMENT component, you can assign messages to one or several target fields. These targets are
interpreted by the client and result in an improved user experience, because the target establishes a visible link
between the message and the target field that also enables navigation if there are many error messages. The

Learn PUBLIC 261
%STATE_AREA component determines whether a message is interpreted as state message. If this component
is left empty, a message is interpreted as a transition message. If the component is filled in, the message is
interpreted as a state message. The component %OP becomes important to distinguish to which operation the
message relates to if many operations or actions are requested for the same instance.
For more general information about the reported and failed structure, see:
• Reported Structure. [page 153]

• Failed Structure. [page 152]
For more information about how messages behave in EML, see Message Behavior in EML (Entity Manipulation
Language) [page 274].
.
Related Information
State Messages [page 268]

Transition Messages [page 264]
2.3.6.1 Generic Message Implementation
Generic Message Implementation
Generally, the message creation and allocation to a reported structure is identical for every scenario:

APPEND VALUE #(
%tky = instance-%tky
%msg = NEW message_exception(
textid =
message_exception=>message_exception_constant
severity = if_abap_behv_message=>severity-
severity
message_variable = instance-field )
%element-field1 = if_abap_behv=>mk-on
%element-_association = if_abap_behv=>mk-on
%op-%create = if_abap_behv=>mk-on
%op-%action-action1 = if_abap_behv=>mk-on
%state_area = 'state_area'
%path = VALUE #( <root>-%is_draft = <child>-
%is_draft
<root>-<key> = <child-
<parent_key_in_child_entity> )) TO reported-business_object_entity.

• APPEND: Appends the message to the reported structure
• %tky: The %TKY makes it possible to uniquely identify to which instance a message belongs. A %TKY is
always required for state messages - if state messages are accessed via EML, the respective messages can

262 PUBLIC Learn
only be returned if the %TKY of the instance is known. For transitions messages, the %TKY is required for
the framework to resolve a %element-field1 target assignment. If a transition message doesn't have a
%TKY, the target isn't resolved in an OData response and the message is interpreted as unbound transition
message by the framework.
• Message_Exception: In this example, a message exception class is used to encapsulate the messages
stored in a message class to handle the formatting of message variables types like dates or amounts via
the exception class. You can adapt the message exception class to fit your specific message requirements
if necessary.
For an example implementation, see Creating a Message Exception Class [page 869].
• Message_Exception_Constant: A message constant is implemented for every message contained in
the message class. The constant contains the message class from where the message is drawn and the
message number to identify one specific message and its variables.
• Severity: The severity specifies if a message is a success, information, warning, or an error message.
Depending on the severity, the message is displayed with different icons and colors on the UI. You can
select between the following options:
• Success: A success message informs the user that a process or action was completed successfully.
No action is required from the user-side. Note that success messages are omitted in some cases.
• Information: An information message offers additional information about a process or an action. No
action is required from the user-side.
• Warning: A warning indicates that an action may be required on the user-side.
• Error: An error occurred and an action is required on the user interface.
• Message_Variable: You can pass one or more message variables, if they’re required for the message you
want to display. It’s recommended to declare all CDS view fields as possible but optional input parameters
in your message exception class, so you can use all fields as variables if necessary.
• %element-field1/field2: The referenced field is used as a target for the message. This improves
the user experience, as it enables navigation and clear allocation of errors when there are multiple error
messages.
%element can also contain associations to child nodes (for example, Sales Order Header -> Sales Order
Item). If the target refers to an association, the message references all subinstances of the association.
This is useful, for example, if there are no subinstances to issue a message saying that at least one subitem
must exist on parent level.
For more information, about how a target assignment is displayed in a UI use case, refer to State Messages
on the UI [page 271].
• %op-create/%action-action1: The referenced standard or non-standard operation is used to indicate
to which operation the message in reported refers to. If more than one operation is executed for the
same entity instance in one EML or OData call, the %op-indicator is relevant to map the messages to the
corresponding operations. Functions are also addressed via the component %op-%action.
This component is only relevant for transition messages. State messages don't belong to operations.
• %state_area (only relevant for state messages): This message is identified as state message since this
component is filled .For a transition message, this component isn’t filled.
For more information about state messages, see State Messages [page 268].
• %path (only relevant for child entities): The path component maps a child entity to its parent. If there’s a
business object with several child entities, the %PATH component is extended to map the child entity to its
parent and the business object root.
• REPORTED-BUSINESS_OBJECT_ENTITY: This message is bound since it’s allocated to a specific business
object entity. Unbound messages are allocated to the %other component instead of a specific entity.

Learn PUBLIC 263
• Longtexts: If a message has a longtext, the longtext is automatically displayed on the UI together with the
message and no additional implementation is required.
2.3.6.1.1 Transition Messages
Transition messages refer to a triggered request.
Transition Messages
Transition messages refer to a triggered request and are only valid during the runtime of the request. In
contrast to state messages, they don't have any relation to the state of the business object itself, but instead to
the transition between states. A typical example for a transition message could be: "Business Object is locked
by user &1". As the example refers to a request relevant for a specific entity, it’s classified as a bound transition
message.
Optionally, a transition message can be bound to a business object entity by adding a %tky to identify the
instance and adding the transition message to the REPORTED structure of a business object entity.
The %path Component for Child Entities

The %path component must be filled in for all child entities of a root entity to explicitly map child entities to the
parents. For a direct child of a root, the %path component maps the child entity to the specific parent instance
using the primary key and the draft-indicator. In the following example the draft parent (%is_draft) is mapped
to the child draft via the instance keys:

%path = VALUE #( <root>-%is_draft = <child>-%is_draft

<root>-<key> = <child-<parent_key_in_child_entity> ))
For a business object consisting of three entities, the second child entity is mapped to the direct parent entity
and additionally to the root of the business object. The %path component allows efficient mapping between
the entities at runtime.

%path = VALUE #( <root>-%is_draft = <child_2>-%is_draft
<root>-<key> = <child_2>-<root_key_in_child2_entity>
<parent>-%is_draft = <child_2>-%is_draft

<parent>-<key> = <child_2>-<parent_key_in_child2_entity> )
For a specific implementation example, refer to Sample Implementation: validateBookingDate (Booking)

[page 878].
The %tky Component

The %tky defines whether a transition message refers to a specific business object instance or not. You can
define entity-bound transition messages belonging to a business object entity without referring to specific
instances with the following syntax:

APPEND VALUE #( %msg = NEW messagewrapper(
textid = message_exception=>message_exception_constant
severity = if_abap_behv_message=>severity-severity


264 PUBLIC Learn
message_variable = read_result-field ) ) TO reported-
business_object_entity.
If no %tky is specified, the transition message doesn't refer to an instance of the business object, but the
message is still semantically related to the respective entity the REPORTED structure belongs to. This syntax
is required, for example, if you want to return a transition message in the context of global authorizations or
global feature control. In global methods, no business object instance exists, but the message is related to
a specific entity of the business object. Note that components that rely on the %tky to resolve assignments
like %element are ignored in this context. Transition messages without instance reference are interpreted as
unbound transition messages in the OData metadata, however defining an unbound transition message in the
context of global authorization isn't possible. Note that the global flag is set automatically by the framework
and can't be set manually.
Generic Message Implementation: Bound Transition Message
A message is interpreted as a transition message if the %STATE_AREA isn’t filled in the implementation.
The following generic implementation is an example of an instance-bound transition message (added to the
reported structure of a business object entity and referencing a business object instance with the %tky
component) with one message variable. It’s recommended to have target fields assigned to the (%ELEMENT-
FIELDNAME) component, if the transition message relates to a particular field value. This doesn't affect the UI,
but the target is transmitted as part of the OData metadata.
Instance-bound transition messages require a %tky as instance reference to resolve assignments to the
%element component. If no %tky is specified, these assignments are ignored during runtime. Instance-bound
messages are returned from instance method implementations like instance feature control or instance
authorization. An instance-bound transition message with a %tky as instance is generically implemented as
follows:

APPEND VALUE #(
textid = message_exception=>message_exception_constant

message_variable = instance-field ) ) TO reported-
business_object_entity.
As this example message is attached to a business object entity, the assumption is that the content of the
message is related to the request for a specific entity. If this isn't the case and the transition message has no
link to any business object entity, a transition message can be bound to the %OTHER component.
For a specific implementation example, refer to Sample Implementation: setToBooked (Travel) [page 877].
Entity-bound transition messages are semantically only related to an entity, but not a specific instance. Hence,
entity-bound transition messages are implemented without an instance reference and are returned from
global method implementations like global feature control or global authorization. An entity-bound transition
message is generically implemented as follows:

APPEND VALUE #(
%msg = NEW messagewrapper(
textid =
message_exception=message_exception_constant
message_variable = read_result-field ) ) TO
reported-business_object_entity.

Learn PUBLIC 265

This example is implemented without a %tky reference since global exits are called before a specific business
object instance is created. The %msg component is filled exactly like an instance-bound transition message. If
a %element is defined in this case, the assignment is ignored during the runtime. For more details, refer to the
section The %tky Component.
Generic Message Implementation: Unbound Transition Message
An unbound transition message is allocated to the %OTHER component. This generic implementation
represents a transition message that passes one message variable to the message-wrapper class and is
allocated to the %OTHER component.

reported-%other = VALUE #( ( NEW message_exception(
textid =
severity =
if_abap_behv_message=>severity-severity
message_variable = instance-field ) ) ).

2.3.6.1.1.1 Unbound and Bound Transition Messages on the UI
This topic shows how bound and unbound transition messages are displayed with UI5.
Unbound and Bound Transition Messages on the UI
 Note
The display of messages depends on the OData version and the UI technology, so the display may vary.
A transition message appears as a pop-up message and is gone once the pop-up window is closed. The
rendering is the same for bound and unbound transition messages. The following example refers to a bound
transition message in an action implementation. The action AcceptTravel modifies the travel entity and
changes the overall status (field overall_status) to 'A' (accepted). To make sure that the state transition was
successful, an information message is thrown after the action was called to confirm that the overall status was
indeed changed. Because this change triggers a change of the business object state and is directly related
to the travel entity, the message is defined as a bound transition message and is allocated to the reported-
travel structure. Furthermore, since the request is related to the field overall_status, this field is added as
element target. This doesn't directly affect the UI, but the information is contained in the OData Metadata. This
example doesn't pass any message variables, but they can be passed by filling the defined import parameters
of the /DMO/MESSAGEWRAPPER class. For a generic example of a message with message variables, you can
refer to State Messages [page 268]. :
APPEND VALUE #( %MSG = NEW /DMO/MESSAGEWRAPPER(

TEXTID = DMO/MESSAGEWRAPPER=>ACTION_APPROVAL

266 PUBLIC Learn
SEVERITY = IF_ABAP_BEHV_MESSAGE=>SEVERITY-INFORMATION )
%ELEMENT-OVERALL_STATUS = IF_ABAP_BEHV=>MK-ON

) TO REPORTED-Travel.
This transition message is rendered as a pop-up on the UI with OData V4 once the respective action is triggered
and completed. The pop-up depends on the message severity - messages with severity information, warning
and error are displayed in a pop-up that can be closed by the user:
Since usually no action is required if there’s a success message, a transition message with this severity appears
as a brief pop-up and disappears on its own without any user interaction:

Learn PUBLIC 267
2.3.6.1.2 State Messages
State messages refer to a business object instance and its values.
State Messages
 Caution
A state message must always be bound to a business object entity and can't be allocated to the %OTHER
component. You musn't define state messages in an action or function added on projection level. If a state
message is issued in a projection, this leads to a short dump.
 Caution
If a rollback is triggered in the context of an exposed RAP OData service, the state of a business object is
returned to the state it had before the request as executed. Since state messages always reflect the current
state of the persisted entity, state messages triggered after the initial request and before the rollback are
invalid with regards to the persisted entity. As a consequence, the framework converts state messages
triggered during this time frame to transitions messages that are then allocated to the REPORTED structure
of the respective MODIFY request.
If a business object is consumed via EML in a non-RAP scenario, and the SAVE is canceled in the
CheckBeforeSave phase, the business object remains in its state and the state messages are preserved.
State messages refer to a business object instance and its values. For a business object with draft capabilities,
they’re persisted until the state that caused the message is changed and in a managed scenario, the messages
are buffered until the end of the session. Messages in validations and determinations (that are part of a
determine action or the Prepare action in a draft scenario) can typically be considered as state messages.
Validations usually check the business object values for inconsistencies, thus reflecting the business object
state, whereas determinations trigger changes to the business object state. Depending on your scenario, state
messages may be converted to transition messages.
 Example
If a validation returns an error message regarding an incorrect value in a field, the state message is
persisted until the value is changed and the save sequence is triggered again.
Using state messages is only recommended for the following cases:
• Business Object with Draft Capabilities: Determinations and Validation that are allocated to the PREPARE
or a determine action
• Unmanaged Business Object: Finalize/Check Before Save Code Exit
• Managed Scenario: Determinations/Validation on Save
The %state_area Component

State messages are defined as such when the %state_area component is filled in with a string in the
REPORTED structure. Regarding the naming, it’s recommended to choose a name that uniquely identifies the

268 PUBLIC Learn
condition that the message originates from. For example, if a validation checks if a CustomerID the user
entered is consistent with customers stored in a customer table, the %state_area 'Invalid_Customer' can be
helpful in characterizing the condition because of which the validation failed. Alternatively, you can choose
the name of the operation a message is thrown in as %state_area . This value isn’t displayed on the UI
nor is it contained in the OData metadata - the %state_area is only used to clear state messages from the
corresponding message table.
Consequently, you need to define a %state_area for each unique condition you're checking against and want
to be able to invalidate your messages for.
The %path Component for Child Entities
The %path component must be filled in for all child entities of a root entity to explicitly map child entities to the
parents. For a direct child of a root, the %path component maps the child entity to the specific parent instance
using the primary key and the draft-indicator. In the following example the draft parent (%is_draft) is mapped
to the child draft via the instance keys:

%path = VALUE #( <root>-%is_draft = <child>-%is_draft

<root>-<key> = <child>-
<parent_key_in_child_entity> )
For a business object consisting of three entities, the second child entity is mapped to the direct parent entity
and additionally to the root of the business object. The %path component allows efficient mapping between
the entities at runtime.

%path = VALUE #( <root>-%is_draft = <child_2>-%is_draft
<root>-<key> = <child_2>-
<root_key_in_child2_entity>
<parent>-%is_draft = <child_2>-%is_draft
<parent>-<key> = <child_2>-
<parent_key_in_child2_entity> )

For a specific implementation example, refer to Sample Implementation: validateBookingDate (Booking)

[page 878].
Invalidating State Messages
State messages must be invalidated so that the messages aren't continuously added to a REPORTED structure
if the same request is triggered multiple times on the same instance. You can only invalidate messages
belonging to the same %state_area in one statement. Each unique %state_area needs to be invalidated
separately. Use the following syntax to invalidate state messages in context of a Managed Business Object:

APPEND VALUE #( %tky = instance-%tky

%state_area = 'state_area' ) TO REPORTED-BUSINESS_OBJECT_ENTITY.
The %state_area component invalidates all messages that were added to the REPORTED structure with the
same state area property for the instance with the %tky component. Since the %msg is undefined, all %msg that
were added beforehand with the respective %state_area are removed by the framework from the message
table:

"Clear state area for instance
APPEND VALUE #( key = instance-key

%state_area = if_abap_behv=>state_area_all ) TO REPORTED-
BUSINESS_OBJECT_ENTITY.

Learn PUBLIC 269
Generic Message Implementation: State Message
A message is interpreted as state message once the %state_area component is filled in. The following
generic implementation is a state message with two target fields that is allocated to a business object entity
passing one field as a message variable:

APPEND VALUE #(
textid =
severity
message_variable = instance-field )
%element-_association = if_abap_behv=>mk-on
%op-%create = if_abap_behv=>mk-on
%op-%action-action1 = if_abap_behv=>mk-on
%state_area = 'state_area'
%path = VALUE #( <root>-%is_draft = <child>-
%is_draft
<root>-<key> = <child-
<parent_key_in_child_entity> )) TO reported-business_object_entity.

For more information, about how state messages are displayed on the UI and a more specific implementation
example, refer to State Messages on the UI [page 271].
For an example implementation with state and transition messages, refer to Creating a Message Exception
Class [page 869] and Exposing Messages for a Sample Business Object with Draft Capabilities [page 875].
State Messages in Read Operations
Read operations, including functions, don't cause any changes to the business object state, but simply return
data. Consequently, a read or function implementation can't issue new state messages.
In OData V4, a function with result type entity returns the respective entity including the respective state
messages. In OData V2, the entity is returned without state messages as default behavior.
For more information about how messages behave in EML, refer to Message Behavior in EML (Entity
Manipulation Language) [page 274].

270 PUBLIC Learn
2.3.6.1.2.1 State Messages on the UI
This topic shows that state messages are displayed with UI5.
State Messages on the UI
The representation of messages depends on the UI technology and the following screenshots are UI5-specific
and the message representation may vary in other cases.
State messages are displayed in a message pop-over and they’re persisted until the state of the business
object changes. If a message is assigned to field in %ELEMENT, the respective field is framed in the severity
color to illustrate the link between the field values and a message in order to improve the user experience.
The following example is extracted from the implementation of the validateDates method from the
managed scenario. This validation checks if the start date is earlier than the enddate. Since a validation refers
to the state of business object, the %state_area component is filled in with 'VALIDATE_DATES'. If you
implement several state messages within the same implementation, it is recommended to use the same value
for all %state_area definitions.
For this validation, two target elements %element-BeginDate and %element-EndDate are defined, since
these field values are checked in the validation. The class /dmo/cm_flight_home is used as a message-
wrapper class in this case. The specific message id and the respective variables necessary for the message
text are contained in the end_date_before_begin_date constant. For this message, the begin_date (type
DATS). end_date (type DATS) and travel_id (type String) are passed as variables for the message. The
message severity is defined as Error indicating that the date must be changed by the user for incorrect values.
The message is allocated to the reported structure of the travel entity:

APPEND VALUE #( %tky = ls_travel_result-%tky
%state_area = 'VALIDATE_DATES'
%msg = NEW /dmo/cm_flight_home( textid = /dmo/
cm_flight_home=>end_date_before_begin_date
begin_date
= ls_travel_result-begindate
end_date
= ls_travel_result-enddate
travel_id
= ls_travel_result-travelid
severity
= if_abap_behv_message=>severity-error )
%element-begindate = if_abap_behv=>mk-on

%element-enddate = if_abap_behv=>mk-on ) TO reported-
travel.

Learn PUBLIC 271
If a date is incorrect, the state message is rendered as follows after the user tries to save the travel instance:
The defined target elements are framed in red to indicate the link between the message and the respective
fields. As a state message, the validation result appears in the message box on the lower left. The defined
message length exceeds the maximum length for a short text and is automatically displayed in the longtext
view so that the complete text is readable for the user. The message is allocated to the travel entity that has the
label Managed- Travel with Semantic Key - the heading for the message is always derived from the business
object label to whose reported structure the message was allocated. Furthermore, the state messages enable
the user to navigate between the messages and the affected field. The respective message then appears on the
bottom of the affected fields:
Related Information

272 PUBLIC Learn
Creating a Message Exception Class [page 869]
Exposing Messages for a Sample Business Object with Draft Capabilities [page 875]
2.3.6.2 Message Mapping
In a cross-BO scenario, you may need to map messages between different RAP business objects to adapt the
message context, the %element reference or to filter messages to fit your specific business requirements.
About Message Mapping
You can use message mapping to fit messages from foreign business objects or underlying base BOs to the
business context of your exposed RAP BO. This is necessary if you want to bind a message to a UI-element for
highlighting when an error occurs. Furthermore, messages need to be mapped so that they can be allocated to
the target context: On the UI, state messages are displayed grouped to the BO entity where they were issued.
If a third-party BO returns a message, for example because it's called in an EML statement, the returned state
message should be mapped to the target context in order to be displayed correctly grouped on the UI.
Foreign Entity Definition
A RAP BO entity is added as foreign entity by adding foreign entity ForeignEntityName to the BDEF
header in the base BO or the projection BDEF. The referenced entity must be part of a composition tree
and each entity you want to map must be listed separately. The REPORTED structure is extended with the
referenced entities that enables you to map the messages accordingly.
For more information about the syntax, refer to CDS BDL - foreign entity (ABAP - Keyword Documentation) .
Map Messages Implementation
When a business object is defined as foreign entity in a BDEF, the reported structure of the original
BO is extended with the components of the foreign entity allowing you to map the messages originating
from the foreign entity to the business context of the original business object. The message mapping is
implemented in a redefined method based on the base class method MAP_MESSAGES that can be added to
the BO behavior pool, but the implementation is optional. If implemented, the method is called immediately
after every invocation of a saver class that has returned messages in reported. This means that the message
mapping occurs before the messages are processed further by the RAP framework. Message consumers only
receive the mapping result without any indication about the changes in the MAP_MESSAGES method. If several
RAP BOs are part of a MODIFY request, the MAP_MESSAGES implementations are called for every RAP BO
during the save sequence.

Learn PUBLIC 273
Related Information
Mapping Messages Between Business Objects [page 880]
2.3.6.3 Message Behavior in EML (Entity Manipulation

Language)
This topic describes how transition and state messages behave in EML.
Transition Messages
As transition messages are semantically related to the current request and not a business object state,
transition messages are returned with the REPORTED structure of the respective MODIFY statement.
For example, if an action throws a transition message and the actions is triggered with a MODIFY statement, the
transition message is returned with the REPORTED structure of the same statement. Transition messages are
bound to a request, so the message can't be accessed at a later point in time, meaning it isn't contained in the
REPORTED structure of the COMMIT statement, nor is the message returned in case of a READ statement.
State Messages
As state messages are semantically related to the state of business object, state messages aren't returned with
the REPORTED structure of a MODIFY request, but can instead only be accessed via a READ. All thrown state
messages are pooled during the modify operations and are returned with a READ on the business object entity
for which the MODIFY requests were triggered.
For example, if a MODIFY - CREATE triggers a validation during the save sequence that throws a state
message, this message isn't contained in the REPORTED structure of the same request, but in the REPORTED
structure of the next READ on the same instance.
 Caution
If a rollback is triggered in the context of an exposed RAP OData service, the state of a business object is
returned to the state it had before the request as executed. Since state messages always reflect the current
state of the persisted entity, state messages triggered after the initial request and before the rollback are
invalid with regards to the persisted entity. As a consequence, the framework converts state messages
triggered during this time frame to transitions messages that are then allocated to the REPORTED structure
of the respective MODIFY request.
If a business object is consumed via EML in a non-RAP scenario, and the SAVE is canceled in the
CheckBeforeSave phase, the business object remains in its state and the state messages are preserved.

274 PUBLIC Learn
Example: Managed Business Object with Draft
The following example illustrates the message behavior of state and transition messages:
A validation belonging to the business object instance throws one bound transition message and one state
message. This example is only used for message behavior comparison - generally speaking a validation would
rather throw state messages than transition messages. First two draft instances are created via an EML
CREATE. Then the two entities are committed to the draft table. On the draft table, the validation is triggered
which check for the value of sample_field.
The generic validation implementation follows the usual action implementation pattern. The validation is
triggered on save and checks if the content of the field sample_field is valid:
[implementation] unmanaged|managed|abstract [in class class_name unique];

with draft;
...
define behavior for CDSEntity travel
implementation in class travel_implementation [unique]
...
{
draft determine action Prepare { sampleValidation; }
validation sampleValidation on save { field sample_field; }
}

Within the sampleValidation, there are two messages implemented. The state message is triggered if an
incorrect value was entered in the sample_field and has the severity error, the transition message confirms
that the contained value is correct and has the severity success:
 Expand the following code sample to view the source code of the method sampleValidation.
 Sample Code

METHOD sampleValidation.
//State message is invalidated
APPEND VALUE #( %tky = k-%tky
%state_area = 'sampleValidation' ) TO reported-travel.
[...Code to check value ]
IF value_is_incorrect.
APPEND VALUE #( %tky = key-%tky ) TO failed-travel.
APPEND VALUE #( %tky = key-%tky
%state_area = 'sampleValidation'
%msg = NEW messagewrapper( textid =
messagewrapper=>validation_value_incorrect
travel_id =
ls_travel-travelid
severity =
if_abap_behv_message=>severity-error )
%element-sample_field = if_abap_behv=>mk-on ) TO
reported-travel.
ELSE.
//value is correct
APPEND VALUE #( %tky = key-%tky
%msg = new messagewrapper( textid =
messagewrapper=>validation_value_correct
travel_id = ls_travel-
travelid
severity =
if_abap_behv_message=>severity-success )
%element-sample_field = if_abap_behv=>mk-on ) to
reported-travel.

Learn PUBLIC 275
ENDIF.

ENDMETHOD.
Now, a CREATE is triggered via EML and all validations are triggered during the CHECK_BEFORE_SAVE. In the
first case, an incorrect value is passed for the sample_field and the %tky of the instance is added to the
failed structure and the state message isn't returned with the REPORTED structure of the MOFIFY or COMMIT.
In the second case, the transition message is triggered : Expand the following code sample to view the source
code
 Sample Code

// Trigger two creates via EML
//Returns state message
MODIFY ENTITIES OF /dmo/BusinessObject
ENTITY Bo_Entity
CREATE SET FIELDS WITH
VALUE #( ( %tky = VALUE #( ID = '1234'
%is_draft = if_abap_behv=>mk-on )
%data = VALUE #(
sample_field = 'incorrectValue'
[...fill in other required fields for CREATE]
) )
MAPPED DATA(create_mapped)
REPORTED DATA(create_reported).
//Returns transition message in reported
MODIFY ENTITIES OF /Dmo/BusinessObject
ENTITY Bo_Entity
CREATE SET FIELDS WITH
VALUE #( ( %tky = VALUE # ( ID = '12345'
%is_draft = if_abap_behv=>mk-on )
%data = VALUE #(
sample_field = 'correctValue'
[...fill in other required fields for CREATE]
) )
FAILED DATA(create_failed_2)
MAPPED DATA(create_mapped_2)
REPORTED DATA(create_reported_2).
//Commit created instances to draft table
COMMIT ENTITIES RESPONSE OF /Dmo/BusinessObject
FAILED DATA(COMMIT_FAILED)
REPORTED DATA(COMMIT_REPORTED).
//Execute prepare to trigger state message - state message not contained in
reported
ENTITY Bo_Entity
EXECUTE prepare from VALUE #( ( id = '1234' ) )
FAILED DATA(prepare_failed)
MAPPED DATA(prepare_mapped)
REPORTED DATA(prepare_reported).
//Execute prepare to trigger messages to trigger transition message -
transition message contained in reported
ENTITY Bo_Entity
EXECUTE prepare from VALUE #( ( id = '12345' ) )
FAILED DATA(prepare_failed_2)
MAPPED DATA(prepare_mapped_2)
REPORTED DATA(prepare_reported_2).
// Read on draft travel entity 1234 - returns the state message for this
instance
READ ENTITIES OF /Dmo/BusinessObject
ENTITY Bo_Entity

276 PUBLIC Learn
FIELDS (ID )
WITH VALUE #( (ID = '1234'
%is_draft = if_abap_behv=>mk-on ) )
RESULT DATA(READ_RESULT)
REPORTED DATA(READ_REPORTED_STATEM)
FAILED DATA(READ_FAILED_STATEM).
//Read on draft travel entity 12345 - reported is empty
ENTITY Bo_Entity
FIELDS ( ID )
WITH VALUE #( ( ID = '12345'
RESULT DATA(READ_RESULT_)
REPORTED DATA(READ_REPORTED)
FAILED DATA(READ_FAILED).
//In new session - state message was persisted for draft and is returned with
READ_REPORTED_STATEM

ENTITY Bo_Entity
FIELDS ( ID )
WITH VALUE #( ( ID = '1234'
RESULT DATA(READ_RESULT)
REPORTED DATA(READ_REPORTED_STATEM)
FAILED DATA(READ_FAILED_STATEM).

Result
The two messages are allocated as follows:
• State Message Instance 1234: The persisted state message is allocated in the READ_REPORTED_STATEM
strcuture. Even if a new session is started, the READ on instance 1234 returns the state message until the
value is changed and the PREPARE is triggered again. When the business object is consistent in the draft
instance, the business object instance can be persisted on the data base.
• Transition Message Instance 12345: The transition message is returned with the prepare_reported_2
structure.
2.3.6.4 Messages in OData
2.3.6.4.1 OData V2
This topic describes how messages are modeled in OData V2.
Messages in OData V2
Messages in OData V2 aren’t modeled as entities, but are returned together with the business data.

Learn PUBLIC 277
Successful Request (http response 2xx)
If the request is successful (http response 2xx), messages are contained in the custom response header
sap-message with the following structure:
• Message Code: A machine-readable code

• Message Text: Message text defined in the T100 message class.
• Message Targets: Message targets are defined with the %element component. A message can have one
or multiple targets. If multiple targets are defined, they’re modeled as an array of additionalTargets. In this
case, each item in this array is a string with the same syntax as target.
• Severity: The severity reflects the severity defined in the %msg component with the statement SEVERITY
= IF_ABAP_BEHV_MESSAGE=>SEVERITY-SEVERITY.
• Transition indicator: An optional transition indicator - transition messages originate during transition
from one backend state to another backend state, for example, during execution of an action. Transition
messages are flagged as transition:true and state messages are flagged as transition:false.
• Detail messages: Zero or more details, each with a code, message, severity, target, and optional an
additionalTargets array and a transition indicator.
The content of the SAP-Message header uses the same format (Atom/XML or JSON) as the response body.
The sap-message header is structured as follows:

sap-message: {
"code": "DMO_BUSINESSOBJECT_MESSAGES/002",
"message": "Message text as defined in T100 message class",
"severity": "info",
"transition": true,
"target": "to_Target"
"details": [
]
}

The code is composed of the T100 message class the message originates from and the message identifier. This
message example has the severity info and was defined as transition message that has the target _Target.
Not Successful (Http Response Code 4xx [Client Error]/ 5xx [Server Error] )
If a request isn’t successful, messages are returned with the http body. If the response contains multiple
messages, they’re arranged hierarchically below the first returned message. The first message is described
with the following properties:
• Lang: Language in which the server returned the message (response language is derived from request
language).
• Message: Message text as defined in the respective T100 message class.
The properties within the response are structured as follows:

"error": {
"message": {
"lang": "en",
"value": "Message Text as defined in T100 message class."
}

Details about all messages are contained in the error details block:

"errordetails": [

278 PUBLIC Learn
{
"message": "Message text as defined in T100 message class.",
"propertyref": "",
"severity": "error",
"transition": true,
"target": ""
},
{
"message": "Second text as defined in T100 message class.",
"propertyref": "",
"severity": "success",
"transition": true,
},
]

In this example, both messages have the property transition:true indicating that they were defined as
transition messages (no %state_area defined in the implementation). The code indicates which message class
the message was created in, the numeric value reflects the message identifier defined in the T100 message
class. The first example wasn’t bound to target because of which the property is undefined. The second
message was assigned to the target _Target with the %element component.
2.3.6.4.2 OData V4
This topic describes how messages are modeled in OData V4.
Messages in OData V4
Bound Messages in OData V4 are modeled as a complex type named sap__messages and unbound messages
(messages allocated to %other) are transported with the response header.
Unbound Messages
Unbound messages are transported with the response header property sap__messages that has the following
structure:

• Message Text: Message text defined in the message class.
• Numeric Severity: The numeric severity corresponds to the severity defined in the %msg component
with the statement SEVERITY = IF_ABAP_BEHV_MESSAGE=>SEVERITY-SEVERITY. The mapping is as
follows:
• Success: 1 (Success - no action required)
• Info: 2 (Information - no action required)
• Warning: 3 (Warning - action may be required)
• Error: 4 (Error - action is required )
• Optional longtextUrl: Contains the URL to the longtext, if the message was defined with a longtext in the
message class.

Learn PUBLIC 279
• Optional Target: The target relates a detail message to (a part of) an OData resource, or a related OData
resource. This link required for errors resulting from validation to establish a visual link between the
message and the affected fields. It’s possible to define one or multiple targets.
• Message Targets: Message targets are defined with the %element component. A message can have one
The content of the sap-messages header uses JSON and is encoded according to the rules for HTTP header
fields.

sap-messages: [
{
"message": "Message text as defined in message class",
"numericSeverity": 2,
"longtextUrl": "..."
}
]

The code is composed of the message class the message originates from and the message identifier. This
message example has the severity info (2) and was defined with a longtext and has the target _Target.
Successful Request (http response 2xx): Bound Message

If a request (http response 2xx) is successful, bound messages are contained in an explicitly modeled
collection-valued message container property to avoid header size problems. This complex type has the
following properties:

• Message Target: Message targets are defined with the %element component. A message can have one
• Numeric Severity: The numeric severity corresponds to the severity defined in the %msg component
with the statement SEVERITY = IF_ABAP_BEHV_MESSAGE=>SEVERITY-SEVERITY. The mapping is as
follows:
• Success: 1 (Success - no action required)
• Info: 2 (Information - no action required)
• Warning: 3 (Warning - action may be required)
• Error: 4 (Error - action is required )
• Transition indicator: An optional transition indicator - transition messages originate during transition from
one backend state to another backend state, for example, during the execution of an action. Transition
messages are flagged as transition:true and state messages are flagged as transition:false.
• Optional longtextUrl: Contains the URL to the longtext, if the message was defined with a longtext in the
message class.
The sap__messages is structured as follows:

sap-messages: {
"numericSeverity": "3",

280 PUBLIC Learn
"transition": true,
"longtextUrl": "..."
}

The code is composed of the message class the message originates from and the message identifier. This
message example has the severity warning (3) and was defined as transition message that has the target
_Target. Furthermore, the message was defined with a longtext.
Not Successful (Http Response Code 4xx [Client Error]/ 5xx [Server Error]): Bound
Message
If a request (http response 2xx) Code 4xx [Client Error]/ 5xx [Server Error]), the error response has the
following structure:

• Message Target: Message targets are defined with the %element component. A message can have one
• Details: Zero or more details, each with a code, message, and a target.
The error response is extended with instance annotations, to add a severity to detail messages, or an array of
additionalTargets or the longtext URL:

{
"error": {
"code": "UF0",
"message": " "Message text as defined in message class"",
"target": "",
"@Common.additionalTargets": [],
"@Common.longtextUrl": "...",
"details": [
{
"code": "UF1",
"target": "$_Target",
"@Common.additionalTargets": [],
"@Common.numericSeverity": 4,
"@Common.longtextUrl": "..."
},
...
]
}

}
The code is composed of the message class the message originates from and the message identifier. There
was no target defined for this message. The second example was defined with a longtext, the target _Target,
and the severity 4 (error).
2.4 Query
A query is the connecting interface for read-only access to the database in OData services. It is used for list
reports or analytical reports to process data.

Learn PUBLIC 281
As the non-transactional counterpart of a business object, it consists of a data model, generic and modeled
query capabilities and a runtime. This threefold division is known from the BO concept. However, a query
provides only read access to the database. Its runtime never modifies data, but only executes structured data
retrieval, for example for filtering.
Data Model
The data model for a query is provided with CDS entities. They structure and group database fields to execute
query capabilities on them. The SQL select to retrieve data from the database is generically integrated in the
CDS view.
A query operates on a loose combination of CDS entities. Each entity represents a real-world artifact and
contains the relevant information about it. For example, the information of Flight Connections or Airports is
manifested in CDS entities. The entities are not strictly structured. Their connections, which are modeled with
associations, only provide a functional relationship. In other words, only if data from other entities is needed
for a certain functionality is the association necessary. In contrast to BO compositions, there is no existential
relationship for such associations.
 Note
The RAP runtime engine can only handle associations to or from a custom entity with attribute bindings (A1
= A2 and B1 = B2), but no:
• OR, NOT
• Other operators than ‘=’
• Using something else than CDS elements as operands (e.g. no literals or variables)
 Example
When providing text for ID elements, you need an association to a text providing CDS entity to get the text
from there. The association is only relevant to get information from the text provider. There is no other
structural relationship.
In case of Flight Connections, an association is created to get the information about the long text of the
airport ID in the Airport entity and the full name of the airline in the Carrier entity.
Loose Combination of CDS Entities with Associations for Query Capabilities

282 PUBLIC Learn
Query Capabilities
Query capabilities provide read access to the database and process data to structure them for a certain output.
In contrast to BO behavior, the capabilities do not need to be defined in a separate artifact. Some of the
query capabilities which result from OData query options are generically available and applicable. The query
framework provides the SQL statement to retrieve the structured data for these capabilities, for example in
filtering.
Other capabilities are explicitly modeled by the developer in the source code of the CDS entity. These
capabilities depend on associated CDS entities. The application developer has to define this dependency in
the CDS entity. In this case, CDS annotations indicate which CDS entity or element is involved, as it is the
case for text or value help provisioning. Most of the explicitly modeled capabilities are based on the query of
associated CDS entities.
The following table lists the available query capabilities.
Generally Applicable Capabilities Explicitly Modeled Capabilities
paging search
sorting value help
filtering aggregation
counting text provisioning
column selections
All of these features do not modify data on the database but process data to structure them for a certain
output.
Query Runtime
The runtime of a query is usually managed by the query framework (SADL). The framework takes into account
all query capabilities that are mentioned previously. The application developer does not have to deal with the
construction of the SQL statement to retrieve data from a database table. The data model for the managed
runtime is provided in CDS enity.
There is also the option to handle the query manually. We speak of an unmanaged query in this case. An
unmanaged query can be used, for example, if the data source of a query is not a database table. That
means, the framework cannot provide the SQL statement to access the database. Instead, the application
developer needs to implement every query capability to retrieve the data matching the OData request. For
the unmanaged implementation type, the data model is manifested in a CDS view containing the annotation
ObjectModel.query.implementedBy:. This annotation is used to reference a query implementation class
which implements the data retrieval.
The following diagram exemplifies the runtime of a managed and an unmanaged query. In the shown example,
a custom entity is used to structure the data coming from the referenced query implementation.

Learn PUBLIC 283
Managed and Unmanaged Query in Contrast
For more information about the query runtime, see Query Implementation Types [page 284].
For a detailed runtime diagram, see Query Runtime [page 287].
2.4.1 Query Implementation Types
Managed Query
The default case for a query is the managed implementation type. In this case, the RAP runtime engine
manages the data access to the database. Query capabilities, which result from OData query options
($orderby, $top, $skip … ) are considered, as well as possible authorizations, which are derived from
attached access control. The framework creates an SQL statement for the query that is executed based on
the definition in the CDS source code, the query capabilities and the authorizations. For the runtime of the
managed query, the application developer does not have to implement anything. The application development
tasks are limited to defining the data model and the related access controls during the design time.
The following diagram illustrates the runtime of a query.

284 PUBLIC Learn
Access controls are not illustrated in the preceding diagram. If authorizations are modeled with access
controls, they would automatically be evaluated.
Managed Query - Runtime
 Example
An OData request with the query option $filter reaches an OData service. Once transformed into an
ABAP consumable object, the RAP runtime engine triggers the query to be executed. Then, the query
framework creates the SQL statement to select the required data from the database. In this case, the query
framework extends the SQL statement with a where clause to only select the data sets that match the
filter condition. In this case, access controls are involved, the query framework also evaluates the involved
authorizations.
Unmanaged Query
The unmanaged implementation type for a query is used when the standard SQL push-down by the query
framework is not sufficient or not usable at all.
Use cases for unmanaged queries are

Learn PUBLIC 285
• the data source for an OData request is not a database table, but, for example another OData service,
which is reached by an OData client proxy,
• performance optimization with application specific handling,
• using AMDPs with some query push-down parameters in the SQL script implementation,
• forwarding the call to the analytical engines, or
• enrichment of query result data on property or row level, for example when splitting rows for intermediate
sums or condensing the filter result.
The unmanaged query is protocol agnostic. That means, like managed queries, it can be reused for multiple
scenarios.
The following diagram illustrates the runtime of an unmanaged query.
Unmanaged Query - Runtime
The data model for an unmanaged query can be defined in a CDS custom entity. A custom entity
defines the structure of the data returned by the query. This is done using CDS syntax in a CDS data
definition (DDLS). A CDS custom entity does not have an SQL view to select data from a database.
Instead, the custom entity specifies an ABAP class that implements the query. The entity annotation
@ObjectModel.query.implementedBy: 'ABAP:...' is used to reference the query implementation class
in the data definition of the CDS custom entity. This annotation is evaluated when the unmanaged query is
executed whereby the query implementation class is called to perform the query. For every query request on
the CDS custom entity, the implementation class is reinstantiated. The class instance is never cached.
Since no SQL artifact is generated for custom entities and the query is implemented in ABAP, custom entities
cannot be used in ABAP SQL or in SQL joins in data definitions.
For details about the syntax of a CDS custom entity, see CDS DDL - DEFINE CUSTOM ENTITY (ABAP - Keyword
Documentation)
A CDS custom entity can have parameters, elements and associations. Like in CDS views, it lists the elements
that are used in the data model. For each element, the data type must be specified as it cannot be retrieved
from an underlying database representation.

286 PUBLIC Learn
A custom entity can be an entity in a business object, for example a root, a parent, or a child entity using root
and composition relationships. Custom entities may also be used as targets in the definition of associations
and define associations as a source.
A custom entity cannot be used in ABAP SQL SELECT executions as they to not have a database
representation. In particular, you cannot use elements of an associated custom entity in the element list of
the source CDS entity.
Unmanaged queries are implemented in ABAP classes. The query implementation class implements a
predefined ABAP interface (IF_RAP_QUERY_PROVIDER) to ensure that the required basic OData support is
enabled. The interface has a select method which imports an interface instance for the request data and one
for the response data.
Access control needs to be implemented manually in the query implementation class to ensure that only those
records are returned the user is allowed to access. You cannot use an access control object for a custom entity.
In contrast to the managed query, the application developer has to take care for every supported query option
in the query implementation class, including possible authorizations that are also implemented in the query
implementation class.
 Example
An example on how to use a CDS custom entity and implement an unmanaged query with the interface
IF_RAP_QUERY_PROVIDER in a query implementation class is given in Implementing an Unmanaged
Query [page 917].
 Cloud The use case of an unmanaged query in combination with the client proxy is explained in the
develop scenario Cloud Developing a UI Service with Access to a Remote Service [page 714].
For more information about the interface IF_RAP_QUERY_PROVIDER, see Unmanaged Query API [page
289].
 Note
Custom Entities cannot be projected in CDS projection views.
2.4.1.1 Query Runtime
In RAP, a query is the non-transactional read operation to retrieve data directly from the database.
The following runtime diagram illustrates the main agents' activities when an OData GET (GET
ENTITYSET)request is sent.

Learn PUBLIC 287

• Query Runtime [page 287]


288 PUBLIC Learn
 Note
This diagram reflects the activities for requesting an entity set (GET ENTITYSET). If you request a single
entity with a key, exceptions that are not depicted in the diagram may arise if, for example, the requested
key does not exist.
2.4.2 Query Capabilities
2.4.3 Unmanaged Query API
In contrast to managed queries, in which a framework assumes the implementation tasks to select the
requested data from the data source, the implementation of the unmanaged query must be done by the
application developer. For this, all desired query capabilities (paging, filtering, sorting, counting, … ) must be
implemented in a query implementation class, which is referenced in a CDS view, for example, in a custom
entity.
The following diagram illustrates the runtime of an unmanaged query:

Learn PUBLIC 289
The query request is delegated to the query implementation class which must implement the
IF_RAP_QUERY_PROVIDER. This API is described in following.
Interfaces
These interfaces define methods for the unmanaged query API.
• Interface IF_RAP_QUERY_PROVIDER [page 290]

• Interface IF_RAP_QUERY_REQUEST [page 291]
• Interface IF_RAP_QUERY_FILTER [page 296]
• Interface IF_RAP_QUERY_PAGING [page 300]
• Interface IF_RAP_QUERY_AGGREGATION [page 302]
• Interface IF_RAP_QUERY_RESPONSE [page 303]
For more conceptual information about the unmanaged query, see Query Implementation Types [page 284].
For an example on how to implement an unmanaged query, see Implementing an Unmanaged Query [page
917].
 Cloud For an example on how to implement the unmanaged query contract in a development scenario, see
Cloud Implementing the Query for Service Consumption [page 731].
 Note
 CloudBefore version 1908, IF_A4C_RAP_QUERY_PROVIDER and the related interfaces was the API
to implement an unmanaged query. This API is deprecated as of 1908, but still available in ABAP
Environment. However, it is recommended to use only the new interface IF_RAP_QUERY_PROVIDER.
The interfaces differ in some aspects, for example the handling of filter requests. The new interface offers
some more methods to reflect the query requests in more detail, for example get_aggregation or
get_parameters, which facilitates the implementation.
2.4.3.1 Interface IF_RAP_QUERY_PROVIDER
This interface defines a method that is used for requesting and responding to OData query requests in an
unmanaged query.
Method select
The method select must be implemented in custom entity scenarios. It replaces the SQL-SELECT of a CDS
view to retrieve and return data. The select method must be called by the query implementation class, which
is referenced in the custom entity annotation @ObjectModel.query.implementedBy.
The select imports an interface instance for the request data and one for the response data:

290 PUBLIC Learn
Signature
METHODS select IMPORTING io_request TYPE REF TO if_rap_query_request [page

291]

io_response TYPE REF TO if_rap_query_response [page 303]

RAISING cx_rap_query_provider.
Interface IF_RAP_QUERY_REQUEST [page 291]
Interface IF_RAP_QUERY_RESPONSE [page 303]
Parameter
IO_REQUEST Interface instance for gathering request information that are used as input for the
select implementation. The request interface provides methods for implementing
query options, like filtering or sorting.
IO_RESPONSE Interface instance for the result output of the select implementation.
Exception
CX_RAP_QUERY_PROVIDER Exception that can be raised if there is an error during the query execution.
 Example
See Implementing an Unmanaged Query [page 917].
2.4.3.1.1 Interface IF_RAP_QUERY_REQUEST
The interface defines methods to parametrize a query request in an unmanaged query. It is used to handle
OData query options for data retrieval.
Method get_entity_id
This method returns the CDS entity name of the requested entity set of an OData request in an unmanaged
query.
With this method, you can ensure that the query implementation is only executed if the correct entity for this
query implementation set is called.
Signature
METHODS get_entity_id RETURNING VALUE(rv_entity_id) TYPE string.
rv_entity_id CDS entity name of the requested entity set.

Learn PUBLIC 291
 Example
See Returning Requested Entity in an Unmanaged Query [page 923].
Method is_data_requested
This method returns a boolean value to indicate if data is requested.
 Note
If this method is used to indicate the request for data, the method set_data [page 303] must be called.
Signature
METHODS is_data_requested RETURNING VALUE(rv_is_requested) TYPE abap_bool.
Parameter
rv_is_requested If data needs to be returned, the value is abap_true. If no data needs to

returned, the value is abap_false.
 Example
See Requesting and Setting Data or Count in an Unmanaged Query [page 923].
Method is_total_numb_of_rec_requested
This method returns a boolean value to indicate if the total number of records is requested. The total number
of records is requested by the query option $inlinecount or a $count request.
 Note
If this method indicates the request for the total number of records, the total count needs to be returned by
the method set_total_number_of_records [page 304].
Signature
METHODS is_total_numb_of_rec_requested RETURNING VALUE(rv_is_requested) TYPE

abap_bool.
Parameter
rv_is_requested If the total number of records needs to be returned the value is abap_true. If
the total number of records is not requested the value is abap_false.

292 PUBLIC Learn
 Example
Method get_filter
This method returns a filter object. This filter object is an interface instance of IF_RAP_QUERY_FILTER. If a
filter is requested,its methods return the filter information. Only records that match this filter condition must
be returned or counted.
Signature
METHODS get_filter RETURNING VALUE(ro_filter) TYPE REF TO if_rap_query_filter

[page 296].

Interface IF_RAP_QUERY_FILTER [page 296]
Parameter
RO_FILTER Contains the filter condition.
 Example
See Implementing Filtering in an Unmanaged Query [page 925].
Method get_paging
This method returns an object with paging information. The paging object is an interface instance of
IF_RAP_QUERY_PAGING. It limits the number of records to be returned as response data with offset and
page size.
Signature
METHODS get_paging RETURNING VALUE(ro_paging) TYPE REF TO if_rap_query_paging

[page 300].
Interface IF_RAP_QUERY_PAGING [page 300]
Parameter
RO_PAGING Contains the paging information.
 Example
See Implementing Paging in an Unmanaged Query [page 931].

Learn PUBLIC 293
Method get_sort_elements
This method returns the sort order for the sort elements.
Signature
METHODS get_sort_elements RETURNING VALUE(rt_sort_elements) TYPE

tt_sort_elements.
Parameter
rt_sort_elements Contains the elements to be sorted with their sort direction. It is an ordered
list to define the ranking order, the first element being the primary sort criteria.
The table indicates the names of the sort element and the sort order with a
boolean value in the column descending. The following table illustrates how
the returning value looks like.
tt_sort_elements
ELEMENT_NAME DESCENDING
string abap_bool
 Example
For a filter request like
<service_root_url>/<entity_set>?$orderby=Customer_ID desc

the method get_sort_elements returns the following entries in the returning table:
rt_sort_elements
ELEMENT_NAME DESCENDING
CUSTOMER_ID X
 Example
See Implementing Sorting in an Unmanaged Query [page 933].
Method get_parameters
This method returns a list of the entity parameters and their values.
Signature
METHODS get_parameters RETURNING VALUE(rt_parameters) TYPE tt_parameters.

294 PUBLIC Learn
Parameter
rt_parameters Contains a list of parameters and their given values.
tt_parameters
PARAMETER_NAME VALUE
string string
 Example
<service_root_url>/
<entity_set>(p_start_date=datetime'2016-07-08T12:34',p_end_date=datetime'2019-
07-08T12:34')/Set
the method get_parameters returns the following table:
rt_parameters
PARAMETER_NAME VALUE
P_START_DATE 20160708
P_END_DATE 20190708
 Example
See Using Parameters in an Unmanaged Query [page 927].
Method get_aggregation
This method returns an aggregation object. This object is an interface instance of

IF_RAP_QUERY_AGGREGATION which contains methods to indicate which elements need to be aggregated
or grouped.
Signature
METHODS get_aggregation RETURNING VALUE(ro_aggregation) TYPE REF TO

if_rap_query_aggregation [page 302].
Interface IF_RAP_QUERY_AGGREGATION [page 302]
Parameter
ro_aggregation Interface instance for information about aggregation and grouping.
 Example
See Implementing Aggregations in an Unmanaged Query [page 936].

Learn PUBLIC 295
Method get_search_expression
This method returns the requested search string.
Signature
METHODS get_search_expression RETURNING VALUE(rv_search_expression) TYPE

string.
Parameter
rv_search_expression Contains a free search expression with unspecified format.
 Example
See Implementing Search in an Unmanaged Query [page 929].
Method get_requested_elements
This method returns the requested elements, which need to be given to the response.
Signature
METHODS get_requested_elements RETURNING VALUE(rt_requested_elements) TYPE

tt_requested_elements.
rt_requested_elements Contains a list of the requested elements.
 Example
See Considering Requested Elements in an Unmanaged Query [page 935].
2.4.3.1.1.1 Interface IF_RAP_QUERY_FILTER
This interface is a filter criteria provider for the unmanaged query. The methods provide different
representations for the filter criteria.
Method get_as_ranges
This method returns the filter as a list of simultaneously applicable range tables. The table is initial if no filter is
supplied.

296 PUBLIC Learn
Signature
METHODS get_as_ranges RETURNING VALUE(rt_ranges) TYPE tt_name_range_pairs

RAISING cx_rap_query_filter_no_range.

Parameter
rt_ranges Contains a list of filter conditions in name-range-table pairs. That means, every
requested filter element is related to a ranges table that indicates the filter condi-
tions. The returning value is in a ranges-table-compatible format. The following
table illustrates the list of name and ranges table.
The columns of the ranges tables have the semantics of selection table criteria.
They are defined as follows:
• SIGN: Contains the values I for inclusive or E for exclusive consideration of

the defined range
• OPTION: Contains the operator values. Valid operators are EQ, NE, GE, GT,
LE, LT, CP, and NP, if the column high is initial, and BT, NB, if column high is
not initial.
• LOW: Contains the comparison value or the lower interval limitation.
• HIGH: Contains the upper interval limitation.
tt_name_range_pairs
NAME RANGE
string tt_range_option
OP-
SIGN TION LOW HIGH
c(1) c(2) string string
 Example
<service_root_url>/<entity_set>?$filter= Agency_ID eq '070031'

and (Begin_Date ge datetime 2019-01-01T00
and Begin_Date le datetime 2019-12-31T00)

the method get_as_ranges returns the following entries in the range table:
tt_name_range_pairs
NAME RANGE
AGENCY_ID tt_range_option
SIGN OPTION LOW HIGH
I EQ 070031

Learn PUBLIC 297
NAME RANGE
Begin_Date tt_range_option
SIGN OPTION LOW HIGH
I BT 20190101 20191231
Exception
cx_rap_query_filter_no_ran This exception is thrown if the filter cannot be converted into a ranges table.
ge
In this case the developer can try to use the method get_as_tree or
get_as_sql_string as a fall back or throw an error.
 Example
Method get_as_sql_string
This method returns the filter as an SQL string. The string is initial if no filter is supplied.
Signature
METHODS get_as_sql_string RETURNING VALUE(rv_string) TYPE string.
Parameter
rv_string Contains the filter conditions as an ABAP SQL string. The variable can be used
directly in the WHERE clause of an ABAP SQL statement to select data.
 Example
<service_root_url>/<entity_set>?$filter= Agency_ID eq '070031'

and (Begin_Date ge datetime 2019-01-01T00
and Begin_Date le datetime 2019-12-31T00)

the method get_as_sql_string returns BEGIN_DATE BETWEEN '20190101' AND '20191231' AND
AGENCY_ID = '070031'. This string has the correct syntax to be used in an SQL statement.
The SQL filter can also be applied on data that have been prefiltered using e.g. a ranges table.

298 PUBLIC Learn
Method get_as_tree
This method returns a reference to an expression tree representing the filter conditions, which can be easily
queried and manipulated due to the semantic tree structure. Every node in the filter tree has a type indicating
the content of the node. The reference to the filter tree is unbound in case no filter is supplied.
Signature
METHODS get_as_tree RETURNING VALUE(ro_tree) TYPE REF TO

if_rap_query_filter_tree.
Parameter ro_tree
The parameter ro_tree references the interface if_rap_query_filter_tree. Use the method
get_root_node of this interface to get the root node of the expression tree. From there you can parse through
the filter tree using the following methods of the interface if_rap_query_filter_tree_node:
• get_children: Get the child nodes of the current node in the order of the user input.
• get_type: Get the type of the current node.
• get_value: For nodes of the type identifier this method returns a reference to a string containing the
identifier, i.e. the field involved in the field condition. For nodes of the type value this method returns a
reference to the raw value. For all other node types this method must not be called. If it is called regardless
an uncatchable exception will be thrown.
 Example
AGENCY_ID = '070004' AND ( CUSTOMER_ID = '000001' OR CUSTOMER_ID = '000002'

OR CUSTOMER_ID = '000003' ) AND OVERALL_STATUS <> 'X'

Learn PUBLIC 299
the method get_as_tree returns a filter tree with the following semantics:
The structure of the filter tree as well as the order of the nodes within this structure are not guaranteed for
the given condition and can change depending on the modifications done to the filter condition.
Consuming code must be prepared to deal with an extension of the available node types as further node
types might be added in the future.
 Example
2.4.3.1.1.2 Interface IF_RAP_QUERY_PAGING
This interface provides the information for paging requests. The methods provide the offset and the page size
for one OData request.
Method get_offset
This method indicates the number of records to drop from the list of data records in the data source. In an
OData query request, the offset is requested by the query option $skip.

300 PUBLIC Learn
Signature
METHODS get_offset RETURNING VALUE(rv_offset) TYPE int8.
Parameter
rv_offset Contains the number of records that are dropped from the result list.
 Example
If rv_offset is 2, the first record in the result list is the data record on
position 3.
 Example
Method get_page_size
This method indicates the maximum number of records that are to be returned. In an OData query request, the
page size is requested by the query option $top.
Signature
METHODS get_page_size RETURNING VALUE(rv_page_size) TYPE int8.
Parameter
rv_page_size Contains the number of records that are returned.
 Note
rv_page_size if_rap_query_pagin=>page_size_unlimited
if no limit is requested.
 Example

Learn PUBLIC 301
2.4.3.1.1.3 Interface IF_RAP_QUERY_AGGREGATION
This interface provides methods to receive information about the requested aggregation and grouping
requests.
Method get_aggregated_elements
This method returns the requested aggregated elements with their aggregation method and the output
elements in a string table. These values can then be extracted and used in the query implementation.
Signature
METHODS get_aggregated_elements RETURNING VALUE(rt_aggregated_elements) TYPE

tt_aggregation_elements.
Parameter
rt_aggregated_elements Contains the aggregation method, the input element, and the output element.
The constants for the available predefined aggregation methods are:
• COUNT: for returning the number of values of the input element in the
output element.
The constant co_count_all_identifier as value for
input_element denotes the counting of all rows.
• COUNT_DISTINCT: for returning the number of unique values of the input
element in the output element.
• SUM: for returning the sum of the input element in the output element.
• MIN: for returning the minimum of the input element in the output element.
• MAX: for returning the maximum of the input element in the output element.
• AVG: for returning the average of the input element in the output element.
The input element is the element whose values are aggregated and the output
element is the element, which contains the aggregated value. The output element
can be the same as the input element.
 Example
rt_aggregated_elements
aggregation_method input_element result_element
SUM BOOKING_FEE TOTAL_BOOKING_FEE
Signature
 Example

302 PUBLIC Learn
Method get_grouped_elements
This method returns the requested elements by which the result is to be grouped.
Signature
METHODS get_grouped_elements RETURNING VALUE(rt_grouped_elements) TYPE

tt_grouped_elements.
Parameter
rt_grouped_elements Returns an ordered list of the elements by which the result is to be grouped. The
elements are listed in the order of grouping priority.
 Example
2.4.3.1.2 Interface IF_RAP_QUERY_RESPONSE
This interface provides methods to return data and the count for the query response. The results of the
methods of interface IF_RAP_QUERY_REQUEST are integrated in the response.
Method set_data
This method provides the response for the method if_rap_query_request~is_data_requested. If this
method is called, the table of result data must be provided (empty if there is no result data).
Signature
METHODS set_data IMPORTING it_data TYPE STANDARD TABLE

RAISING cx_rap_query_response_set_twic.
Parameter
it_data Contains a table of the data records for the query response.
Use the type of your custom entity for the response to be compatible with the
request.
Exception
cx_rap_query_response_set_ Exception is raised when the result table is set more than once.
twic

Learn PUBLIC 303
 Example
Method set_total_number_of_records
This method provides the response for the method

if_rap_query_request~is_total_numb_of_rec_requested. If this method is called, the count needs
to be set for the response.
Signature
METHODS set_total_number_of_records IMPORTING iv_total_number_of_records TYPE

int8

RAISING cx_rap_query_response_set_twic.
Parameter
iv_total_number_of_records Contains the total number of records. If no records match the given request
criteria, the value zero must be passed.
Exception
cx_rap_query_response_set_ Exception is raised when the number of records is set more than once.
twic
 Example

304 PUBLIC Learn
3 Start
This Start section provides you with the fundamental basics of development with the ABAP RESTful
Programing Model.
For demonstration and learning purposes, we provide the ABAP Flight Reference Scenario that simulates an
application used by a travel agency for booking flights. The first thing to do is therefore to import the ABAP
Flight Reference Scenario in your ADT to get sample data: Downloading the ABAP Flight Reference Scenario
[page 314]. You can find more details about the data model of the reference scenario in ABAP Flight Reference
Scenario [page 309].
 Restriction
Currently, it is not possible to download the ABAP Flight Reference Scenario into an S/4 HANA Cloud
System. However, all code examples are also provided in this documentation for reference.
The getting started guide helps you to create a complete application based on the existing data model from
the ABAP Flight Reference Scenario with the most basic features: Developing an OData Service for Simple List
Reporting [page 315]. Alternatively, you can use the Generate ABAP Repository Objects Wizard to create all
RAP-service-related development objects on the basis of a database table to get started: Generating a RAP
Business Service with the Generate ABAP Repository Objects Wizard [page 339].
3.1 Prerequisites
Development Environment
• You have installed ABAP Development Tools (ADT). Test

SAP recommends to use the latest version of the client installation. The ADT download is available on the
update site https://tools.hana.ondemand.com/.
• You have created an ABAP project to establish a connection between your ABAP back-end system and the
Eclipse-based IDE. For more information, see .
 Home Application Server ABAP
You are working on Application Server ABAP 7.55 SP00 or higher.
SAP Gateway
SAP Gateway is properly configured in your ABAP system for activating and testing the resulting OData service.
For more information, see SAP Gateway Foundation.

Start PUBLIC 305
Authorizations
To reproduce the steps described in this guide, the user on Application Server ABAP 7.55 SP00 with the
following roles assigned is required:
• SAP_BC_DWB_ABAPDEVELOPER (ABAP Developer)

• SAP_BC_DWB_WBDISPLAY (Display User)
 Note
For behavior definitions and service bindings, you must add authorizations manually. See SAP Note
2827843 .
For SAP Gateway service development and consumption, roles of the following templates are needed:
• /IWFND/RT_DEVELOPER (SAP Gateway service development)

• /IWFND/RT_ADMIN (for publishing services)
• /IWFND/RT_GW_USER (for consuming services)
For more information, see User, Developer and Administrator Roles
Knowledge
Basic knowledge of
• ABAP Core Data Services (CDS)

• ABAP Objects.
3.1.1 Naming Conventions for Development Objects
Naming conventions facilitate the development. An addition to the name of development objects conveys
standardized meaning and generates consistency in your development.
General Rules
 Remember
The general guideline for development objects is the following: [/<namespace>/]

[<prefix>]_<object_name>_[<suffix>].
• Use your own namespace that is reserved for your organization.
 Note
Consider that the namespace /DMO/ is reserved for demo purposes. Do not use this namespace in
your productive development.

306 PUBLIC Start
• A prefix is used for cases when there are generically different types of one development object. Then, this
prefix states the semantic difference that cannot be conveyed through the object type.
For example, a service binding can expose an OData service for UI purposes and as a Web API. That is
why, for service bindings we introduce the prefixes UI_ and API_ to differentiate the semantics of service
bindings.
• A suffix is used for additional differentiation between different types of development objects. It helps to
recognize more subtle or secondary differences in development objects.
For example, a UI service can be bound against the OData protocol OData, version 2 and OData,
version 4. This difference can also be manifested by suffixing the name with _O2 or _O4.
 Note
In the ABAP Flight Reference Scenario we use another suffixed character (_R, _M, _D, _U, _C). This
character identifies the development object to belong to one specific development guide (read-only,
managed, ddraft, unmanaged, service consumption).
The following list provides an overview of the prefixing and suffixing guidelines on naming specific development
objects.
ABAP Dictionary Objects
Database Tables
Use a prefix for database tables in scenarios, in which multiple technical representations of the same semantic
data is necessary, for example in draft scenarios.
Use the prefix
• A_ for the persistent database table, the table that contains the active data.
• D_ for the draft database table.
Example: /DMO/A_TRAVEL_D
CDS Objects
CDS Entity
Use the prefix
• I_ for an interface view.

• R_ for the base CDS views
• C_ for a projection view. The character C represents the consumption layer. If there are multiple projections
of one CDS entity, the object name should semantically represent the projection role.
Example: /DMO/I_Travel_U, /DMO/C_Travel_Processor_M
Behavior Definition
A behavior definition has always the same name as the root entity of the business object.

Start PUBLIC 307
Example: /DMO/I_Travel_U, /DMO/C_Travel_M
Metadata Extension
A metadata extension has the same name as the CDS entity it relates to. If you use more than one metadata
extension for one CDS entity, you can add a numbered suffix.
Example: /DMO/C_TRAVEL_U, /DMO/C_BOOKING_U_M2
Business Services
Service Definition
Since a service definition- as a part of a business service - does not have different types or different
specifications, there is (in general) no need for a prefix or suffix to differentiate meaning.
Example: /DMO/TRAVEL_U
However, in use cases where no reuse of the same service definition is planned for UI and API services, the
prefix may follow the rules of the service binding.
Example: /DMO/UI_TRAVEL_U
Service Binding
Use the prefix
• UI_ if the service is exposed as a UI service.

• API_ if the service is exposed as Web API.
Use the suffix
• _O2 if the service is bound to OData protocol version 2.

• _O4 if the service is bound to OData protocol version 4.
Example: /DMO/UI_TRAVEL_U_O2
Source Code Objects
Behavior Pool
Use the prefix
• BP_ for an ABAP class that implements the behavior of a business object.
Example: /DMO/BP_TRAVEL_U
Handler and Saver Classes

Use the prefix
• LHC_ for a local handler class.

• LSC_ for a local saver class.

308 PUBLIC Start
Depending on the modularization of your behavior implementation, you can provide the semantics of the
coding in the name of the classes.
Example: LHC_TRAVEL_CREATE
Example: LHC_BOOKING_CUD
3.1.2 ABAP Flight Reference Scenario
The ABAP Flight Reference Scenario helps you to get started with development in the context of the ABAP
RESTful Programming Model. It contains demo content that you can play around with and use to build your
own sample applications..
The reference scenario is based on multiple database tables which you can use to build your application. These
tables are also used in the development guides in the Develop [page 344] section.
• #unique_226/unique_226_Connect_42_subsection-im1 [page 310]


Start PUBLIC 309
Hover over each element for a description of the related database table. Click the element to view the database
table fields.
/DMO/AGENCY
The database table /DMO/AGENCY stores general data about the travel agency that operates travels for
customers.
The database table has the following fields:
• agency_id (key)
• name
• street
• postal_code
• city
• country_code
• phone_number
• email_address
• web_address
The key field is the unique ID for the travel.
/DMO/TRAVEL
The database table /DMO/TRAVEL stores general travel data. In addition, it includes administrative data about
the creation and changing of instances.
• travel_id (key)
• agency_id
• customer_id
• begin_date
• end_date
• booking_fee
• total_price
• currency_code
• description
• status
• createdby

310 PUBLIC Start
• createdat
• lastchangedby
• lastchangedat
The key field is the unique ID for the travel.
/DMO/CUSTOMER
The database table /DMO/CUSTOMER stores general data about customers. In addition, it stores
administrative data about the creation and changing of instances.
• customer_id
• first_name
• last_name
• title
• street
• postal_code
• city
• country_code
• phone_number
• email_address
• createdat
• createdby
• lastchangedby
• lastchangedat
The key field is the unique ID for the customer.
/DMO/BOOKING
The database table /DMO/BOOKING stores data about a booked flight for a certain travel instance. Apart from
general flight and booking data, it includes the customer ID for whom the flight is booked as well as the travel ID
to which the booking belongs.
• travel_id (key)
• booking_id (key)
• booking_date
• customer_id
• carrier_id
• connection_id
• flight_date
• flight_price
• currency_code
The key fields are the travel ID for the travel it belongs to and the booking ID, which are unique in combination.
/DMO/FLIGHT
The database table /DMO/FLIGHT stores general data about flights.

Start PUBLIC 311
• carrier_id (key)
• connection_id (key)
• flight_date (key)
• price
• currency_code
• plane_type_id
• seats_max
• seats_occupied
The key fields are the IDs for carrier and connection as well as the flight date, which makes the flight unique.
/DMO/BOOK_SUPPL
The database table /DMO/BOOK_SUPPL stores data of booking supplements that can be booked for flights,
for example meals or insurances.
• travel_id (key)
• booking_id (key)
• booking_supplement_id (key)
• supplement_id
• price
• currency_code
The key fields are the travel ID, the booking ID and the booking supplement ID, which are unique in
combination.
/DMO/CONNECTION
The database table /DMO/CONNECTION stores general data about flight connections.
• connection_id (key)
• airport_from_id
• airport_to_id
• departure_time
• arrival_time
• distance
• distance_unit
The key fields are the IDs of carrier and connection, which are unique in combination.
/DMO/CARRIER
The database table /DMO/CARRIER stores data about flight carriers.

312 PUBLIC Start
• name
• currency_code
The key field is the unique ID of a carrier.
/DMO/AIRPORT
The database table /DMO/AIRPORT stores data about airports.
• airport_id (key)
• name
• city
• country
The key field is the unique airport ID.
/DMO/SUPPLEMENT
The database table /DMO/SUPPLEMENT stores general data about the supplement, which can be booked for
flights.
• supplement_id (key)
• price
• currency_code
The key field is the unique ID for the supplement.
/DMO/SUPPL_TEXT
The database table /DMO/SUPPL_TEXT stores the readable texts for the supplements in different languages.
• supplement_id (key)
• language_code (key)
• description
The key fields are the IDs of the supplement and the language, which are unique in combination.
Downloading the ABAP Flight Reference Scenario from GitHub
You can download the complete ABAP Flight Reference Scenario for the ABAP RESTful Application
Programming Model from GitHub. https://github.com/SAP-samples/abap-platform-refscen-flight
 Restriction
The steps to import all relevant development objects are described in the README.md files of the respective
branches..

Start PUBLIC 313
 Remember
The namespace /DMO/ is reserved for the demo content. Apart from the downloaded ABAP Flight Scenario,
do not use the namespace /DMO/ and do not create any development objects in the downloaded packages.
You can access the development objects in /DMO/ from your own namespace.
3.2 Downloading the ABAP Flight Reference Scenario
The ABAP Flight Scenario contains demo content that you can import into your development environment.
The ABAP Flight Reference Scenario helps you to get started with development in the context of the ABAP
RESTful Application Programming Model. It contains demo content that you can play around with and use to
build your own sample applications.
Sample Data
First of all, the reference scenario contains data. You can use database tables that are filled with travel data
including master data items, such as customer, flights, airports, or booking supplements. The structure of the
complete data model allows you to build simple but also more complex services. In this way, it is easy to follow
the steps in the development guides while building your own application based on the same database tables as
in the given examples.
For an overview of the available database tables, see ABAP Flight Reference Scenario [page 309]. They are
available in the package /DMO/FLIGHT_LEGACY. This package also includes a data generator with which you
can fill the database tables.
Sample Services
The development guides for the ABAP RESTful Application Programming model are based on the sample data
from the ABAP Flight Reference Scenario. That means that you can compare the documentation with the
productive code that was used to build the documentation scenario. In addition, the ABAP Flight Reference
Scenario also includes a demo package with the development objects that are created during the course of
the development guides. That means, the whole demo scenario can be downloaded and tested. You obtain
full demo services with code built by following conventions and best practices and you can use and reuse the
delivered objects for your development.
The following demo scenarios are available for you:
• Developing Read-Only List Reporting Apps [page 350] in the package /DMO/FLIGHT_READONLY
• Developing Unmanaged Transactional Apps [page 481] in the package /DMO/FLIGHT_UNMANAGED
• Developing Managed Transactional Apps [page 371] in the package /DMO/FLIGHT_MANAGED
• Developing Transactional Apps with Draft Capabilities [page 578] in the package /DMO/FLIGHT_DRAFT
• Developing Transactional Apps with Multi-Inline-Edit Capabilities [page 693] in the package /DMO/
FLIGHT_REUSE_SUPPLEMENT
Legacy Coding
The reference scenario also includes legacy coding. This legacy coding is based on function modules and
exemplifies legacy applications that you can include in your new ABAP code. Above all, the legacy coding
is relevant for the development guide, that explains how to build a new service on the basis of an existing

314 PUBLIC Start
application. It illustrates how you build an application with the unmanaged implementation type. The legacy
coding that is used in this scenario is available in the package /DMO/FLIGHT_LEGACY.
Downloading the ABAP Flight Reference Scenario from GitHub
You can download the complete ABAP Flight Reference Scenario for the ABAP RESTful Application
Programming Model from GitHub. https://github.com/SAP-samples/abap-platform-refscen-flight
 Restriction
The steps to import all relevant development objects are described in the README.md files of the respective
branches..
 Remember
3.3 Developing an OData Service for Simple List Reporting
The following guide describes the basic development tasks to create a simple list reporting app based on a
query.
Introduction
An OData service makes it possible to create and consume queryable and interoperable RESTful APIs. A SAP
Fiori Elements application consumes OData services like this, but it also possible for other Web clients to make
use of an OData service that is created with the ABAP RESTful Application Programming Model .
This programming model provides a framework that facilitates your application development. All included
technologies, such as Core Data (CDS) or business services, are usable and accessible with ABAP
Development Tools (ADT), providing easy access to the necessary infrastructure.
The following guide starts from a data model assuming that database tables already exist. It uses the
ABAP Flight Reference Scenario (in short Flight Scenario), which provides example data comprising travel
information with flight data. For a detailed description of the database tables that are used in this scenario,
refer to ABAP Flight Reference Scenario [page 309]
You are guided step-by-step through the new application model in three consecutive building blocks:

Start PUBLIC 315

• Defining the Data Model with CDS [page 317]

• Creating an OData Service [page 323]
• Designing the User Interface for a Fiori Elements App [page 332]
You start by implementing a CDS view as a new data model layer using a data source that is already provided.
You also use basic CDS annotations to manifest semantics for the data model. The next step is to create an
OData service by defining and binding a service based on the corresponding CDS view. As soon as the OData
service is published in the local system repository, it is ready to be consumed using an OData client, such
as a SAP Fiori app. Finally, you learn how to use UI annotations as a UI technology independent semantic
description of the user interface layout.
The result of this Getting Started guide is a consumable OData Service, which can be easily used to set
up a Fiori Elements travel booking app, from which you can derive information about flight connections.
Navigation properties are added to this application to receive more information about bookings, customers,
and agencies in the other scenarios in the Develop [page 344] section. These other development guides also
cover extended read-only and transactional features, whereas the Getting Started guide only deals with the
most basic read-only features for setting up an OData Service. The scenarios in the Develop section assume
that you understood the steps that are described in the following guide.
 Note
Via ABAPGit you can import the service including the related development objects into your development
environment for comparison and reuse. You find the service in the package /DMO/FLIGHT_READONLY. The
suffix for development objects in this development guide is _R. Be aware that the development objects
might contain more than explained in the Getting Started guide. This is because the Getting Started
scenario is enhanced in the first development guide Developing Read-Only List Reporting Apps [page 350]
which uses this same demo objects.

316 PUBLIC Start
For information about downloading the ABAP Flight Reference Scenario, see Downloading the ABAP Flight
Reference Scenario [page 314].
The following sections serve as an introductory guide for the development of an OData service based on the
ABAP RESTful Application Programming Model . It forms the basic building block for more elaborate scenarios
with extended read-only features or transactional processing.
Prerequisites
Developing the scenario that is described in the subsequent chapters requires the following:
• You fulfill the requirements described in Prerequisites [page 305].

• You have installed ABAP Development Tools (ADT).
• To recreate the demo scenario, the ABAP Flight Reference Scenario must be available in your ABAP system.
You can download the complete reference scenario from GitHub: Downloading the ABAP Flight Reference
 Restriction
Objectives
By the end of this Getting Started section, you will be able to:
• Create a data definition and define a CDS view

• Implement an ABAP CDS view based on an existing database table
• Define an OData service and expose a CDS view for this service
• Bind the OData service against a protocol and publish it locally
• Use semantics annotations in CDS
• Understand some basic UI annotations in CDS
3.3.1 Defining the Data Model with CDS
The data model for an OData service must be defined in CDS.
This introductory programming guide uses example data from the Flight Reference Scenario. The Getting
Started scenario uses the database table /dmo/connection. It provides information about airline and
connection numbers, flight times, and data related to planes.

Start PUBLIC 317
In the CDS layer we use and manipulate data that is persisted in the database. To make data available in
the ABAP application server, CDS views use SQL queries to project persisted data to the ABAP layer. This is
necessary to create an OData service to make the data ready to be consumed. More information about CDS: .
To define a data model based on the ABAP CDS view concept, you first need to create a data definition as the
relevant ABAP Repository object using a wizard in ABAP Development Tools.
Task 1: Creating a CDS View Entity for the Connection Entity [page 318]
In the second step, you implement an elementary CDS view from scratch by defining a simple query for flights
based on a single data source from the ABAP Flight Reference Scenario.
Task 2: Implementing the CDS View as a Data Model [page 319]
In the final task of this section, you have the option of using the test environment to verify the output (a results
set) of the CDS view you have just implemented.
Task 3: Verifying the Results Set in the Data Preview Tool [page 322]
3.3.1.1 Creating a CDS View Entity for the Connection

Entity
Use the data definition wizard to create the relevant development object for a CDS view.
Context
For our simple read-only scenario, we want to define data that is exposed by an OData service to make it
available for an OData client. For this purpose, you create a development object to define an ABAP CDS entity
(for example, a CDS view). The data definition provides you with the appropriate development object for the
CDS view, which is included in ABAP development tools and directly accesses the standard ABAP functions.
To create a data definition for the CDS view, use the wizard for data definition as described in
Results
In the selected package, the ABAP back-end system creates an inactive version of a data definition and stores
it in the ABAP Repository. As a result, the data definition editor is opened. The generated source code already
provides you with the necessary view annotations and adds a placeholder for the name of the data source
for query definition. The name for the actual CDS view is predefined on the basis of the name for the data
definition, but can be changed in the data definition editor.

318 PUBLIC Start
The generated template code in the data definition editor
Next Steps
Now that you have created a data definition, you can implement the CDS view as a data model for your OData
service.
3.3.1.2 Implementing the CDS View as a Data Model
Use a predefined database table as the data source for a CDS view.
Prerequisites
• You have created the data definition artifact in ABAP Development Tools.
• The database table /dmo/connection is available for you.
Context
In this step, you implement an interface view as a new data model using a predefined data source.
Procedure
1. If you have not yet already done so, open the new data definition in the editor.
2. Specify the name of the CDS view: /DMO/I_Connection_R. The data definition editor already provides a
suggestion for the name using the name that you specified for the data definition in the creation wizard.
However, these names do not have to be the same. You can overwrite it in the define statement.
3. In the SELECT statement, enter the predefined database table /dmo/connection as a data source and
define an optional alias name for the data source.

Start PUBLIC 319
An alias is useful especially when you use multiple data sources or whenever the name of the data source is
not descriptive or too long.
... select from /dmo/connection as Connection{
4. Add the fields of /dmo/connection to the SELECT list and assign alias names to each item field as follows:
{

Connection.carrier_id as AirlineID,
Connection.connection_id as ConnectionID,
Connection.airport_from_id as DepartureAirport,
Connection.airport_to_id as DestinationAirport,
Connection.departure_time as DepartureTime,
Connection.arrival_time as ArrivalTime,
Connection.distance as Distance,
Connection.distance_unit as DistanceUnit

}
 Tip
Whenever you insert table fields or view elements in the SELECT list, you can make use of the content
assist function in the data definition editor ( CTRL + SPACE ).
Inserting fields using semantic auto-completion

5. To document the key semantics of the new data model, define the AirlineID and ConnectionID
elements as KEY elements in the current CDS view:
key connection.carrier_id as AirlineID,

key connection.connection_id as ConnectionID,
6. Change authorization check to "NOT_REQUIRED".
7. Click the activation button or use the shortcut Ctrl + F3 to activate the data definition.
To check the syntax before activation, click or use the shortcut Ctrl + F2 .
Results
The resulting source code for the CDS view is the following:

@EndUserText.label: 'Read-Only E2E: Data Model Connection'
define view entity /DMO/I_Connection_R
as select from /dmo/connection as Connection
{
key Connection.carrier_id as AirlineID,
key Connection.connection_id as ConnectionID,

320 PUBLIC Start

}
The source code above is used to define a quite simple CDS view named /DMO/I_Connection_R. This view is
implemented using a query that performs a SELECT statement, where the database table /dmo/connection
is used as the data source. The select list includes a set of fields that are relevant for the scenario. The KEY
elements in the selection list are used to define the key field semantics of the CDS view.
When the data definition source is activated, the entity of the CDS view /DMO/I_Connection_R is created in
ABAP Dictionary.
Next Steps
Mark the element Distance as semantically related to the element DistanceUnit.
3.3.1.2.1 Relating Semantically Dependent Elements
Use the @Semantics annotation to relate the quantity element to its unit of measure element.
Context
The CDS view /DMO/I_Connection_R that you created contains elements that are heavily dependent on each
other semantically, namely Distance and DistanceUnit. In CDS, you can use semantic annotations to
standardize semantics that have an impact on the consumer side for these elements. In general, elements that
need to be marked as having semantic content to guarantee that they are handled correctly are elements that
contain the following:
• Amounts of money
These elements need a reference to the currency related to this element.
• Amounts of measures
These elements need a reference to the unit of measure related to this element.
If you create annotations that define a link to the unit for the amounts, the amounts and their units are always
handled as being dependent on each other in the OData service. On UIs in particular, amounts are displayed
with the correct decimals with regard to their unit.
In the CDS view /DMO/I_Connection_R, you therefore need to proceed as described in the following to always
display the distance together with the distance unit.

Start PUBLIC 321
Procedure
1. Open the CDS view /DMO/I_Connection_R.

2. Define the relationship between amount and unit of measure with the annotation
@Semantics.quantity.unitOfMeasure: '<ElementRef> on Distance and reference the element
DistanceUnit.
@Semantics.quantity.unitOfMeasure: 'DistanceUnit'


3. Activate the CDS view.
Results
If you expose the CDS view to an OData service, the elements are always handled as being semantically related
to each other. This means that they are given the OData annotation sap:unit and sap:semantics in the
OData metadata document. On UIs in particular, the elements are always displayed as being attached to each
other.
Related Information
Semantics Annotations [page 1247]
3.3.1.3 Verifying the Results Set in the Data Preview Tool
Use the data preview tool to check the elements in the CDS view.
Prerequisites
The data definition has correct syntax and has been activated.
Context
You have created a data definition and implemented a CDS view with data from the database table /dmo/
connection. Now you have the option of launching the test environment (in the data preview tool), which
enables you to verify that the persisted data from the database is now displayed in the CDS view.

322 PUBLIC Start
Procedure
In the data definition editor, position the cursor somewhere in the CDS source code. Open the context menu
and choose Open With Data Preview or use the shortcut F8 .
Results
The CDS view does not require any parameters, which means the data preview displays the results set of the
data selection query directly.
Results sets in the data preview tool
 Note
You can sort the entries by element by clicking the column header.
3.3.2 Creating an OData Service
Business service artifacts enable the publishing of an OData service using ABAP Development Tools.
In the previous step, you defined a data model based on the persisted data source /dmo/connection in the
data definition /DMO/I_Connection_R. You can now use this data model and expose it for an OData service.
The OData service makes it possible for UI technologies to query data and consume it. The following steps are
necessary to include the CDS view in an OData service.
To define a service, you first need to create a service definition as the relevant ABAP Repository object using a
wizard.

Start PUBLIC 323
Task 1: Creating a Service Definition for the Read-Only Service [page 324]
The next step is to define the scope of the OData service by exposing the relevant CDS views (including their
metadata and their behavior).
Task 2: Exposing a CDS View for an OData Service [page 325]
To define the type and category of the OData service, you need to create a service binding as the relevant ABAP
Repository object. There is also a wizard available for this.
Task 3: Creating a Service Binding [page 326]
In the next step, you use the form-based editor of the service binding to publish the service locally.
Task 4: Publishing the OData Service Locally [page 327]
You have the option of checking the resulting OData service by viewing its metadata. The service binding offers
a simple solution for this.
Task 5: Verifying the OData Metadata [page 328]
You can also take a look at how the UI of a Fiori Elements of the OData service looks like with the preview tool of
Task 6: Previewing the Resulting UI Service [page 330]
3.3.2.1 Creating a Service Definition for the Read-Only

Service
Use the service definition wizard to create the relevant development object that defines the scope of the OData
service
Context
The service definition is a projection of the models and related behavior that you want to expose. In a service
definition, you define the OData service to determine which CDS entities are part of the service. This service
is then exposed either as a UI service or a Web API by a service binding artifact. A service definition can be
integrated in various protocols without any reimplementation.
To create a Service Definition use the wizard to create the relevant development object that defines the scope
of the OData service as described in .
Results
The ABAP back-end system creates an inactive version of a service definition and stores it in the ABAP
Repository.
In the Project Explorer, the new service definition is added to the Business Services folder of the corresponding
package node. As a result, the service definition editor is opened.

324 PUBLIC Start
Next Steps
Now that you have created a service definition, you can choose one or more CDS entities to be exposed in the
service.
3.3.2.2 Exposing a CDS View for an OData Service
Assign the scope of the OData service.
Prerequisites
You have created the service definition artifact in ABAP Development Tools.
Context
In the service definition editor, you determine the CDS entities that you want to expose in an OData service.
Procedure
1. If you have not yet already done so, open the new service definition in the editor.
The name of the service is already specified in accordance with the name you gave in the service definition
wizard. It cannot be changed to a different name.
2. Specify the name of each CDS entity that you want to expose for the service. For the getting started
read-only scenario, there is only one CDS view to be exposed: /DMO/I_Connection_R
3. Optionally, you can assign an alias for the CDS view.
An alias is useful, especially when you use multiple CDS views or whenever the name of the CDS view is not
descriptive or too long.
4. Click the activation button or use the shortcut Ctrl + F3 to activate the service definition.
To check the syntax before activation, click or use the shortcut Ctrl + F2 .

Start PUBLIC 325
Results
The resulting source code for the service definition is as follows:
@EndUserText.label: 'Read-Only E2E: SD for Managing Flights'

define service /DMO/FLIGHT_R {
expose /DMO/I_Connection_R as Connection;

}
The source code above is used to define a service definition named /DMO/FLIGHT_R. It exposes the CDS
view /DMO/I_Connection_R to be included in the service.
Next Steps
Now that the service exists, you can determine the binding type and category for the service using a service
binding.
3.3.2.3 Creating a Service Binding
Use the service binding wizard to create the relevant development object to bind the service to a protocol and,
if necessary, to an OData client.
Prerequisites
You have defined a service and exposed CDS entities that are included in the service.
Context
A service binding implements the protocol that is used for the OData service. It uses a service definition that
projects the data models and their related behaviors to the service.
To create a Service Binding, use the wizard to create the relevant development object to bind the service to a
protocol and, if necessary, to an OData client as described in .
Use the Binding Type ODATA V2 - UI and the Service Definition /DMO/FLIGHT_R.
Results
The ABAP back end creates a service binding and stores it in the ABAP Repository.

326 PUBLIC Start
In the Project Explorer, the new service binding is added to the Business Services folder of the corresponding
package node. As a result, the service binding form editor is opened and you can verify the information you
have entered.
Service Binding Artifact Form Editor
Next Steps
Activate the service binding to make it ready for consumption.
3.3.2.4 Publishing the OData Service Locally
To make the service ready for consumption, use the activation button in the service binding form editor.
Prerequisites
You have created the service binding and specified the binding type and category.
Context
To make the service available and consumable by an OData client you have to activate the service.
Procedure
1. If you have not already done so, open the new service binding in the form editor.
The binding type and category are already defined and cannot be changed once the service binding is
created. You can verify the type and category in the general information section in the form editor. As soon

Start PUBLIC 327
as you have specified the binding for the service, it is ready for publishing. The service is then available for
consumption.
2. Choose the Publish button in the form editor. For more information about the editor, see Using Service
Binding Editor for OData V2 Service.
Results
The OData service /DMO/UI_FLIGHT_R_V2 is published locally, which means that it is activated in SAP
Gateway. The service is bound to the protocol OData V2 for the category UI. This means it can now be
consumed by a SAPUI5 application.
The binding type and service information is displayed in the service binding form editor
On the left side of the form editor, the service list with the version and the service definition is filled. The right
side of the form editor shows the service details. It provides a URL to view the metadata of the service and lists
the entity sets that are exposed for the service. The service contains the entities that you have exposed in the
service definition. The service binding editor shows the names that you assigned as alias.
3.3.2.5 Verifying the OData Metadata
Use the URI in the service binding form editor to check the metadata document of the published OData service.
Prerequisites
You have published an OData service using a service binding.
Context
In the previous steps we defined an OData service and published it. It is now ready to be consumed by an HTTP
protocol. To verify the data that the OData service exposes, the service offers a metadata document in which all
relevant service elements are listed.
Procedure
1. If you have not already done so, open the service binding for the relevant service.
2. To open the service document of the OData service, choose the link to the service URL (/sap/opu/
odata/sap/DMO/UI_FLIGHT_R_V2) that is provided in the form editor for the relevant line in the service
details section.

328 PUBLIC Start
A browser opens that displays the service document.
3. Add /$metadata to the URI in the address bar to view the metadata of the OData service.
…/sap/opu/odata/DMO/UI_FLIGHT_R_V2/$metadata
The metadata document displays the relevant information that the OData service provides for an OData
client in a CSDL (Common Schema Definition Language).
 Note
As labels are language dependent, they are only displayed if the language of the browser and the
maintained data elements are in the same language, or if a fallback language matches the browser
configurations.
OData metadata
 Note
Depending on your browser and the xml format you choose, the layout of the metadata might differ.
For the described scenario, the following OData annotations are relevant:
• EntityType: Introduces a CDS entity that is exposed for the service.

sap: label: Provides a semantic description for the entity type. It retrieves the description that was
entered in the wizard for the data definition as no other label is defined.
Name: Specifies the name of the OData entity. It uses the name of the CDS entity and attaches Type. If
an alias is used in the service definition, it uses the alias.
• Key: Introduces the OData properties that are specified as keys for the OData entities. If the
service is based on CDS entities, it uses the keys of the CDS entities.
Property: Introduces an OData property that is exposed in the service. If the service is based on a
CDS entity, it uses the elements of the CDS view as properties.
sap: label: Provides a more informative description than just the name of the property. It retrieves
the field label text of the data element if the CDS element is not labeled differently.
Name: Specifies the name of the OData property. The service uses the name of the CDS elements.
It retrieves the alias if there is one.

Start PUBLIC 329
sap:quickinfo: Provides a semantic description for the property. It retrieves the description of the
data element that is used in the database table /dmo/connection if no other description is
defined.
sap:unit: Specifies that the respective OData property describes an amount whose unit is provided
with the referenced property. In this case, as we have defined it in CDS with a semantics
annotation, the property DistanceUnit provides the unit for the Distance.
sap:semanticsDistanceUnit only contains currency codes. This information is taken from the
data element that is used for the database table /dmo/connection, which is stored in ABAP
Dictionary.
 Note
The information that is taken from the data elements can be checked in the data definition. Click a CDS
element in the data definition and press F2 . A pop-up opens and you can navigate to all the underlying
elements, displaying the semantic information for the respective OData property.
Next Steps
To check the output of a SAP Fiori UI you can preview the app with the previewing functionality of the service
binding.
3.3.2.6 Previewing the Resulting UI Service
Use the preview function in the service binding to check how the UI of a Fiori application looks like.
Prerequisites
You have published an OData service using a service binding.
Context
The published OData service is ready to be consumed by an HTTP protocol. You can set up a Fiori application
based on this service. The service binding artifact offers a tool which you can use to preview a simple list
reporting Fiori application.

330 PUBLIC Start
Procedure
1. If you have not yet already done so, open the service binding for the relevant service.
2. To open the Fiori Elements app preview in the service information section, select the relevant entity set
(Connection) and choose the Preview button as described in Using Service Binding Editor for OData V2
Service.
3. Choose Open Fiori Elements App Preview.
Your internet browser opens a new tab.
4. You now have access to the system and the Fiori Elements app UI is displayed. The columns of the
elements that you have in the CDS views appear. The app does not show any data yet.
5. To display data in the list report, first select the items that you want to display by clicking the configuration
button  and choosing the elements from the column section.
You need to select at least one element, otherwise you get an error message when retrieving the data.
6. Choose Go to display the data of the items you selected.
Results
The Fiori Elements App preview opens in your browser. You see the connection data that you implemented in
the CDS view. The following image displays the list report when selected all available fields.

Start PUBLIC 331
3.3.3 Designing the User Interface for a Fiori Elements App
UI annotations can be used in CDS to configure the look of the user interface of a Fiori App.
To define annotations that concern the UI, we use CDS annotations. CDS offers the option of defining a
universal setup for the presentation and order of items in the CDS layer. This is independent of the UI
technology or application device, which benefits the reuse of one OData service for multiple applications. The
application developer does not have to configure the setting for every application, but can reuse the settings
that were defined in the back end.
 Note
You can use metadata extensions to separate the metadata specified by @UI or other UI related
annotations from the actual data definition in the CDS view. See
You are introduced to necessary and useful UI annotations that define the presentation of your data in a UI
service.
Task: Defining UI Annotations [page 332] .
The task addresses different components of the user interface separately.
In the section List Items [page 333] CDS offers the option to define a universal setup for the presentation and
order of the business data. You will learn how to order and label the columns of your list report.
The second section List Report Header [page 335] deals with the items in the list report header.
The section Object Page [page 336] describes the configuration of an object page and its items.
 Tip
You can always check the influence of the UI annotations on the UI with the preview option in the service
binding form editor.
3.3.3.1 Defining UI Annotations
The presentation and order of the CDS elements in a SAP Fiori Elements user interface is configured in CDS
with annotations.
Context
You have created an OData service and published it locally. The UI can now be set up with UI annotations in the
CDS layer to define a UI layout independent from the application or the user device. You can always check the
influence of UI annotations by using the preview function in the service binding artifact.

332 PUBLIC Start
List Items
Context
Using the following annotations, you specify which of the elements appear in the list report when starting the
app. In addition to their order, you can also rename them if you want to display them with a name other than
the name specified in the CDS entity. The columns that are shown in the UI are then predefined and you can
retrieve data by choosing GO without determining the columns to be displayed.
Procedure
1. Open the CDS view for which you want to determine the list report. In our case: /DMO/I_Connection_R.
2. For the headline of the list, use the annotation @UI.headerInfo:typeNamePlural:'name'.
This annotation is an entity annotation because it concerns the whole entity rather than a specific element.


@UI.headerInfo.typeNamePlural: 'Connections'


…
3. Specify a position for each element that you want to show in the list report with the annotation
@UI.lineItem: [ { position:decfloat } ].
 Note
The value's number does not represent an absolute measure and works as a relative value to the
positions of the other elements instead. Hence, the elements are arranged in ascending order with
regard to the annotation value.
…

{

@UI.lineItem: [ { position: 10 } ]











Connection.distance as Distance, //** secondary
information, not to be displayed on list report entry page
Connection.distance_unit as DistanceUnit //** secondary


}

Start PUBLIC 333
4. You can display the elements with a name other than the name specified in CDS by labeling them with the
annotation @UI.lineItem.label: label. In particular, you can label element with names containing
spaces. The label is displayed in the column header of the list report.
…

{

@UI.lineItem: [ { position: 10, label: 'Airline'} ]


@UI.lineItem: [ { position: 20, label:'Connection Number' } ]


@UI.lineItem: [ { position: 30 , label: 'Departure Airport Code'} ]


@UI.lineItem: [ { position: 40 , label: 'Destination Airport Code'} ]


@UI.lineItem: [ { position: 50 , label: 'Departure Time'} ]


@UI.lineItem: [ { position: 60 , label: 'Arrival Time' } ]


}
Results
The source code specifies which of the elements of the CDS view /DMO/I_Connection_R are displayed in
the list report and in which order. In addition, the list report is given the title Connections. When starting the
app, you do not have to select columns in the settings since they are already displayed. Press the GO button to
retrieve data.
List report after UI configuration in the data definition

334 PUBLIC Start
List Report Header
Context
The following annotations specify the items that are shown in the list report header.
You can define a header for the list report or you can implement selection fields on top of the list report to filter
for a specific item. One selection field always refers to one element, but you can have more than one selection
field in a single list report header.
Procedure
To include selection fields for the key elements in the header, use the annotation
@UI.selectionField.position:decfloat on the respective elements.
 Note
The value's number does not represent an absolute measure and works as a relative value to the positions
of the other selection fields instead. Hence, the selection fields are arranged in ascending order with regard
to the annotation value.
…

@UI.lineItem: [ { position: 30 , label: 'Departure Airport Code'} ]

@UI.selectionField: [ { position: 10 } ]




…
Results
The selection field annotation is used on the key elements of the CDS view to create a selection field in the
header on the list report. Using these selection fields, you can filter for specific list items.

Start PUBLIC 335
UI with selection fields filtered for connections to a specific destination airport
Object Page
Context
Whereas the list report gives a general overview of the list items, the object page shows more detailed
information about a single list item. You navigate to the object page by clicking the item in the list report.
Procedure
1. /DMO/I_Connection_R using the annotation @UI.headerInfo.typeName: 'name'.

@EndUserText.label: 'Read-Only E2E: Data Model Flight'

@UI.headerInfo.typeName: 'Connection'

define view /DMO/I_Connection_R

...
2. Create a standard facet for the object page with the annotation @UI.facet.purpose: #STANDARD. This
annotation must be in the element section.
A facet is a type of section in the object page. It can contain diagrams or other information in a discrete
part of the user interface.

{

@UI.facet: [ { purpose: #STANDARD } ]

...

336 PUBLIC Start
3. Specify the type of the facet. In our case, the object page displays the detailed information of one list item.
Use the annotation @UI.facet.type: #IDENTIFICATION_REFERENCE.

as select from /dmo/connection as Connection{
@UI.facet: [ {
purpose: #STANDARD,

type: #IDENTIFICATION_REFERENCE } ]

…
4. Specify a name for the object page facet header. Use the annotation @UI.facet.label: 'name'.

{
@UI.facet: [ {
purpose: #STANDARD,
type: #IDENTIFICATION_REFERENCE,

label: 'Connection' } ]

…
5. To define the position of the facet, use the annotation @UI.facet.position: decfloat.

as select from /dmo/connection as Connection{
@UI.facet: [ {
purpose: #STANDARD,
label: 'Connection',

position: 10 } ]

…
An object page of a type identification reference is created. You can now define the elements that are
displayed in the object page.
6. Specify the position and the label for each element that you want to show in the object page. Use
the annotations @UI.identification.position: 'decfloat' and @UI.identification.label:
'name' on each element.
{ …

@UI: { identification:[ { position: 10, label: 'Airline' } ] }


@UI: { identification:[ { position: 20, label: 'Connection Number' } ] }


@UI: { identification:[ { position: 30, label: 'Departure Airport
Code'} ] }


@UI: { identification:[ { position: 40, label: 'Destination Airport
Code'} ] }


@UI: { identification:[ { position: 50, label: 'Departure Time' } ] }


@UI: { identification:[ { position: 60, label: 'Arrival Time' } ] }


@UI: { identification:[ { position: 70, label: 'Distance' } ] }


}

Start PUBLIC 337
The following image displays the object page after clicking the connection item JL 407.
Object page with identification reference

Results
The resulting source code, including all annotations that are relevant for the UI in the data definition, is as
follows:
 Sample Code

@UI.headerInfo: { typeName: 'Connection',
typeNamePlural: 'Connections' }
{ @UI.facet: [
{ id: 'Connection',
purpose: #STANDARD, }
label: 'Connection' } ]
@UI: { identification:[ { position: 10, label: 'Airline' } ] }

338 PUBLIC Start
@UI.lineItem: [ { position: 20, label:'Connection Number' } ]
@UI: { identification:[ { position: 20, label: 'Connection
Number' } ] }
@UI: { identification:[ { position: 30, label: 'Departure Airport
Code'} ]
@UI: { identification:[ { position: 40, label: 'Destination Airport
Code'} ] }
@UI.selectionField: [ { position: 20 } ] }
@UI.lineItem: [ { position: 50 , label: 'Departure Time'} ]
@UI: { identification:[ { position: 50, label: 'Departure Time' } ] }
@UI.lineItem: [ { position: 60 , label: 'Arrival Time' } ]
@UI: { identification:[ { position: 60, label: 'Arrival Time' } ] }
@UI: { identification:[ { position: 70, label: 'Distance' } ] }
Connection.distance_unit as DistanceUnit //** information is
given with element Distance via semantic connection

}
Related Information
UI Annotations [page 1260]
3.4 Generating a RAP Business Service with the Generate

ABAP Repository Objects Wizard
You can create all RAP-service-related development objects on the basis of a database table by using the
Generate ABAP Repository Objects Wizard.
Introduction
Creating a RAP business object from scratch can be quite cumbersome as it involves many different
development objects that need to be created manually. The Generate ABAP Repository Object wizard has
a solution for this in straight-forward use cases. On the basis of one database table, it creates all the
development objects that are relevant for a business object and for a RAP service. You simply have to define
names for these objects and navigate through the wizard. The end result is a full-blown RAP UI service or Web
API.
The following objects are created by the wizard:

Start PUBLIC 339
• CDS view entity
• CDS behavior definition
• ABAP implementation class
• CDS projection view entity
• CDS projection behavior definition
• Draft database table (only for UI services)
• Metadata extension (only for UI services)
• CDS service definition
• Service binding
Data Model
The generation wizard creates the business object on the basis of a database table. The data model in the CDS
view entities uses all fields that are defined in the database table. It adds CDS annotations that can be retrieved
from the database modeling, for example @Semantics annotations for administrative fields, which are needed
for a managed BO. The wizard also creates alias names for the elements in the CDS view entity that represents
the BO entity. The alias names are created in camel case.
The CDS projection view entity contains all relevant fields for the transactional data model and the dedicated
admin field for ETag handling.
 Note
Currently, the generation wizard creates the CDS projection view without the provider contract
transactional_query. This leads to a syntax warning in the projection view.
Metadata Extension
For UI scenarios, the generation wizard creates a metadata extension object with the basic UI-related
annotations for a UI service. The UI service that is generated creates a basic list report application that
exposes all transaction-enabled fields on the UI. The fields are annotated with the relevant @UI.lineItem and
@UI.identification annotation.
Behavior
The generation wizard creates a managed RAP BO with draft capabilities. The behavior definition defines strict
mode. It contains the most basic behavior characteristics, for example the lock master and the authorization
master for global authorization control. In addition, the ETag master is defined.
The generated RAP BO defines the standard operations and the draft actions. In addition, the administrative
fields are set to read only and the field mapping is defined.
The RAP BO uses external numbering.
Business Service
The service definition exposes the generated CDS projection view.
Depending on the choice in the wizard, the service binding exposes a UI service (V2 or V4), or a Web API.

340 PUBLIC Start
Use
The Generate ABAP Repository Object wizard can be used for a quick start with RAP. It facilitates the creation
of development artifacts and ensures a consistent and functional business service with a few clicks and just
one prepared development object, the database table. The feature scope of the generation wizard is limited to
creating a business services that exposes a draft-enabled managed BO that contains no more than one single
BO entity.
 Note
It is not possible to create just a subset of the above-mentioned development objects. It always generates
the complete BO and the business service. The BO is always transaction- and draft-enabled and of
implementation type managed.
You can easily add more BO entities to the composition structure or add other features to the generated
objects. These features can be related to the data model, for example value helps or search capabilities, or
related to the behavior. In the behavior definition, you can add business logic by defining and implementing
actions, validations, or determinations.
 Note
When adding new CDS view entities to the compositional structure of the data model, make sure that
you also extend the behavior definition for the new BO entities. Otherwise your business service will show
errors.
Prerequisites
To build a RAP BO with the generation wizard, you need to prepare a database table that
• has a client field

• defines administrative fields that use the RAP reuse elements.
For more information, see RAP Reuse Data Elements [page 210].
3.4.1 Example: RAP Business Service Generation
This topics describes how you can create a UI service with the Generate ABAP Repository Objects wizard. It is
exemplified by a RAP BO based on the database table /dmo/customer.
Prepare Database Table /dmo/customer
To match the prerequisites mentioned in Prerequisites [page 341], add administrative fields to the database
table. These fields are used by the managed BO provider to fill the correct values during runtime.

Start PUBLIC 341
The field local_last_changed_at is used as ETag field for OData ETag comparison. The field
last_changed_at is used as total ETag, which is necessary for draft BOs.
 Expand the following code sample to view the source code of database table /dmo/customer.
 Sample Code
@EndUserText.label : 'Flight Reference Scenario: Managing Customers'

@AbapCatalog.enhancement.category : #NOT_EXTENSIBLE
define table /dmo/customer {
key client : abap.clnt not null;
key customer_id : /dmo/customer_id not null;
first_name : /dmo/first_name;
last_name : /dmo/last_name;
title : /dmo/title;
postal_code : /dmo/postal_code;
city : /dmo/city;
country_code : land1;
phone_number : /dmo/phone_number;
email_address : /dmo/email_address;
local_created_by : abp_creation_user;
local_created_at : abp_creation_tstmpl;
local_last_changed_by : abp_locinst_lastchange_user;
local_last_changed_at : abp_locinst_lastchange_tstmpl;
last_changed_at : abp_lastchange_tstmpl;

}
Use the Generate ABAP Repository Objects Wizard
1. In the project explorer, open the context menu on the database table /dmo/customer and choose
Generate ABAP Repository Objects.
2. Choose ABAP RESTful Application programming Model: UI Service as use case.
3. Navigate through the wizard and provide names for the objects that are generated.
The following names are used for this example:

342 PUBLIC Start
Preview Generator Output
4. Choose Finish to start the generation of all development objects.
Result
As a result, the wizard generates all development objects that are displayed in the preview. All objects are
activated automatically. The draft-enabled RAP business object is exposed as a UI service. By opening the
service binding editor, you can publish the service locally and open the Fiori Elements App Preview to see the
result on the UI.
You can use all repository objects as usual and modify them. You can add data model options, for example
value help or search capabilities to CDS view entities. You can also extend the behavior with actions and
functions or other business logic with validations and determinations. In general, the generated business
object is editable and useable in the same way as a manually developed business object.
 Note
When adding new CDS view entities to the composition structure of the data model, you have to add the BO
entity in the behavior definition.

Start PUBLIC 343
4 Develop
The development guides in this section provide a detailed step-by-step description on how to use and exploit
the ABAP RESTful application programming model in end-to-end scenarios.
The guides in this section focus on specific development tasks. It depends on your initial situation and on the
aimed outcome of your development, which guide meets your requirements best.
Follow the path in the diagram and ask yourself the questions to find out which development guide helps
you with your development task. You get further information about the steps and the development guides by
hovering over the image.

344 PUBLIC Develop

• Develop [page 344]

• Developing an OData Service for Simple List Reporting [page 315]
• Developing Read-Only List Reporting Apps [page 350]
• Developing Unmanaged Transactional Apps [page 481]
• Cloud Developing a UI Service with Access to a Remote Service [page 714]

Develop PUBLIC 345
• Develop Web APIs [page 765]
• Developing Managed Transactional Apps [page 371]
• Developing Transactional Apps with Draft Capabilities [page 578]
• Developing Transactional Apps with Multi-Inline-Edit Capabilities [page 693]
Use the navigation in the image or the following links to navigate to the development guides:
Developing Read-Only List Reporting Apps [page 350]
Developing Unmanaged Transactional Apps [page 481]
Developing Managed Transactional Apps [page 371]
Develop Web APIs [page 765]
 Cloud Cloud Developing a UI Service with Access to a Remote Service [page 714]
4.1 Development Constraints
The current version of the ABAP RESTful application programming model still has some constraints for ...
Actions with Parameters
In case a value help is added to an action parameter (e.g. via annotation @ValueHelpDefinition in
corresponding abstract entity for the action parameters) the value help isn't added automatically to the service
and must be added to the service definition explicitly.
Create and Edit in the Same Request

An EML request containing create and edit in the same MODFY ENTITIES statement currently results in a
runtime error.
Heterogeneous Deep-Create
If at least one property in a service is annotated with an explicit value control property, the heterogeneous
Deep-Create is disabled for the service entirely
RAP Testability
Support is missing for the testability of Draft-enabled BOs and the related tables like draft-admin-data, durable
locks, messages.
Using Parameters in CDS Views

CDS Views with parameters don't work properly in Fiori Elements UI services. The filter value isn't sent to the
back end.

346 PUBLIC Develop
Using a Consumption Model with two Namespaces
The OData Client Proxy doesn't support two namespaces.
Where Clause in CDS Projection Views

In transactional operations, including the transactional READ, the where clause in projection views isn't
respected. Applications must ensure that the instances that are created, updated, or read via the projection
conform to the where clause.
Different Projections
If multiple projections expose the same RAP BO, it must not be modified via different projections in the same
LUW.
Using Determinations and Validations

When using determinations and validations, the following constraints are given:
• The trigger operation update for determinations and validations on save is only supported in combination
with the trigger operation create.
• The trigger operation delete is of limited use, unless the instances of entities are identified by semantic
keys.
• It'sn't possible to assign a determination or validation for a descendent entity to a determine action, if the
determination or validation has the trigger operation delete.
Augmentation
In case the augmentation implementation adds operations on nonoriginal instances (which aren’t part of
the original request), the runtime attempts to lock these automatically. For a proper response, it's the
responsibility of the augmentation implementation to use the "relating by" syntax to relate these nonoriginal
instances to original instances. Then, the runtime maps lock failures on nonoriginal instances back to failure of
the corresponding related instances.
If the nonoriginal instances require authorization (not covered by the original instances), it is the responsibility
of the augmentation implementation to check it's authorization.
Draft-Enabled Business Objects

• There can be locking conflicts for the active provider if an instance that was activated is locked again in the
same transaction. This is because the durable lock of the active instance remains after the activation of a
draft instance.
• Every child entity in a CDS composition hierarchy must be represented in the behavior definition if a
behavior definition for the root entity exists and defines a draft-enabled RAP business object.
Projections on top of BO Interfaces

You can't use augmentation if the source of a BDEF projection is a behavior definition of implementation type
interface.
Unmanaged Business Objects with Draft

There are features that can be defined in the behavior definition of an unmanaged business object and thus
used on active instances, but not on draft instances:
• You can't execute the following operations on draft instances:

Develop PUBLIC 347
• Create-enabled associations that aren't modeled as part of a composition
• Direct creates on child instances
• The aggregated admin data fields aren't updated automatically when a draft instance is saved.
• Associations that use NOT in the binding condition can't be draft-enabled.
• There's no support for transactional draft-enabled associations leading from draft to active instances.
• Client-independent CDS views aren't supported.
Functions
Multiple Execution of Bound Actions / Functions on same Instance
If bound non-factory actions or functions are executed multiple times on the same binding instance (but
maybe with distinct parameters), the assignment of the operation result to the request operations is
ambiguous for the consumer and for the provider. This is due to the missing operation ID ("OID") and applies
to to EML and for actions also to OData change sets. For OData change sets, this can cause violations of return
multiplicities, leading to a Gateway exception after successfully finished LUW. You can use repeatable actions
to implement this behavior.
Performance in Draft Scenarios
Draft handling isn't mass-enabled. Processing many draft instances at once has a negative performance
impact.
Cross-BO Functionality
Draft Scope isn't supported.
Releasing RAP Business Object with C1 Release Contract
Currently you can't release BOs with :
• entities that contain virtual or path elements.

• draft scope.
•
Unmanaged Queries in Sort or Filter Requests
An unmanaged query can't process path expressions using to-one associations with a foreign target in filter or
sort requests.
Deep Parameters in Non-Standard Operations
OData exposure of operation parameters that are modeled as a composition hierarchy of abstract entities
(deep parameters) is only possible with OData V4.
Using field (suppress) in a Managed Context
Currently, the syntax field(suppress) to remove fields from the BDEF derived types, OData, and all RAP
APIs on base BO level is only supported for the implementation type unmanaged. You can't use it for a
managed RAP BO or an unmanaged RAP BO with draft capabilities.

348 PUBLIC Develop
Invalidating OData Service
In case of changing (deep) action parameters or non-entity action results with an OData service (V2 and V4),
the result is not invalidated correctely, because the changes are not taken into account when calculating the
last-changed -timestamp. A workaround is the activation of e.g. BDEF or service definition.
Business Events in Extensions

It's not possible to create and raise an event in an extension BDEF.
To expose events with an event bindings, it is currently required that the respective (base) root CDS view is
released for the Extend (C0) release contract.
RAP Extensibility
• Node Extensibility: Currently it's not possible to release a service definition extension for the Extend
release contract. Thus, extension node of released RAP BOs can only be conusmed via EML and not via an
OData Service.
• Behavior Extensibility:
• Behavior extensions are only supported for the implementation type managed.
• In order to expose action extensions on the UI, any field in the CDS view extend of the projection layer
is required, which the UI annotations for the action extensions can refer to.
• Virtual Elements: You can't add virtual elements to extensions on the projection layer.
• Augmentation: It's not possible to use augmentation in an extensibility scenario.
• Draft: You can't subsequently draft-enable a RAP BO interface or CDS projection after they have been
released for the Extend(C0) release contract.
• MAP_MESSAGES: You can't implement MAP_MESSAGES in extensions.
• Additional Clean-Up: You can't implement an additional clean-up in extensions.
Large Objects
• The RAP Runtime Engine rejects OData V4 requests having an $expand clause where a $select clause is
stated for the expanded entity that contains the property SAP__Messages explicitly. If the expanded entity
contains a large object property, then such requests are rejected even if no $select clause is specified for
the expanded entity.
• When downloading attachments, file extensions are present twice in the downloaded content.
Mixed Client Dependencies within RAP BOs

BOs with mixed client-dependencies in their composition hierarchy aren't consistently supported.
UI annotations in OData V2
The UI annotations UI.CreateHidden, UI.UpdateHidden and UI.DeleteHidden are not supported in

OData V2.
Side Effects
• Currently, $self as side effect source or target is only possible with OData V2.
• Messages as side effect target are only available with OData V4.
• Association paths with multiple associations are currently not supported.
/>

Develop PUBLIC 349
4.2 Develop Applications
Here you can find end-to-end scenarios for developing RAP applications.
If you want to develop an application, the following development examples are available:
• Developing Read-Only List Reporting Apps [page 350]: In this chapter you learn how to develop an OData
service including multiple read-only features. This OData service can be consumed by a Fiori Elements
application or by any other OData client. Based on existing persistent data sources, you create and
implement a query for an OData service to get a running app with useful read-only features.
• Developing Managed Transactional Apps [page 371]: In this chapter, you will be guided through all
steps necessary to develop a travel administration app based on the business object’s managed runtime
infrastructure.
• Developing Transactional Apps with Draft Capabilities [page 578]: This chapter is a walk-through tutorial
that guides you through the main implementation steps to develop an application with draft support.
Draft-enabled applications provide the end user with the highest flexibility when working with the app.
• Developing Unmanaged Transactional Apps [page 481]: This chapter explains the main development
tasks required for enabling transactional processing in a business objects provider that integrates existing
business logic.
• Developing Transactional Apps with Multi-Inline-Edit Capabilities [page 693]: This chapter guides you
through the implementation steps to create an application with multi-inline-edit capabilities. These are
always necessary, if you want the end user of a UI app to be able to edit, add, and delete all instances
directly on a Fiori UI list report without navigating to the object page of one instance.
• Cloud Developing a UI Service with Access to a Remote Service [page 714]: With this chapter you can
create a new service that enhances the remote service with additional information based on a remote
OData service. You develop an OData service that consumes a Web API
4.2.1 Developing Read-Only List Reporting Apps
Based on existing persistent data sources, you create and implement a query for an OData service to get a
running app with useful read-only features.
Introduction
In this chapter you learn how to develop an OData service including multiple read-only features. This OData
service can be consumed by a Fiori Elements application or by any other OData client.
Starting from the elementary list reporting scenario that was introduced in the Start [page 305] section, you
may want to add some further features to the existing elementary OData service. First of all, the end user wants
to be able to navigate to a second information layer for a flight connection to retrieve more detailed information
about the flight, such as flight dates or plane types. Secondly, if the list report contains a large number of rows,
it becomes difficult for end users to find the information they need. To make it easier to find this information,
you can implement search capabilities or label the app elements differently than their presets in the data model
layer in the back end. You might also want to enable value helps for selection field dialogs. All these features

350 PUBLIC Develop
are implemented using specific CDS annotations, which you, as the developer, add to the source code of the
respective CDS view.
We assume that you know the development steps to create an OData service, as described in the Start [page
305] section. The following guide uses the CDS view /DMO/I_Connection_R and the OData service /DMO/
UI_FLIGHT_R_V2 as the basis for a more elaborate OData service with further read-only features. You learn
how to expand the data model with associated CDS views and how to include useful read-only functions in the
OData service.
You are guided step-by-step through the application model and expand the OData service that you created in
the Getting Started section with the following features and query capabilities.
• Expanding the data model with additional CDS views [page 353]
• Navigating between CDS views with associations [page 358]
• Changing UI Field Labels and Descriptions [page 360]
• Displaying Text for Unreadable Elements [page 362]
• Providing Value Help for the Selection Fields [page 365]
• Adding Search Capabilities [page 368]
This scenario implements the query case. We firstly define a CDS data model for which we define modeled
query capabilities. The service that was created in the Getting Started scenario is reused and the new CDS
entities including their query capabilities are exposed for this service.
 Note
Via ABAPGit You can import the service including the related development objects into your development
environment for comparison and reuse. You find the service in the package /DMO/FLIGHT_READONLY. The
suffix for development objects in this development guide is _R.
Prerequisites

 Restriction

Develop PUBLIC 351
• You have understood the development steps to create an OData service as described in Developing an
OData Service for Simple List Reporting [page 315].
In particular, you are able to use the existing OData service /DMO/UI_FLIGHT_R_V2 to check and try out
the new implementation with the preview tool.
Objectives
By the end of this development guide you are able to:
• Apply and enhance your knowledge about how to create and expand an OData service
• Implement associations between CDS views
• Expose new CDS views for an existing OData service
• Use @EndUser.Text annotations
• Implement text associations
• Develop value helps for input fields
• Implement search capabilities
4.2.1.1 Determining the Data Model for the Read-Only

Scenario
Starting Point
We build the list reporting scenario based on the service that was created in the Start [page 305] scenario. The
CDS view /DMO/I_Connection_R is reused in the following scenario and included in a broader data model.

352 PUBLIC Develop
In the first step of this development guide, you expand the data model with additional CDS views to create a full
blown reference app for flights. The resulting running app is able to find flights based on connections and the
airports involved. From a technical point of view, this means that the CDS data model is expanded with three
other CDS views, one of which is connected using associations to enable navigation from one CDS view to
another. The data model and the relationship between the CDS views that you work on to implement read-only
features is illustrated in the following figure. All items represent a self-contained data model of a CDS view that
retrieves data from a database table included in the ABAP Flight Reference Scenario [page 309].
Data model for read-only scenario
As you can see in the figure above, the entry point of the flight scenario is the well-known CDS view /DMO/
I_Connection_R. It manages data for flight connections. From here, you can navigate to more detailed flight
information with flight dates and plane information. The detailed information in the carrier CDS view is used to
display the full name of the airline, whereas the CDS view /DMO/I_Airport_R is used as a value help provider
view for the airport elements in the connection CDS view.
These items only represent a part of the ABAP Flight Reference Scenario.The other items in the reference data
model are applied in other development scenarios.
4.2.1.1.1 Defining CDS Views
To provide a complete data model for a read-only OData service, CDS views have to be defined first.
Context
In the introductory guide, you learned how to define CDS views based on an existing persistent data source.
Repeat the process for further CDS views to expand the data model for the flight scenario. We assume that the
CDS view /DMO/I_Connection_R already exists. This view defines the starting point of the app.
For a detailed description of the following steps, look at Defining the Data Model with CDS [page 317].
Procedure
1. For each new CDS view, do the following:

Develop PUBLIC 353
a. Create a data definition using the creation wizard in your development package.
b. Implement the CDS view as a data model and define the name of the CDS view as given in the table
below.
 Note
Naming CDS views: Since CDS views are (public) interface views, they are prefixed with I_ in
accordance with the VDM (virtual data model) naming convention. In addition, we add the suffix _R
for the read-only implementation type to the view name.
Data Definition
Data
CDS View Name Source Description
/DMO/I_FLIGHT_R /dmo/ Provides information about the available flights including flight dates
flight and plane information.
/DMO/I_Flight_R
(DB table) You can navigate to this view once you have chosen a flight connec-
tion.
/DMO/I_CARRIER /dmo/ Provides information about the airlines that operate the flights.
carrier
/DMO/I_Carrier This view is later used as a value help provider view for the
(DB table) view /DMO/I_CONNECTION_R.
 Note
As this CDS view is reused in more scenarios, it does not carry a

suffix.
/DMO/I_AIRPORT /dmo/ Provides information about the involved airports.

airport
/DMO/I_Airport  Note
(DB table)
As this CDS view is reused in more scenarios, it does not carry a
suffix.
2. For each new CDS view, do the following:

a. Insert all elements provided from the data source.
b. Add a meaningful alias to each CDS element.
3. Add the relevant @Semantics annotation where necessary.
The price element in the CDS view /DMO/I_FLIGHT_R must be annotated with
@Semantics.amount.currencyCode: 'CurrencyCode'. This annotation establishes the link between
the amount and the currency element.
More information: Relating Semantically Dependent Elements [page 321].

4. Insert the relevant UI annotations to ensure that the user interface is rendered properly where necessary.
Whereas the existing CDS view of the introductory guide in the getting started section requires many UI
annotations, since it represents the landing list report page, the new CDS views only require a limited

354 PUBLIC Develop
number of UI annotation. In fact, only the CDS view /DMO/I_Flight_R requires the @UI.lineItem:
[{}] annotation to be applied to the relevant elements. Since the remaining views only function as text
provider or value help provider views, they do not need any UI annotations at all.
A detailed description of this procedure is described in Designing the User Interface for a Fiori Elements
App [page 332].
The resulting source code for each data definition is displayed at the end of this topic: Data Model for Flight
App [page 355].
6. Include the new CDS entities in the existing service /DMO/UI_FLIGHT_R_V2, which you created in the
introductory guide in the getting started section: Developing an OData Service for Simple List Reporting
[page 315]. To do this, expose the CDS entities in the service definition /DMO/FLIGHT_R. Specify the
leading entity /DMO/I_Connection_R in the annotation @ObjectModel.leadingEntity.name:. In
case multiple entities are exposed by one service definition, it defines the main entity of the service.
The following codeblock displays the source code of the updated service definition /DMO/FLIGHT_R
@EndUserText.label: 'Service Definition for Managing Flights'

@ObjectModel.leadingEntity.name: '/DMO/I_Connection_R'
define service /DMO/FLIGHT_R {
expose /DMO/I_Connection_R as Connection;
expose /DMO/I_Flight_R as Flight;
expose /DMO/I_Carrier_StdVH as Airline;
expose /DMO/I_Airport_StdVH as Airport;
expose I_CountryVH as Country;

}}
4.2.1.1.2 Data Model for Flight App
The following listings display the source code of the CDS views that are involved in our read-only scenario.
 Note
You can use metadata extensions to separate the metadata specified by @UI or other UI related
annotations from the actual data definition in the CDS view. See
 Expand the following listing to view the source code of the Connection CDS view.
Connection CDS view /DMO/I_Connection_R

This CDS view is the entry point of the flight reference app. It provides the elements for the connection search
that the end user can use to find suitable flights for a journey.
This CDS view /DMO/I_Connection_R was already modeled in the introductory guide in the getting started
section.

{

Develop PUBLIC 355
@UI.facet: [
{ id: 'Connection',
purpose: #STANDARD,
position: 10 } ]
@UI: {
lineItem: [ { position: 10, label: 'Airline' } ],
identification:[ { position: 10, label: 'Airline' } ] }
@UI: {
lineItem: [ { position: 20, label: 'Connection Number' } ],
identification:[ { position: 20, label: 'Connection Number' } ] }
@UI: {
lineItem: [ { position: 30, label: 'Departure Airport Code' } ],
selectionField: [ { position: 10 } ],
identification:[ { position: 30, label: 'Departure Airport Code' } ] }
@UI: {
lineItem: [ { position: 40, label: 'Destination Airport Code' } ],
identification:[ { position: 40, label: 'Destination Airport Code' } ] }
@UI:{
lineItem: [ { position: 50, label: 'Departure Time'} ] ,
identification: [ {position: 50, label: 'Departure Time' }] }
@UI:{
lineItem: [ { position: 60, label: 'Arrival Time' } ] ,
identification: [ {position: 60, label: 'Arrival Time' }] }
@UI:{ identification: [ {position: 70, label: 'Distance' } ] } **
establishes the link between quantity and the corresponding unit of measure

}
 Expand the following listing to view the source code of the Flight CDS view.
Flight CDS view /DMO/I_Flight_R

This CDS view provides detailed information about the flights. It is displayed as a second facet in the UI, which
means we only need a limited number of UI annotations.

@EndUserText.label: 'Read-Only E2E": Data Model Flight'
define view entity /DMO/I_Flight_R
as select from /dmo/flight as Flight
{
key Flight.carrier_id as AirlineID,
@UI.lineItem: [ { position: 20, label: 'Connection Number' } ]
key Flight.connection_id as ConnectionID,
@UI.lineItem: [ { position: 30, label: 'Flight Date' } ]
key Flight.flight_date as FlightDate,
@UI.lineItem: [ { position: 40, label: 'Price' } ]
@Semantics.amount.currencyCode: 'CurrencyCode' ** establishes the link
between amount and currency code
Flight.price as Price,
Flight.currency_code as CurrencyCode,
@UI.lineItem: [ { position: 50, label: 'Plane Type' } ]
Flight.plane_type_id as PlaneType,
@UI.lineItem: [ { position: 60, label: 'Maximum Seats' } ]
Flight.seats_max as MaximumSeats,
@UI.lineItem: [ { position: 70, label: 'Occupied Seats' } ]
Flight.seats_occupied as OccupiedSeats

356 PUBLIC Develop
}

 Expand the following listing to view the source code of the Carrier CDS view.
Carrier CDS view /DMO/I_Carrier

This CDS view is used as a text provider view for the main views of the app. It contains the text for the element
AirlineID.

@EndUserText.label: 'Read-Only E2E: Data Model Carrier'
define view entity /DMO/I_Carrier
as select from /dmo/carrier as Airline
{
key Airline.carrier_id as AirlineID,
Airline.name as Name,
Airline.currency_code as CurrencyCode
}

 Expand the following listing to view the source code of the Airport CDS view.
Airport CDS view /DMO/I_Airport

This CDS view is used as a value help provider view for the connection view. It contains detailed information
about the available airports that can be used for the value help.

@EndUserText.label: 'Read-Only E2E: Data Model Airport'
define view entity /DMO/I_Airport
as select from /dmo/airport as Airport
{
key Airport.airport_id as AirportID,
Airport.name as Name,
Airport.city as City,
Airport.country as CountryCode

}
 Note
To obtain the full scope of a data model and to enable flexible service consumption, you can project the
data model before creating a business service with CDS projection views. With a projection layer, you can
extend the basic data model without affecting the already existing business service.
For more information, see CDS Projection View [page 201].

Develop PUBLIC 357
4.2.1.2 Implementing Associations for Existing CDS Views
Associations structure the relationships between CDS views. To enable navigation in the UI, associations must
be implemented in CDS.
Context
You created the flight CDS view that provides detailed information about the available flights for the
connection. To be able to navigate to this view in the UI, you have to implement an association from /DMO/
I_Connection_R to /DMO/I_Flight_R.
An association defines a structural and unidirectional relationship between two CDS views. Associations are
used to navigate from a source CDS view to a related target CDS view.
Associations are defined in the source CDS view. The connections between the two CDS views are established
by a join condition applied to the respective elements of the source and target view. You need to define a
cardinality for the target CDS view to define how many records of the target CDS view are associated with one
record of the source.
Procedure
1. Open the source CDS view /DMO/I_Connection_R.

2. Define the association after the select statement.
a. Introduce the association with the keyword association.
b. Define [min .. max] for the cardinality of the target view.
 Note
The cardinality defines the minimum and maximum number of associated entries of the target
view.
In our example, the cardinality is one-to-many, since one entry in /DMO/I_Connection_R is

associated to many entries of /DMO/I_Flight_R. This complies with business logic since one
connection can be operated by flights on different dates.
...

define view entity /DMO/I_Connection_R as select from /dmo/connection as
Connection

association [1..*]
c. Specify the target CDS view and define an alias. An alias makes it easy to reference the association.

define view entity /DMO/I_Connection_R as select from /dmo/connection as
Connection

association [1..*] to /DMO/I_Flight_R as _Flight
d. Specify the mapping condition for the CDS views.

358 PUBLIC Develop
In our example, the associated CDS views are mapped to two elements. Therefore both of them must
be stated in the condition expression.
define view entity /DMO/I_Connection_R as select from /dmo/connection

association [1..*] to /DMO/I_Flight_R as _Flight on
$projection.AirlineID = _Flight.AirlineID

and
$projection.ConnectionID = _Flight.ConnectionID
3. Add the association to the element list in the CDS view.
{

...
/*Associations*/
_Flight ** use the alias to refer to the association

}
4. For the UI: Provide a second facet to make it possible to navigate from the list report page to the detailed
object page of the connection with corresponding flights as line items.
A detailed description of UI annotations can be found in Defining UI Annotations [page 332].
@UI.facet: [

{ id: 'Connection',
purpose: #STANDARD,
position: 10 } ,
{ id: 'Flight',
purpose: #STANDARD,
type: #LINEITEM_REFERENCE,
label: 'Flight',
position: 20,
targetElement: '_Flight' }

]
Results
You have established a connection between the connection CDS view and the flight CDS view. With the right
configuration of UI annotations, the end user can now navigate to the flight information by selecting one
connection in the list report app. The flight information is displayed as line items in the object page as can be
seen in the following figures.
Click on one connection entry to navigate to the information for flights.

Develop PUBLIC 359
Selection of the connection AZ 789 from TYO to FCO
The object page then displays the information about the selected connection and the related flights for this
connection in the second facet. .
Object page displaying all flights of the connection AZ 789 from TYO to FCO
4.2.1.3 Changing UI Field Labels and Descriptions

Field labels and description help to customize the UI of the app.
Meaningful descriptions of elements that appear on the user interface are a key concept for working with an
app and improving the user experience. It is essential that all items on the UI are readable and understandable
for the end user. Although every data element in ABAP Dictionary is labeled with descriptions for presentation
on the UI, sometimes you want to modify the description for a specific use case and give it a name other
than the name predefined on the persistent database layer. In the CDS layer, database description labels can
be redefined and given more information by using the annotations @EndUserText.label: '<text>' and
@EndUserText.quickInfo: '<text>'.
The labels that are assigned in the CDS layer overwrite the database field descriptions and are exposed to the
OData service. These labels are also propagated to the UI and displayed on the user interface if no UI labeling
annotations exist that overwrite the CDS EndUserText annotations.
 Note
UI labeling annotations, such as @UI.lineItem: [ { label: '' } ], overwrite any @EndUserText

labeling annotations on the UI. However, they are not manifested in the OData service metadata.
A tooltip can provide additional or more thorough information for the element. The tooltip is displayed on the UI
as mouse over text. If no @EndUserText annotations are used, the text for the mouse over function is retrieved
from the long description of the data element stored in ABAP Dictionary.

360 PUBLIC Develop
In general, every text that is used in EndUserText annotations is translated into every relevant language by the
SAP translation process, along with the labels that are given to the data elements.
For more information on how to integrate information for the end user in your data model, refer to Adding Field
Labels and Descriptions [page 774].
Adding Labels for Elements with Selection Fields
In our flight scenario, we have equipped the CDS elements with UI annotations to display them adequately in
the UI, which means that all elements are already represented with a meaningful label.
However, there is one use case where EndUserText labels are necessary to ensure coherence on the UI.
Whereas @UI.listItem and @UI.identification offer the option to directly label list items and object
page items with UI annotations, the @UI.selectionField annotation lacks this option. The selection field
label is therefore retrieved from the database label and might not match the label we have given to the list item
and the identification. In this case, it is useful to apply the @EndUserText annotations to those elements that
represent selection fields to provide consistency.
 Example
In the CDS view /DMO/I_Connection_R, we defined two selection fields that are labeled differently than
the corresponding list item. We use the @EndUserText annotation to acquire matching labels.
{...

@UI: {
lineItem: [ { position: 30, label: 'Departure Airport Code' } ],
identification:[ { position: 30, label: 'Departure Airport Code' } ] }
@EndUserText.label: 'Departure Airport Code' //*** Use the same
label as in lineItem
@UI: {
lineItem: [ { position: 40, label: 'Destination Airport Code'} ],
identification:[ { position: 40, label: 'Destination Airport Code' } ] }
@EndUserText.label: 'Destination Airport Code' //*** Use the same
label as in lineItem

… }
Integrating the Mouse Over Function
If you want additional and longer information about an element, you can use the annotation
@EndUserText.quickInfo: <text> to display a text when hovering over the element.
 Note
If you do not define a tooltip in CDS, the mouse over text displays the short description of the data element
in ABAP Dictionary.

Develop PUBLIC 361
Mouse over displaying long text of data element
To change the text of the mouse over, use the tooltip.
 Example
@UI: {

lineItem: [ { position: 10, label: 'Airline' } ],
identification:[ { position: 10, label: 'Airline' } ] }
@EndUserText.quickInfo: 'Airline that operates the flight.'

Mouse over displaying tooltip of CDS annotation
Related Information
Adding Field Labels and Descriptions [page 774]
4.2.1.4 Displaying Text for Unreadable Elements

Use text associations to add readable texts to short forms or identifiers.
Data that is stored in databases is usually kept as short as possible and consequently, many words are
shortened or abbreviated with a character code. While this is convenient for storage reasons, it becomes a
problem on the UI as the elements might then not be understandable anymore. The following figure displays a
UI screen with airline codes that are not commonly known and which makes it difficult (or impossible) to use
the app.
In our use case, the airline is abbreviated with the two letter airline code.

362 PUBLIC Develop
The full name of the airline is given in the CDS view /DMO/I_Carrier based on the database /DMO/carrier.
Using a text association, you can establish a link from the connection CDS view to the carrier CDS view and
adopt the names of the airlines as an addition to the airline codes in the UI. This requires the use of annotations
from the domains @semantics and @ObjectModel to mark the names as readable text and to assign the text
addition to the airline code elements.
For more detailed information about text elements, refer to Working with Text Elements [page 891].
Getting Airline Names through a Text Association
Prerequisites
A text provider view already exists. In our case, the CDS view /DMO/I_Carrier contains the relevant text
element Name.
Context
The readable names of the airlines can be displayed in the UI together with the two letter code. The text is taken
from the text provider view /DMO/I_Carrier that contains the airline code as well as the readable name of the
airline. We want to display the text for the airlines on the list report page and on the object page. This is why
we need to implement the text association for both views, /DMO/I_Connection_R and /DMO/I_Flight_R.
Apart from an association with the text provider view, the text element in that view needs to be specified as
text with an @Semantics annotation. In addition, the element with the airline code in the source view must be
annotated to assign the text from the associated view to the element.
Procedure
1. Open the CDS view /DMO/I_Carrier. Use the annotation @Semantics.text: true on the element
Name to identify the annotated element as a text and activate the view.
...

define view entity /DMO/I_Carrier
{
@Semantics.text: true

}
 Note
In general, you can annotate more than one view field as a text field. However, only the first annotated
field is respected in the text consumer view for OData exposure.

Develop PUBLIC 363
2. Open the CDS view /DMO/I_Connection_R, for which you want to display the text. Implement an
association to the CDS view /DMO/I_Carrier with the join condition on AirlineID. This association
serves as a text association.
The process how to implement associations is described in Implementing Associations for Existing CDS
Views [page 358].
3. Use the annotation @ObjectModel.text.association: '<_AssocToTextProvider>' on the
element AirlineID and reference the association _Carrier as a text association. Then activate the
CDS view.
...

association [1..*] to /DMO/I_Flight_R as _Flight on
$projection.AirlineID = _Flight.AirlineID
and
$projection.ConnectionID = _Flight.ConnectionID
association [1] to /DMO/I_Carrier as _Airline on $projection.AirlineID
= _Airline.AirlineID{
...
@ObjectModel.text.association: '_Airline'
...
/*Association*/
_Airline

}
4. Open the CDS view /DMO/I_Flight_R for which you also want to display the text. Use the annotation
@ObjectModel.text.association: '<_AssocToTextProvider>' on the element AirlineID and
reference the association _Airline as a text association. Then activate the CDS view.
...

association [1] to /DMO/I_Carrier_R as _Airline on
$projection.AirlineID = _Airline.AirlineID
{
...
@ObjectModel.text.association: '_Airline'
...
/*Association*/
_Airline

}
5. Activate all changed CDS views.
Results
You have established a text association from the two CDS views that contain the two-letter airline code. The
text is taken from the text provider view and is displayed in the UI together with the two-letter code, as can be
seen in the following image. Now, the airlines are clearly identifiable by their full names.

364 PUBLIC Develop
 Note
You can also establish a text association with the CDS view /DMO/I_Airport to provide a full text for the
airport elements Departure Airport Code and Destination Airport Code.
Related Information
Working with Text Elements [page 891]
4.2.1.5 Providing Value Help for the Selection Fields
Use value helps to make it easier to find the correct value for selection fields on the UI.
We created some selection fields for the UI to enable the end user to find a suitable flight in the flight app.
The difficulty, however, is to know the correct three letter airport code to determine the correct departure or
destination airport for a flight. You can enable a value help option to assist the end user in finding correct
values. The end user then gets direct access to a value help dialog in which he or she can enter values, such as
city names or country codes, to find the suitable airport code. This is shown in the following figure.

Develop PUBLIC 365
Adding Annotations for Value Help
Prerequisites
A value help provider view already exists. In our case, the CDS view /DMO/I_Airport contains the relevant
fields Name, City and CountryCode to help find the airport code.
Context
To provide a value help for the selection fields of the elements Departure Airport Code
and Destination Airport Code in the CDS view /DMO/I_Connection_R, use the annotation
@Consumption.valueHelpDefinition.
Procedure
1. Open the CDS view /DMO/I_Connection_R.

2. Annotate the elements Departure Airport Code and Destination Airport Code.
You want to equip these elements with a value help dialog with the annotation
@Consumption.valueHelpDefinition: [{ entity: { name: '<target_view>' , element:

366 PUBLIC Develop
'<target_element>' }}]. In our case, the target view is /DMO/I_Airport with the target element
AirportID , which works as the binding condition for both elements in the source view. .
{...

@Consumption.valueHelpDefinition: [{ entity: { name: '/DMO/
I_Airport',
element: 'AirportID' } }]
airport_from_id as DepartureAirport,
...
I_Airport' ,
element:
'AirportID' } }]
airport_to_id as DestinationAirport,

…}
 Note
For the value help, you do not need to establish an association between the source and the target view.
Nevertheless, you need to make sure that the target view is part of the service.
If not already done, add the value help provider view to the service definition.
Results
You have implemented a value help for the selection fields that refer to the airport code elements. Clicking
opens the value help dialog with the option to use all the elements of the value help provider view /DMO/
I_Airport to find the correct three letter airport code (see the image above). Additionally, the selection fields
are now equipped with a value completion option. This means that, once you start typing in the selection field,
the possible values are displayed. This is shown in the following figure:
Value completion option
Related Information
Consumption Annotations [page 1195]

Providing Value Help [page 776]

Develop PUBLIC 367
4.2.1.6 Adding Search Capabilities
Include a search input field to execute a text and fuzzy search on multiple elements.
Prerequisites
The CDS view must be suitable for text and fuzzy search enabling. For more information, take a look at the
corresponding topics in the SAP HANA Search Developer Guide.
Context
In the previous chapter, you implemented a value help for the selection fields, which are based on airport code
fields. This means you can easily search for connections from and to certain airports. However, it is not possible
to search for connections by specific airlines or flights that are operated on a specific day. Maybe the end user
even wants to search for values of different elements, say someone wants to find out which connections are
available to or from Frankfurt on, say, February 18, 2019. This is exactly the use case when search capabilities
are required.
You use annotations to enable search capabilities for a specific CDS view and also to mark the elements that
you want to be included in the search scope. You can also define fuzziness thresholds for the search, so that
entries are also found if the values are entered in the search field with incorrect spelling. This makes the search
easier and more effective.
The following section explains the process used to implement search capabilities when the end user wants to
search for the following:
• Connections operated by one or more certain airlines

• Connections on one or more certain days
• Connections with one or more plane types
• Or a combination of any of these.
Whereas the first two searches operate only on the CDS view /DMO/I_Connection_R (because the search
target elements Airline, Departure Airport Code and Destination Airport Code are part of this
view), the searches for days and plane types require the search to be operated on the associated view, since
the elements Flight Date and Plane Type are part of /DMO/I_Flight_R. In addition, we also want to
be able to search for the full airline name. That is why the text provider view /DMO/I_Carrier must also be
search enabled.
Procedure
1. Enable the relevant elements for searches in /DMO/I_Connection_R

a. Open the CDS view /DMO/I_Connection_R.

368 PUBLIC Develop
b. Use the annotation @Search.searchable: true on the entity level to enable the CDS view for
searches and to expose a standard search field on the UI.
 Note
If you use this annotation in a CDS view, you have to assign at least one default search element.

@Search.searchable: true //*** exposes a standard search field on
the UI
...

c. Choose the elements that you want to search for and annotate them with
@Search.defaultSearchElement: true.
d. Define a fuzziness threshold for the searchable elements with @Search.fuzzinessThreshold:
<fuzziness_value>.
 Note
You can set a fuzziness threshold of 0 to 1. SAP recommends that you use 0.7 to begin with.
This means that every item with a 70% match and greater is found. You can then customize the
threshold.
The search elements in the connection view are Airline, Departure Airport Code, and
Destination Airport Code. As the first one only consists of a two letter code, you do not need to
define a fuzziness threshold for this element.
{

…
@Search.defaultSearchElement: true
…
@Search.fuzzinessThreshold: 0.7
…

… }
e. Annotate the association _Flight with @Search.defaultSearchElement: true to enable the

search for elements in the associated view.
{…

_Flight,

… }
f. Activate the CDS view.
Now the end user can search for connections by specific airlines or to or from a specific airport. The
following figure illustrates the connections operated by SQ (Singapore Airlines Limited).

Develop PUBLIC 369
2. For our use case, we not only want to search for elements in the main view of the app, but also for the
fields of the associated view. Enable the relevant elements for search in /DMO/I_Flight_R. As previously
described, open the CDS view /DMO/I_Flight_R, mark it as search enabled, and then choose the
elements to search on with a proper fuzziness threshold.

@EndUserText.label: 'Read-Only E2": Data Model Flight'
@Search.searchable: true
{…

… }
The association is now search enabled. This means it is possible to search for connections with a specific
plane type and at a specific airport at the same time, even though the elements are not part of the same
view. The following figure displays the search results for the search for the machine with the code A380
and the airport with the code FRA.
3. Enable the relevant elements for searches in /DMO/I_Carrier to be able to search for the full airline
names and not only for the two letter code. As previously described, open the CDS view /DMO/I_Carrier,
mark it as search enabled, and then choose the elements to search on with a proper fuzziness
threshold.

@EndUserText.label: 'Read-Only E2E: Data Model Carrier'
define view entity /DMO/I_Carrier_R
{…

… }

370 PUBLIC Develop
The text association now enables the end user to search for the full names of airlines, even though the full
name element Name is not exposed on the UI. Even if the full name is not complete in the search field, the
search still presents the right results, as can be seen in he following figure.
Related Information
Enabling Text and Fuzzy Searches in SAP Fiori Apps [page 897]
4.2.2 Developing Managed Transactional Apps
In this chapter, you will be guided through all steps necessary to develop a travel administration app based on
the business object’s managed runtime infrastructure.
Introduction
Let's assume you want to develop completely new transactional apps for SAP Fiori UI or for an arbitrary
Web API consumer. Let's further assume that you don't have any transactional buffer or business logic
implementation or authorization functionality available to you.
In that situation you can benefit from the managed implementation type of the ABAP RESTful application
programming model.
The managed implementation type addresses use cases where all essential parts of an application must be
developed from scratch. However, these new applications can highly benefit from out-of-the-box support
for transactional processing. Standard operations (create, update, delete) must only be specified in the
behavior definition to obtain a ready-to-run business object. In addition the provisioning and handling of the
transactional buffer is automatically done for you. The technical implementation aspects are taken over by
the managed RAP BO provider. The interaction phase and the save sequence are implemented generically.
The application developer can then focus on business logic that is implemented using actions, validations and
determinations and user interaction. The corresponding transactional engine manages the entire life cycle of
your business object and covers all aspects of your business application development.

Develop PUBLIC 371
The architecture for a managed scenario can be depicted as in the simplified figure below.
The new implementation of business objects and their functionality is a key component in the architecture.
In addition to the generic implementation of transactional handling, these objects also provide the application-
specific business logic. Even with new developments, you will certainly always use already available reuse
functionality whenever possible. For example, our demo application uses value help views and text views for
text information retrieval, currency conversion procedures, and message constants as reuse components.
Architecture Overview - Managed Implementation
Prerequisites

 Restriction

372 PUBLIC Develop
 Remember
However, if you want to recreate all development objects of this demo content, make sure that you use
different names from this documentation.
Involved Development Objects
The figure below provides an overview of the main development objects involved when creating new
transactional apps based on the managed implementation type.

Develop PUBLIC 373
Development Objects Involved When Implementing Managed Transactional Apps
Development Process in Overview
The development of new managed applications mainly requires developers to perform the following
fundamental activities:
1. Developing Ready-to-Run Business Objects

In this section, you will create, from scratch, all the components of your application required to run ready-to-
run business objects. Using the business object framework for managed implementation type, you will save
time during the development cycle because you don't have to implement all the technical details yourself
- details such as low-level transaction handling, buffer management, or business logic orchestration. This
framework provides a set of generic services and functionalities to speed up, standardize, and modularize your
development.
More on this: Developing a Ready-to-Run Business Object [page 380]

374 PUBLIC Develop
2. Developing Business Logic
Using model-driven development approach, you may focus your attention more on the actual business
requirements themselves by developing actions, validations, determinations and providing feature control for
each entity of the business object structure.
More on this: Developing Business Logic [page 394]
3. Providing Projection Layer for Service Consumption
To enable a flexible consumption of the resulting business service, a projection is introduced as a separate layer
within the application development. This layer is required for service projections for different consumption
scenarios such as Web APIs and UI-related services according to Fiori UI role-based design.
This essentially includes three steps: providing a data model with CDS views for projections, modeling behavior
definitions for projections as well as defining business services that expose projections for consumption.
More on this: Developing a Projection Layer for Flexible Service Consumption [page 456]
4. Testing the OData UI Service
Using ABAP Development Tools, you have the option of publishing the service to the service repository of your
local system. As soon as the service is published, it is ready for consumption through an OData client, such as
an SAP Fiori app. The service binding editor also offers a preview tool that you can use for testing the resulting
app within your ABAP development environment.
More on this: Testing the Business Object [page 392]
4.2.2.1 Reference Business Scenario
In this demo scenario, we will implement a simple travel provider app that can be used to manage flight
bookings. A single travel should be booked by the travel provider for an existing customer through a travel
agency and include one or multiple flight bookings. In addition, one or more supplements should be able to be
booked for each flight.
Requirements
Based on the same data model, two different views of the travel app are to be realized, each corresponding to
two different user roles:
• The processor acquires all the data relevant to flight bookings: he or she creates individual travel
instances, creates and manages individual flights, and adds supplements to flight bookings. The
accumulated travel costs should be calculated automatically when the underlying bookings are updated.
When editing individual travel data, validation must be made for data consistency and, in the case of an
error, be issued as an appropriate message to the user.

Develop PUBLIC 375
List of Travels - UI for Processor Role
Creating a Travel - UI for Processor Role

• The role of the approver is limited to the verification of the recorded travel data entered by the processor.
The approver has the option to accept or reject individual travels.
List of Travels - UI for Approver Role
Data Model
Entities for Transactional Data
As depicted in the figure below, the 3-tier entity hierarchy for managing transactional data in our scenario
consists of the following editable entities, with a 1: N cardinality on each level:
• Travel

376 PUBLIC Develop
• Booking
• BookingSupplement
That is, each travel instance has 0..N bookings and each booking has 0..N booking supplements.
The figure below shows the composition relationship between the travel, the (flight) booking and the
supplement entities, where the travel entity represents the root of the data model.
Editable Entities of the Data Model
Additional Entities for Master Data (Reuse Components)

To access business data from other entities in our demo content, we are going to reuse master data from the
package /DMO/FLIGHT_REUSE that is part of the downloaded demo content /DMO/FLIGHT. Some of these
entities will be used primarily as text provider views for retrieving text information and as value help provider
views for individual input fields on the UI.

Develop PUBLIC 377
Non-Editable Entities Reused in the Data Model
Behavior
In the following table, we briefly outline the scope of the business logic to be implemented in the demo
scenario. Bear in mind that the managed implementation type comes into play with a few new concepts such
as validations and determinations, which will be introduced later on over the course of this E2E guide.
Processor Role:
Processor
Entity Behavior
Travel Operations:
• Create, update, delete

• Create bookings by association
• Action: copy travels
Validations:
• Validate editable input fields
Feature Control:
• Static and dynamic field control

• Dynamic operation control
• Dynamic action control

378 PUBLIC Develop
Entity Behavior
Booking Operations:
• Update
• Create booking supplements by association
Validations:
• Validate editable input fields
Determinations:
• Calculate total price for bookings
Feature Control:

• Dynamic operation control
Booking Supplement Operations:
• Update
Determinations:
• Calculate total price for supplements
Feature Control:
Approver Role:
Approver
Entity Behavior
Travel Operations:
• Update (on limited set of travel fields)

• Action: accept travel
• Action: reject travel
Validations:
• Validate editable fields
Feature Control:

• Dynamic action control
Booking Read operations only

Develop PUBLIC 379
Restrictions
 Restriction
The current version of the ABAP RESTful programming model does not support late numbering for
managed implementation type. Therefore, in our demo scenario, the numbering is not implemented in the
save sequence using the adjust_numbering( ) method when creating instances for travels, bookings,
and booking supplements.
4.2.2.2 Developing a Ready-to-Run Business Object
Each business object is characterized by a structure, a behavior and a runtime implementation.
As shown in the figure below, the structure of a business object is defined by the sequence of compositions
and to-parent associations between CDS entities with a root entity on top of the composition tree. Each level of
a business object’s composition tree can offer a set of operations that are specified in the behavior definition
that refers to the entities of the CDS data model. In the case of managed implementation type, the standard
operations (create, update, delete) must only be specified in the behavior definition to obtain a ready-to-run
business object. The business object runtime infrastructure already implements the interaction phase and the
save sequence generically and provides an out-of-the-box support for transactional processing.
Data Model and Behavior of a Ready-to-run Business Object

380 PUBLIC Develop
Preview: Resulting Business Object in Relation Explorer
The figure below displays the resulting “Travel” business object in Relation Explorer view. If you choose the
Business Object context, the Relation Explorer provides the composition tree of the business object and
displays all operations of the selected entity.
"Travel" Business Object in Relation Explorer
Activities Relevant to Developers
1. Providing Business Object Structure [page 381]

1. Providing Persistent Tables [page 383]
2. Creating CDS Data Definitions [page 385]
3. Defining Data Model and Business Object Structure [page 386]
2. Defining Elementary Behavior for Ready-to-Run Business Object [page 390]
3. Testing the Business Object [page 392]
4.2.2.2.1 Providing Business Object Structure
From a structural point of view, a business object consists of a tree of entities that are linked by compositions.
Every entity in this composition tree is an element that is modeled with a CDS entity.
For our demo travel booking scenario, we will implement a 3-level hierarchy composition tree.
consists of the following editable entities, with a 1: N cardinality on each level:
• Travel
• Booking
That is, each travel instance has 0..N bookings and each booking has 0..N booking supplements.
The figure below shows the composition relationship between the travel, the (flight) booking and the
supplement entities, where the travel entity represents the root of the data model.

Develop PUBLIC 381
Editable Entities of the Data Model
Additional Entities for Master Data (Reuse Components)
To access business data from other entities in our demo content, we are going to reuse master data from the
package /DMO/FLIGHT_REUSE that is part of the downloaded demo content /DMO/FLIGHT. Some of these
entities will be used primarily as text provider views for retrieving text information and as value help provider
views for individual input fields on the UI.
 Note
Additional entities for currencies (I_Currency) and countries (I_Country) are generally available in your
system and are included in our data model using associations.

382 PUBLIC Develop
Related Information
Providing Persistent Tables [page 383]

Creating CDS Data Definitions [page 385]
Defining Data Model and Business Object Structure [page 386]
4.2.2.2.1.1 Providing Persistent Tables
Travel data of our demo application is distributed across multiple database tables: a table for the travel header
data, a table for flight bookings, and booking supplements.
To build up our demo scenario from scratch, we will first create a suitable set of database tables using ADT
ABAP Dictionary tools and then use these tables as a data source in the new CDS-based data model.
The standard use case is to work with client-dependent tables. That means, the database table has a key
field in which the client is maintained. Like this, you can control the access to the database entries based on
the client. However, there are use cases in which the instances of the database tables are not client-specific.
These tables do not contain a client field. The RAP managed BO runtime also supports scenarios with client-
independent database tables. For more information, see Using Client-Independent Database Tables [page 217].
All RAP applications need administrative fields to log data access and modification. The RAP framework offers
reuse data elements for these fields, see RAP Reuse Data Elements [page 210].
Procedure: Creating Tables
To create and work with database tables in ABAP Development Tools (ADT), do the following:
1. Open the source-based ABAP Dictionary editor in ADT and create the corresponding database tables listed
below. For further information, see: .
2. Edit the database tables with the fields and metadata as depicted in the listings below.
3. Activate the tables
Table /DMO/TRAVEL_M: Persistent Table for Managing Travel Data
This table defines general travel data, such as the key element travel ID, agency ID or customer ID, the date for
travel’s begin and end, as well as the overall status of the travel bookings, and the total price of an individual
travel. In addition, the fields for standard administration data, such as the respective user or the time of
creation, are added to the table.
 Expand the following code sample to view the source code of database table /dmo/travel_m.
 Sample Code

Develop PUBLIC 383

define table /dmo/travel_m {
@Semantics.amount.currencyCode : '/dmo/travel_m.currency_code'
@Semantics.amount.currencyCode : '/dmo/travel_m.currency_code'
created_by : abp_creation_user;
created_at : abp_creation_tstmpl;
last_changed_by : abp_locinst_lastchange_user;
last_changed_at : abp_locinst_lastchange_tstmpl;

}}
Table /DMO/BOOKING_M: Persistent Table for Managing Bookings
This table will be used for managing flight booking data, such the flight connection, the carrier, or the price and
flight date, and finally, the status of flight bookings.
 Expand the following code sample to view the source code of database table /dmo/booking_m.
 Sample Code
@EndUserText.label : 'Flight Reference Scenario: Booking'

define table /dmo/booking_m {
@AbapCatalog.foreignKey.label : 'Travel'
@AbapCatalog.foreignKey.screenCheck : false
key travel_id : /dmo/travel_id not null
with foreign key [0..*,1] /dmo/travel_m
where travel_id = /dmo/booking_m.travel_id;
booking_date : /dmo/booking_date;
carrier_id : /dmo/carrier_id;
connection_id : /dmo/connection_id;
flight_date : /dmo/flight_date;
@Semantics.amount.currencyCode : '/dmo/booking_m.currency_code'
flight_price : /dmo/flight_price;
booking_status : /dmo/booking_status;

}

384 PUBLIC Develop
Table /DMO/BOOKSUPPL_M: Persistent Table for Managing Booking
Supplement Data
This table is used to add additional products to a travel booking. For example, the customer can book together
with a flight, a drink or a meal.
 Expand the following code sample to view the source code of database table /dmo/booksuppl_m.
 Sample Code
@EndUserText.label : 'Flight Reference Scenario: Booking Supplement'

define table /dmo/booksuppl_m {
@AbapCatalog.foreignKey.label : 'Travel'
key travel_id : /dmo/travel_id not null
with foreign key [0..*,1] /dmo/travel_m
where travel_id = /dmo/booksuppl_m.travel_id;
@AbapCatalog.foreignKey.label : 'Booking'
key booking_id : /dmo/booking_id not null
with foreign key [0..*,1] /dmo/booking_m
where travel_id = /dmo/booksuppl_m.travel_id
and booking_id = /dmo/booksuppl_m.booking_id;
key booking_supplement_id : /dmo/booking_supplement_id not null;
supplement_id : /dmo/supplement_id;
@Semantics.amount.currencyCode : '/dmo/booksuppl_m.currency_code'
price : /dmo/supplement_price;

}
4.2.2.2.1.2 Creating CDS Data Definitions
In this step you create CDS views as the basis for the data model of our demo scenario. For each data definition
a corresponding development object and the related CDS views are created.
Data Definitions and CDS Views to Create
 Note
Naming CDS views: Since CDS views are (public) interface views, they are prefixed with I_ in accordance
with the VDM (virtual data model) naming convention. In addition, we add the suffix _M to the view name
in case it is specific for our managed implementation type scenario. For detailed information, see: Naming
Conventions for Development Objects [page 306]

Develop PUBLIC 385
Data Definitions Required for all Editable Entities of the Data Model
Data Definition
CDS View Name Data Source Description
/DMO/I_TRAVEL_M /DMO/ A Travel entity defines general travel data, such as the agency
TRAVEL_M ID or customer ID, overall status of the travel bookings, and the
/DMO/I_Travel_M (root entity)
total price of a travel.
(DB table)
/DMO/I_BOOKING_M /DMO/ The booking entity is used for managing flight booking data,
BOOKING_M such as the customer, the flight connection, or the price and
/DMO/I_Booking_M (child entity)
flight date.
(DB table)
/DMO/I_BOOKSUPPL_M /DMO/ This entity is used to add additional products to a travel booking.
/DMO/I_BookSuppl_M (child en- BOOKSUPPL_

tity) M
(DB table)
Procedure: Creating a Data Definition
To launch the wizard tool for creating a data definition, do the following:
1. Launch ABAP Development Tools.

2. In your ABAP project (or ABAP cloud project), select the relevant package node in Project Explorer.
3. Open the context menu and choose New Other ABAP Repository Object Core Data Services Data
Definition
Further information: (Tool Reference)
4.2.2.2.1.3 Defining Data Model and Business Object

Structure
Travel Root View /DMO/I_Travel_M
For the root CDS view /DMO/I_Travel_M, the database table /dmo/travel_m serves as the data source. This
CDS view defines the root entity of the managed business object and represents the root of compositional
hierarchy for the travel business object to be created.
To define a composition relationship from the root to a child entity, the keyword COMPOSITION is used. In
our example, we specify the /DMO/I_Booking_M as child entity in the composition _Booking. As a result,

386 PUBLIC Develop
the booking node is defined as a direct child entity to the business object’s root. The cardinality [0 .. *]
specifies that any number of booking instances can be assigned to each travel instance.
To be able to access master data from other entities, a set of associations is defined in the CDS source code.
These associations refer to CDS entities that are part of our demo application scenario. Some of these views
are used primarily as text views for retrieving text information and as value help provider views for specific UI
fields.
Finally, the fields for standard administration data are added to the select list, where the persistent field
last_changed_at plays a special role as a field ETag.
To ensure uniform data processing on the consumer side, all administrative as well as quantity fields are
provided with appropriate @Semantics annotations. These annotations are necessary to support managed
ETag handling, that is the automatic update of the relevant ETag field on every operation.
 Expand the following code sample to view the source code of the CDS Root View /DMO/I_Travel_M.
 Sample Code

@EndUserText.label: 'Travel view - CDS data model'
define root view entity /DMO/I_Travel_M
as select from /dmo/travel_m as Travel -- the travel table is the data
source for this view
composition [0..*] of /DMO/I_Booking_M as _Booking
association [0..1] to /DMO/I_Agency as _Agency on
$projection.agency_id = _Agency.AgencyID
association [0..1] to /DMO/I_Customer as _Customer on
$projection.customer_id = _Customer.CustomerID
association [0..1] to I_Currency as _Currency on
$projection.currency_code = _Currency.Currency
association [1..1] to /DMO/I_Overall_Status_VH as _OverallStatus on
$projection.overall_status = _OverallStatus.OverallStatus
{
key travel_id,
agency_id,
customer_id,
begin_date,
end_date,
booking_fee,
total_price,
currency_code,
overall_status,
description,
created_by,
created_at,
last_changed_by,
//local ETag field --> OData ETag
last_changed_at,
/* Associations */
_Booking,
_Agency,
_Customer,
_Currency,
_OverallStatus
}


Develop PUBLIC 387
Booking View /DMO/I_Booking_M
Listing 2 (below) provides you with a data model implementation of the booking entity. All fields that are
declared in the database table are used in the CDS view. The administrative field last_changed_at is used for
optimistic concurrency control on all nodes. That means, every business object entity stores its own eTag.
In the data definition of the root entity /DMO/I_Travel_M, we specified the booking entity /DMO/
I_Booking_M as a composition child entity. Reversely, this relationship requires an association to their
compositional parent entity – from the child entity. This relationship is expressed by the keyword
ASSOCIATION TO PARENT.
To provide a data model for 3-tier entity hierarchy, we also define a composition relationship from booking
to a booking supplement entity. In our example, we specify /DMO/I_BookSuppl_M as child entity in the
composition _BookSupplement. The cardinality [0 .. *] expresses that any number of booking supplement
instances can be assigned to each booking instance.
To be able to access data from other entities, a set of additional associations is defined in the CDS source code.
The SELECT list includes all elements of a booking entity that are relevant for consumption in a user interface.
 Expand the following code sample to view the source code of CDS View /DMO/I_Booking_M.
 Sample Code

//@Metadata.ignorePropagatedAnnotations:true
@EndUserText.label: 'Booking view'
define view entity /DMO/I_Booking_M
as select from /dmo/booking_m as Booking
association to parent /DMO/I_Travel_M as _Travel on
$projection.travel_id = _Travel.travel_id
composition [0..*] of /DMO/I_BookSuppl_M as _BookSupplement
$projection.customer_id = _Customer.CustomerID
association [1..1] to /DMO/I_Carrier as _Carrier on
$projection.carrier_id = _Carrier.AirlineID
association [1..1] to /DMO/I_Connection as _Connection on
$projection.carrier_id = _Connection.AirlineID
and
$projection.connection_id = _Connection.ConnectionID
association [1..1] to /DMO/I_Booking_Status_VH as _BookingStatus on
$projection.booking_status = _BookingStatus.BookingStatus
{
key travel_id,
key booking_id,
booking_date,
customer_id,
carrier_id,
connection_id,
flight_date,
flight_price,
currency_code,
booking_status,
last_changed_at,
/* Associations */
_Travel,
_BookSupplement,
_Customer,
_Carrier,

388 PUBLIC Develop
_Connection,
_BookingStatus
}

Booking Supplement View /DMO/I_BookSuppl_M
The 3-tier composition relationship requires an association for the booking supplement child entity /DMO/
I_BookSuppl_M entity to their compositional parent entity.
Like the booking entity, the booking supplement entity also uses the field last_changed_at to store eTag
values.
To access master data from other entities, additional associations are defined in the CDS source code.
 Expand the following code sample to view the source code of CDS View /DMO/I_BookSuppl_M.
 Sample Code

@EndUserText.label: 'Booking Supplement View - CDS data model'
define view entity /DMO/I_BookSuppl_M
as select from /dmo/booksuppl_m as BookingSupplement
association to parent /DMO/I_Booking_M as _Booking on
$projection.travel_id = _Booking.travel_id
and
$projection.booking_id = _Booking.booking_id
association [1..1] to /DMO/I_Travel_M as _Travel on
$projection.travel_id = _Travel.travel_id
association [1..1] to /DMO/I_Supplement as _Product on
$projection.supplement_id = _Product.SupplementID
association [1..*] to /DMO/I_SupplementText as _SupplementText on
$projection.supplement_id = _SupplementText.SupplementID
{
key travel_id,
key booking_id,
key booking_supplement_id,
supplement_id,
price,
currency_code,

last_changed_at,
/* Associations */
_Travel,
_Booking,
_Product,
_SupplementText
}


Develop PUBLIC 389
4.2.2.2.2 Defining Elementary Behavior for Ready-to-Run
Business Object
In this step, we focus on modeling an elementary behavior in which only the standard operations create(),
update(), and delete() are defined for each entity. These operations, along with some basic properties
(behavior characteristics), are already sufficient to obtain a ready-to-run business object.
Creating a Behavior Definition /DMO/I_TRAVEL_M
Create the behavior definition by using the creation wizard in ADT. By using the context menu on the root view
entity (/DMO/I_Travel_M), you can directly create a new behavior definition for the complete BO hierarchy.
In the wizard, choose the implementation type Managed. For a detailed description, see .
Modeling the Behavior for the Ready-to-Run Travel BO
As depicted in the codeblock below, the source code of the behavior definition consists of a header information
and three definitions for entity behavior: one for the root travel entity and two for the child entities booking and
booking supplements – corresponding to the composition tree of the business object.
For a detailed syntax description of a behavior definition header, see CDS BDL - CDS behavior definition header
For a detailed syntax description of an entity behavior definition, see CDS BDL - entity behavior definition
The header specifies managed implementation type of our business object’s provider since we are going to
implement all essential parts of an application from scratch.
Whereas for the unmanaged implementation type, the application developer must implement essential
components of the REST contract manually, for the managed scenario, on the other hand, all required standard
operations (create, update, delete) must only be specified in the behavior definition to obtain a ready-to-run
business object. New applications can highly benefit from out-of-the-box support for transactional processing,
since the technical implementation aspects are taken over by the business object runtime infrastructure. In
this case, the business object framework implements generically the interaction phase and the save sequence.
The application developer can then focus on business logic that is implemented using actions, validations,
determinations and user interaction.
The strict mode ensures RAP best practices and up-to-date syntax for the behavior definition and behavior
implementation. For more information, see Strict Mode [page 184].
Our TRAVEL business object refers to the underlying CDS data model, which is represented by root
entity /DMO/I_Travel_M. All data changes related to this entity that result from transactional behavior are
stored in the database table /DMO/TRAVEL_M. This is the reason why this table is referenced as persistent
table. The transactional handling of the business object's root entity travel is mainly determined by the
standard operations create, update, and delete. The fact that in our scenario new instances of the booking
child entity should also be created for a specific travel instance is considered by the addition of the _Booking

390 PUBLIC Develop
association. The keyword {create;} declares that this association is create-enabled what exactly means that
instances of the associated bookings can only be created by a travel instance.
 Note
The create_by_association expects that the parent key fields of the child entity that is to be created
are read-only as the parent key fields are filled automatically during runtime.
The sub node of the TRAVEL business object structure refers to the corresponding data model for bookings
that is represented by the child entity /DMO/I_Booking_M. The transactional handling of booking child
entity is determined by the standard operation update and delete. In addition, the create-enabled association
_BookSupplement is defined for creation of supplements as part of associated booking instances. Similarly,
we model the behavior of the booking supplement entity /DMO/I_BookSuppl_M. Since we reach the end of
the composition tree with this entity, there is no need to define a create-enabled association.
For each entity, the following behavior definitions are relevant:
When providing modifying operations, we also must take care for locking support for all relevant entities of the
composition tree. For this purpose, the root entity travel is defined as lock master and the child entities as
lock dependent. In the latter case, the binding information is specified via the association leading from child
entity instance to its lock master instance. For more information, see Optimistic Concurrency Control [page
33].
In the managed scenario, all entities receive a separate eTag master field to store eTag values. Like this,
every entity can be accessed and modified independently of others. For more information, see Pessimistic
Concurrency Control (Locking) [page 38].
The strict mode requires that authorization is defined for the business object. Although this demo application
only provides a dummy implementation for the authorization, it must be defined for each entity. For more
information, see Authorization Control [page 80].
For the fields that are used in the business object, a mapping prescription describes which fields of the
database tables are to be used as fields in the business object. Since in this scenarios, the field names are the
same, the corresponding operator can be used. For more information, see Using Type and Control Mapping
[page 861].
 Expand the following code sample to view the source code of the Behavior Definition /DMO/I_Travel_M.
 Sample Code

managed;
strict(2);
persistent table /DMO/TRAVEL_M
etag master last_changed_at
lock master
authorization master (global)
{
mapping for /DMO/TRAVEL_M corresponding;
create;
update;
delete;
}
persistent table /DMO/BOOKING_M
lock dependent by _Travel

Develop PUBLIC 391
authorization dependent by _Travel
{
field ( readonly ) travel_id;
mapping for /DMO/BOOKING_M corresponding;
update;
association _BookSupplement { create; }
association _Travel { }
}
define behavior for /DMO/I_BookSuppl_M alias booksuppl
persistent table /DMO/BOOKSUPPL_M
{
field ( readonly ) travel_id, booking_id;
mapping for /DMO/BOOKSUPPL_M corresponding;
update;
association _Booking { }
}

4.2.2.2.3 Testing the Business Object
At this point, you can now test the newly created travel business object for its basic functionality by creating
some new instances for the 3 entities (travel, booking, booking supplement) that correspond to the business
object’s structure, modifying the existing data sets or deleting existing instances.
These options are available to you:
• Testing with Fiori UI by using the integrated Fiori UI preview function

• Testing without Fiori UI:
• By executing automated ABAP Unit tests, starting from a generated test class
• By consuming the newly created business object’s entities with EML.
Procedures
To use the integrated Fiori UI preview, perform the following steps:
1. Add required UI annotations to the relevant CDS views.

Add, at least, the @UI.identification annotation on each element to be editable when creating or
editing entity instances on the Fiori UI object pages.
2. Create the service definition.
3. Specify which CDS entities are exposed as a UI service.
4. Create a service binding for UI consumption.
5. Activate the UI service endpoint in the local service repository.
6. Run the resulting app by using the integrated UI preview function.

392 PUBLIC Develop
 Tip
Since UI annotations are not yet defined in the CDS views provided, you can benefit from the generic
templates by choosing the Settings ( ) button on the (initial) screen that appears. In the Settings
dialog, click on the Select all box for Columns and confirm with OK. Then choose the Go button.
More on this: Creating an OData Service [page 323] and Designing the User Interface for a Fiori Elements App
[page 332]
To generate a test class for an individual entity of the OData service, perform the following
steps:
1. Create the service definition.
2. Specify which CDS entities are to be exposed as a service.
3. Create a service binding for service consumption.
4. Activate the service endpoint in the local service repository.
5. To launch the test class creation wizard, select the relevant entity in the service binding editor and choose
New ABAP Test Class from context menu.
Creating a Test Class for Travel Entity
For the selected entity, the wizard creates a test class with a source code template for ABAP unit tests. After
completing the test code, you can perform CUD operations on relevant entity.
 Note
You can either create a separate test class for each entity or copy and paste the generated code, then
change the name of the entity accordingly for writing ABAP unit tests for other entity.
To test the business object functionality by implementing EML consumer class, you can, for
example, proceed as follows:
1. Create an EML consumer class.
You can use, for example, the source code template from listing below.
2. Implement MODIFY calls for creating, updating, or deleting instances of business object’s entities.
LISTING 1: Template for EML consumer class

CLASS MY_EML_CONSUMER_CLASS DEFINITION
PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.

Develop PUBLIC 393
INTERFACES if_oo_adt_classrun.
PROTECTED SECTION.
PRIVATE SECTION.
ENDCLASS.
CLASS /dmo/cl_eml_travel_update IMPLEMENTATION.
METHOD if_oo_adt_classrun~main.
" To implement the MODIFY call, add EML code here!
ENDMETHOD.
ENDCLASS.

 Tip
To check the results of the MODIFY call implemented in the consumer class, run the main method of the
consumer class by pressing F9 key in the class editor and then search for the created, or updated (and
deleted) travel, booking and booking supplement instances in the data preview tool ( F8 ).
More on this: Entity Manipulation Language (EML) [page 235] and Examples for Accessing Business Objects
with EML [page 240]
4.2.2.3 Developing Business Logic
The managed scenario addresses use cases where all essential parts of an application are to be developed
from scratch. New applications like this can highly benefit from out-of-the-box support for transactional
processing. The corresponding BO runtime manages the entire life cycle of your business objects and covers all
aspects of your business application development.
In a managed scenario, the business object framework implements generically the interaction phase and the
save sequence. You, as an application developer can then focus on business logic that is implemented by
adding actions, validations ad determinations and user interaction.
Preview: Resulting Business Object in Relation Explorer
The figure below displays the resulting "Travel" business object in the Relation Explorer view. If you choose
the Business Object context, the Relation Explorer provides the composition tree of the business object and
displays all operations (including actions), determinations and validations defined by the selected entity.
"Travel" Business Object in Relation Explorer

394 PUBLIC Develop
Contents
4.2.2.3.1 Creating ABAP Classes for Behavior

Implementation
Until this step, we got by without any line of ABAP code. This was also not necessary, as in case of managed
implementation type the technical implementation aspects are taken over by the business object runtime
infrastructure itself. In this case, the business object framework implements generically the interaction phase
and the save sequence.
However, to provide our application with specific business logic, we will on the one hand extend the behavior
definition with actions, feature control, validations and determinations and on the other hand implement it in
ABAP code.
In this step, you create the ABAP classes required for extending behavior artifacts of the corresponding
behavior definition that you created earlier.
In doing so, we apply the contribution pattern and split the behavior implementation into different behavior
pools, one for the travel root entity and the others for the booking and booking supplement child entities
(as shown in figure below). In addition, we will make use of a separate auxiliary class for implementing
helper methods (such as for methods reused in different handlers) that can be reused in each behavior
Splitting Implementation into Different Behavior Pools and Auxiliary Classes

Develop PUBLIC 395
Creating the Behavior Pool /DMO/BP_TRAVEL_M
The behavior definition is directly linked to the implementation class. Therefore, it offers a quick fix to create a
behavior pool with a template for methods to implement the corresponding behavior in the behavior definition.
Create the behavior pool for the travel entity with the following steps:
1. Add the following syntax to the behavior definition in the section of the entity behavior for the travel entity.
implementation in class /dmo/bp_travel_m unique
2. As the behavior pool with the name /dmo/bp_travel_m does not exist yet, the behavior definition offers a
quick fix to create it.
Creating a Behavior Pool via Quick Fix in Behavior Definition
Follow the quick fix to start the wizard for creating an ABAP class.
For a more detailed description, see .
Compared to the standard ABAP class, the generated behavior pool (in our case /DMO/BP_TRAVEL_M)
provides you with an extension FOR BEHAVIOR OF.
New Global Behavior Pool
The real substance of a behavior pool is located in Local Types (there is currently no implementation yet). Here
you can implement special local classes, namely handler classes for additional operations (such as actions),
validations and determinations that are triggered at specific points in time within the interaction phase.
Note that these classes can be instantiated or invoked only by the ABAP runtime environment (virtual
machine)

396 PUBLIC Develop
Creating the Behavior Pool /DMO/BP_BOOKING_M
Create another behavior pool class /DMO/BP_BOOKING_M for the booking entity, by doing the same steps as
described for the travel entity.
CLASS /dmo/bp_booking_m DEFINITION PUBLIC ABSTRACT FINAL FOR BEHAVIOR OF /dmo/

i_travel_m.

ENDCLASS.
CLASS /dmo/bp_booking_m IMPLEMENTATION.

ENDCLASS.
Creating the Behavior Pool /DMO/BP_BOOKINGSUPPLEMENT_M
Create another behavior pool class /DMO/BP_BOOKINGSUPPLEMENT_M for the booking supplement entity as
described for the travel entity.
CLASS /dmo/bp_bookingsupplement_m DEFINITION PUBLIC ABSTRACT FINAL FOR BEHAVIOR

OF /dmo/i_travel_m.

ENDCLASS.
CLASS /dmo/bp_bookingsupplement_m IMPLEMENTATION.

ENDCLASS.
Results
The newly created behavior pools are located in the Behavior Implementations folder of the corresponding
behavior definition node /DMO/I_TRAVEL_M.
Folder Behavior Implementations
4.2.2.3.2 Developing Early Unmanaged Numbering
Early unmanaged numbering is used to automatically assign a key to a BO entity instance during the CREATE
or CREATE-BY-ASSOCIATION. The key assignment is implemented in the FOR NUMBERING method in the
behavior pool.
About Early Unmanaged Numbering
In this demo, early unmanaged numbering is implented for the Travel, Booking and BookingSupplement
business object entities. The early unmanaged numbering method is triggered during the CREATE or CREATE-

Develop PUBLIC 397
BY-ASSOCIATION of a BO entity instance and a key is assigned based on the implementation in the FOR
NUMBERING method. Every assigned key must be unique, otherwise the new instance is rejected by the
database which results in a dump. It is recommended to use a numbering logic which guarantees that every
drawn key is unique and also takes care of locking in case of parallel execution of a CREATE operation.
In this example, the key assignment on root entitiy level is implemented with a Number Range Object,
which guarantees unique keys and a working locking mechanism during the number distribution so that a
number isn't assigned twice. BO subnodes always have a combined key consisting of the keys of the parent
entities and the key of the subnode itself. That's why it's sufficient to guarantee a unique key solely for one
part of the composite key to guarantee that the whole key is unique. In this demo, a number range object
on root entity level guarantees that all composite keys for all subnodes are unique. Consequently, the FOR
NUMBERING implementation for a booking or a bookingSupplement instance only derives the maximum key
already assigned and increases the key count for the current instance.
For more general information about early unmanaged numbering, see Early Numbering [page 24] and for more
details about the FOR NUMBERING method, see <method> FOR NUMBERING [page 28].
4.2.2.3.2.1 Defining Early Unmanaged Numbering
Procedure: Adding Early Unmanaged Numbering to the Behavior Definition
Early unmanaged numbering is always defined on entity level and applied to the CREATE operation of the
respective BO entity. Early unmanaged numbering is applied to all keys of a BO entity. That means that
all keys must be mapped accordingly in the FOR NUMBERING method for all instances as soon as early
unmanaged numbering is defined for a BO entity. The implementation is then called during every CREATE or
CREATE-BY-ASSOCIATION operation to assign keys automatically during a BO instantiation. Since no external
input is required, all key fields are defined as readonly in the behavior definition.
Add early unmanaged numbering to the behavior definition of /DMO/I_TRAVEL_M corresponding to the
following sample:
 Sample Code

managed;
strict(2);
implementation in class /DMO/BP_TRAVEL_M unique
...
early numbering
...
{
...
}
implementation in class /DMO/BP_BOOKING_M unique

398 PUBLIC Develop
early numbering
...
{
...
}
implementation in class /DMO/BP_BOOKINGSUPPLEMENT_M unique
with unmanaged save
early numbering
...
{
field ( readonly ) travel_id, booking_id, booking_supplement_id;
}

4.2.2.3.2.2 Implementing Early Unmanaged Numbering
In this topic, we explain how you can implement early unmanaged numbering for your BO.
Travel
The early unmanaged numbering is implemented in the earlynumbering_create method within the handler
class lhc_travel (local types) of the behavior pool /DMO/BP_TRAVEL_M.
Definition
In the behavior definition, the early unmanaged numbering for the travel entity is defined as follows:

managed;
strict(2);
lock master
early numbering
...
{
...
}

Implementation
The early unmanaged numbering implementation on root node level must always be unique in order to
guarantee unique keys for all child nodes. In this example, a Number Range Object is used to draw the
keys for the travel entity. This guarantees, that every number is assigned only once even when the method is

Develop PUBLIC 399
called from several services simultaneously. The number range can be defined freely - in this implementation,
the count is always increased by 1.
(1) Because the FOR NUMBERING method is called twice in a managed scenario with draft capabilities (once
during the CREATE and once during the save sequence), the implementation includes a mapping for travels
that already have an ID, so that the ID assigned during the CREATE isn’t overwritten during the save sequence.
This is only a preparation step for later draft enablement and not required for an active-only managed BO.
Then travels which already have an ID are deleted from the list of travels. In the subsequent implementation,
IDs are only assigned to travels that didn't have an ID before.
(2) The actual key assignment is implemented using the number range object /DMO/TRV_M. The method
number_get has the following importing parameters:
• nr_range_nr: ID of the intervals that is used to assign the keys.

• object: Name of the number range object.
• quantity: Quantity of required number (number of travels without an ID in entities_wo_travelid)
The method returns the ID that is to be assigned, a return code that indicates if there was a problem with
the numbers drawn and the actual quantity of IDs that were returned. You can implement the error handling
according to your requirements - in this example, any problem with the number range object leads to an
entry in the failed table to abort the CREATE and an error message to provide more details about the error
occurred.
(3) The keys are then assigned and mapped in mapped-travel. If several numbers are requested, the number
always returns the highest number and the starting point of the assignment is calculated by subtracting the
requested number of numbers. The number count is then increased by 1 for each instance.
 Expand the following code sample to view the source code Of early unmanaged numbering for travel.
 Sample Code
CLASS lhc_travel DEFINITION INHERITING FROM cl_abap_behavior_handler

PRIVATE SECTION.
METHODS earlynumbering_create FOR NUMBERING
IMPORTING entities FOR CREATE travel.
ENDCLASS.
CLASS lhc_travel IMPLEMENTATION.
METHOD earlynumbering_create.
DATA:
entity TYPE STRUCTURE FOR CREATE /DMO/I_Travel_M,
travel_id_max TYPE /dmo/travel_id.
" Ensure Travel ID is not set yet (idempotent)- must be checked when BO
is draft-enabled
LOOP AT entities INTO entity WHERE travel_id IS NOT INITIAL.
APPEND CORRESPONDING #( entity ) TO mapped-travel.
ENDLOOP.
DATA(entities_wo_travelid) = entities.
DELETE entities_wo_travelid WHERE travel_id IS NOT INITIAL.
" Get Numbers
TRY.
cl_numberrange_runtime=>number_get(
EXPORTING
nr_range_nr = '01'
object = '/DMO/TRV_M'
quantity = CONV #( lines( entities_wo_travelid ) )
IMPORTING
number = DATA(number_range_key)
returncode = DATA(number_range_return_code)
returned_quantity = DATA(number_range_returned_quantity)

400 PUBLIC Develop
).
CATCH cx_number_ranges INTO DATA(lx_number_ranges).
LOOP AT entities_wo_travelid INTO entity.
APPEND VALUE #( %cid = entity-%cid
%key = entity-%key
%msg = lx_number_ranges
) TO reported-travel.
%key = entity-%key
) TO failed-travel.
ENDLOOP.
EXIT.
ENDTRY.
CASE number_range_return_code.
WHEN '1'.
" 1 - the returned number is in a critical range (specified under
“percentage warning” in the object definition)
%key = entity-%key
%msg = NEW /dmo/cm_flight_messages(
textid = /dmo/
cm_flight_messages=>number_range_depleted
severity =
if_abap_behv_message=>severity-warning )
ENDLOOP.
WHEN '2' OR '3'.
" 2 - the last number of the interval was returned
" 3 - if fewer numbers are available than requested, the return code
is 3
%key = entity-%key
textid = /dmo/
cm_flight_messages=>not_sufficient_numbers
severity =
if_abap_behv_message=>severity-warning )
%key = entity-%key
%fail-cause = if_abap_behv=>cause-conflict
) TO failed-travel.
ENDLOOP.
EXIT.
ENDCASE.
" At this point ALL entities get a number!
ASSERT number_range_returned_quantity = lines( entities_wo_travelid ).
travel_id_max = number_range_key - number_range_returned_quantity.
" Set Travel ID
travel_id_max += 1.
entity-travel_id = travel_id_max .
%key = entity-%key
) TO mapped-travel.
ENDLOOP.
ENDMETHOD.

ENDCLASS.

Develop PUBLIC 401
Booking
The early unmanaged numbering is implemented in the earlynumbering_cba_booking method within the
handler class lhc_travel (local types) of the behavior pool /DMO/BP_TRAVEL_M.
Definition
In the behavior definition, the early unmanaged numbering for the booking entity is defined as follows:
managed;

early numbering
...
{
...

}
Implementation
The number range object for the travel entity guarantees unique keys for the root entity. For booking entities,
the numbering starts from 0 for every travel entity.
(1) With a read-by-association all booking-ids are retrieved.
(2) The highest booking number for the current travel is retrieved.
(3) Bookings that already have an ID are assigned to mapped-booking and no new number is assigned.
Because the FOR NUMBERING method is called twice in a managed scenario with draft capabilities (once
during the CREATE and once during the ACTIVATE), the implementation includes a mapping for bookings with
already have an ID, so that the ID assigned during the CREATE isn’t overwritten during the save sequence. This
is only a preparation step for later draft enablement and not required for an active-only managed BO.
(4) The max_booking_id is increased by 10 for each new booking.
 Expand the following code sample to view the source code Of early unmanaged numbering for booking.
 Sample Code

PRIVATE SECTION.
METHODS earlynumbering_cba_booking FOR NUMBERING
IMPORTING entities FOR CREATE travel\_booking.
ENDCLASS.
METHOD earlynumbering_cba_booking.
DATA: max_booking_id TYPE /dmo/booking_id.
READ ENTITIES OF /DMO/I_Travel_M IN LOCAL MODE
ENTITY travel BY \_booking
FROM CORRESPONDING #( entities )
LINK DATA(bookings).
" Loop over all unique TravelIDs
LOOP AT entities ASSIGNING FIELD-SYMBOL(<travel_group>) GROUP BY
<travel_group>-travel_id.
" Get highest booking_id from bookings belonging to travel
max_booking_id = REDUCE #( INIT max = CONV /dmo/booking_id( '0' )

402 PUBLIC Develop
FOR booking IN bookings USING KEY entity
WHERE ( source-travel_id = <travel_group>-travel_id )
NEXT max = COND /dmo/booking_id( WHEN
booking-target-booking_id > max
THEN
booking-target-booking_id
ELSE max )
).
" Get highest assigned booking_id from incoming entities
max_booking_id = REDUCE #( INIT max = max_booking_id
FOR entity IN entities USING KEY entity
WHERE ( travel_id = <travel_group>-travel_id )
FOR target IN entity-%target
NEXT max = COND /dmo/booking_id( WHEN
target-booking_id > max
THEN
target-booking_id
ELSE max )
).
" Loop over all entries in entities with the same TravelID
LOOP AT entities ASSIGNING FIELD-SYMBOL(<travel>) USING KEY entity
WHERE travel_id = <travel_group>-travel_id.
" Assign new booking-ids if not already assigned
LOOP AT <travel>-%target ASSIGNING FIELD-SYMBOL(<booking_wo_numbers>).
APPEND CORRESPONDING #( <booking_wo_numbers> ) TO mapped-booking
ASSIGNING FIELD-SYMBOL(<mapped_booking>).
IF <booking_wo_numbers>-booking_id IS INITIAL.
max_booking_id += 10 .
<mapped_booking>-booking_id = max_booking_id .
ENDIF.
ENDLOOP.
ENDLOOP.
ENDLOOP.
ENDMETHOD.

ENDCLASS.
Booking-Supplement
The early unmanaged numbering is implemented in the earlynumbering_cba_booksupplem method within

the handler class lhc_travel (local types) of the behavior pool /DMO/BP_BOOKING_M.
Definition
In the behavior definition, the early unmanaged numbering for the bookingsupplement entity is defined as
follows:

managed;
with unmanaged save
early numbering
...
{
}


Develop PUBLIC 403
Implementation
The number range object for the travel entity guarantees unique keys for the root entity. For booking
supplements, the numbering starts from 0 for every bookingSupplement instance.
(1) With a read-by-association all supplement_ids are retrieved.
(2) The highest supplement number for the current booking is retrieved together with the corresponding
travel_id.
(3) Bookings that already have an ID are assigned to mapped-booksuppl and no new number is assigned.
Because the FOR NUMBERING method is called twice in a managed scenario with draft capabilities
(once during the CREATE and once during the ACTIVATE), the implementation includes a mapping for
bookingSupplements that already have an ID, so that the ID assigned during the CREATE isn’t overwritten
during the save sequence. This is only a preparation step for later draft enablement and not required for a
managed BO without draft.
(4) The max_booking_suppl_id is increased by 1 for each new booking.
 Expand the following code sample to view the source code Of early unmanaged numbering for
bookingSupplement.
 Sample Code
CLASS lhc_travel DEFINITION INHERITING FROM cl_abap_behavior_handler.

PRIVATE SECTION.
...
METHODS earlynumbering_cba_booksupplem FOR NUMBERING
IMPORTING entities FOR CREATE booking\_booksupplement.
...
ENDCLASS.
METHOD earlynumbering_cba_booksupplem.
DATA: max_booking_suppl_id TYPE /dmo/booking_supplement_id .
READ ENTITIES OF /dmo/i_travel_m IN LOCAL MODE
ENTITY booking BY \_booksupplement
FROM CORRESPONDING #( entities )
LINK DATA(booking_supplements).
" Loop over all unique tky (TravelID + BookingID)
LOOP AT entities ASSIGNING FIELD-SYMBOL(<booking_group>) GROUP BY
<booking_group>-%tky.
" Get highest bookingsupplement_id from bookings belonging to booking
max_booking_suppl_id = REDUCE #( INIT max = CONV /dmo/
booking_supplement_id( '0' )
FOR booksuppl IN booking_supplements
USING KEY entity
WHERE ( source-travel_id = <booking_group>-travel_id
AND source-booking_id = <booking_group>-booking_id )

NEXT max = COND /dmo/
booking_supplement_id( WHEN booksuppl-target-booking_supplement_id > max
THEN booksuppl-target-booking_supplement_id
ELSE max )
).
" Get highest assigned bookingsupplement_id from incoming entities
max_booking_suppl_id = REDUCE #( INIT max = max_booking_suppl_id
FOR entity IN entities USING KEY
entity
WHERE
( travel_id = <booking_group>-travel_id

404 PUBLIC Develop
AND
booking_id = <booking_group>-booking_id )
FOR target IN entity-%target
NEXT max = COND /dmo/
booking_supplement_id( WHEN target-booking_supplement_id > max
THEN target-booking_supplement_id
ELSE max )
).
" Loop over all entries in entities with the same TravelID and BookingID
LOOP AT entities ASSIGNING FIELD-SYMBOL(<booking>) USING KEY entity
WHERE travel_id = <booking_group>-travel_id
AND booking_id = <booking_group>-booking_id.

" Assign new booking_supplement-ids
LOOP AT <booking>-%target ASSIGNING FIELD-
SYMBOL(<booksuppl_wo_numbers>).
APPEND CORRESPONDING #( <booksuppl_wo_numbers> ) TO mapped-
booksuppl ASSIGNING FIELD-SYMBOL(<mapped_booksuppl>).
IF <booksuppl_wo_numbers>-booking_supplement_id IS INITIAL.
max_booking_suppl_id += 1 .
<mapped_booksuppl>-booking_supplement_id = max_booking_suppl_id .
ENDIF.
ENDLOOP.
ENDLOOP.
ENDLOOP.
ENDMETHOD.

ENDCLASS.
4.2.2.3.3 Developing Actions
An action is assigned to an individual entity of a business object and is used to implement a modifying
non-standard operation as part of the business logic.
This demo scenario implements four actions for the travel entity.
The action acceptTravel sets the overall status of the travel entity to accepted (A). The action
rejectTravel sets the overall status of the travel entity to rejected (X). These actions are instance actions
as there is one specific instance of the travel entity for which the status is changed. They return exactly one
instance, namely the instance on which the action is executed. The result is therefore defined as result [1]
$self.

Develop PUBLIC 405
Accept and Travel Action on the Fiori UI
The action copyTravel copies a travel instance as well as its associated booking and booking supplement
instances and creates new instances based on the copied data. A new travel ID is assigned to the new travel
instance by early unmanaged numbering. This action is an instance factory action as the end user has to select
one instance which serves as the basis for the instance to be created. It returns exactly one instance of the
same entity type the action is assigned for.
Copy Travel Action
The action ReCalcTotalPrice is used to calculate the total price of one travel BO instance, that is one
travel entity instance with all its booking instances and the corresponding booking supplement instances. The
relevant amounts of the booking fee, the flight price and the booking supplement price are added up in the field
total_price of the travel instance. The action is not exposed to the UI, as it is only used internally and called
by determinations, whenever one of the relevant fields is changed. The action does not have a result parameter
so the UI does not navigate to the travel instance whenever the determination is triggered on one of the child
instances.
For more information about actions in general, see Actions [page 101].

406 PUBLIC Develop
1. Defining Actions as Part of the Behavior Definition [page 407]

2. Implementing Actions [page 408]
3. Enabling Actions for UI Consumption [page 414]
4.2.2.3.3.1 Defining Actions as Part of the Behavior Definition
Actions are defined in the behavior definition.
Corresponding to the codeblock below, add the following actions to the behavior definition /DMO/I_TRAVEL_M.
All three actions acceptTravel, rejectTravel, and copyTravel have a similar syntax: they have no input
parameters and the output parameter is the same entity for which the action is executed.
The action ReCalcTotalPrice is an internal action with no result parameter.

...
{
// instance actions
action acceptTravel result [1] $self;
action rejectTravel result [1] $self;
// instance factory action for copying travel instances
factory action copyTravel [1];
// internal action that is called by determinations
internal action ReCalcTotalPrice;
...
}
...
{...
// No actions defined for bookings
}
...
{...
// No actions defined for booking supplements

}

Develop PUBLIC 407
4.2.2.3.3.2 Implementing Actions
In this topic we demonstrate how you can implement the two actions copyTravel and acceptTravel.
Action copyTravel
This action copies a travel instance as well as its associated booking and booking supplement instances and
creates new instances based on the copied data. A new travel ID is assigned to the new travel instance by early
unmanaged numbering.
UI Preview
When we run the final app, the UI screen provides the button Copy Travel for the action as shown in the figure
below.
Accessing the Action on Fiori UI
As soon as the user selects a travel and chooses this button, a copy of the travel instance and its associated
booking and supplement instances are created and persisted in the corresponding database table.
Created Travel Instance
Definition
In the behavior definition, the action copyTravel is defined as follows:

...
{ ...

408 PUBLIC Develop
factory action copyTravel [1];
...

}
Implementing copyTravel Action in the Handler Class

The copyTravel action is implemented in the copyTravel method within the handler class lhc_travel
which is part of the behavior pool /DMO/BP_TRAVEL_M.
The local handler class lhc_travel inherits from class cl_abap_behavior_handler and is automatically
instantiated by the framework.
The signature of the copyTravel method includes the importing parameter keys for referring to the travel
(root) instances, which contains the data to be copied. To identify the root entity, the alias travel is used
- according to the alias that is specified in the behavior definition. The action is then addressed with FOR
ACTION travel~copyTravel.
As given in the listing below, the basic structure of the copyTravel method includes:
• An assertion to ensure that the code is only called for action executions with filled import parameter
%cid, which is mandatory for factory actions. If the consumer doesn't fill %cid the subsequent create-by-
association will fail for all source travel instances that have child instances. Since an initial %cid is a
programming error, an assertion is made.
• EML READ statements that read all fields of the selected travel instance and, if successful, all fields of its
associated booking and booking supplement instances. The selected travel instance is identified by the
importing parameter keys. In case of failure, the entries of the read operation's failed parameter for the
travel instance are directly written to the method's failed parameter. The travel read operation can only
fail if non-existing instance identifiers are imported. This is usually only possible for EML requests. Then
the failed parameter returns the fail cause not_found, which does not need an additional information
in the reported parameter. The read requests for bookings and booking supplements cannot fail for
successful travel read requests; they can only return empty results.
• LOOP statements in which structures and tables for the subsequent create and create-by-
association operations are populated on the basis of the readbooking>-booking_id. "Fill booksuppl
container for creating supplement with cba APPEND VALUE #( %cid = keys[ KEY entity %tky
= <travel>-%tky ]-%cid && <booking>-booking_id && <booksuppl>-booking_supplement_id %data
= CORRESPONDING #( <booksuppl> EXCEPT travel_id booking_id ) ) TO <booksuppl_cba>-%target.
ENDLOOP. ENDLOOP. ENDLOOP. "create new BO instance MODIFY ENTITIES OF /DMO/I_Travel_M
IN LOCAL MODE ENTITY travel CREATE FIELDS ( agency_id customer_id begin_date end_date
booking_fee total_price currency_code overall_status description ) WITH travels CREATE BY \_Booking
FIELDS ( booking_id booking_date customer_id carrier_id connection_id flight_date flight_price
currency_code booking_status ) WITH bookings_cba ENTITY booking CREATE BY \_BookSupplement
FIELDS ( booking_supplement_id supplement_id price currency_code ) WITH booksuppl_cba MAPPED
DATA(mapped_create). mapped-travel = mapped_create-travel . ENDMETHOD. ... ENDCLASS.%cid to
identify the instance, which is to be created. For the travel instance, the %cid the method imports is
used that . The other content identifiers for the booking and booking supplements must be manually
concatenated. In this implementation, the imported %cid is used and the corresponding id of the source
instance is concatenated. The content identifier of the parent instances are then used as values for
%cid_ref for the respective child entities. Some fields for the target instances are handled separately to
meet the requirements for new travels, for example the travel dates that are checked by the validation
validateDates.
• An EML MODIFY statement that creates the travel, booking and booking supplement instances based on
the internal tables populated above. The new travel ID is assigned to the new travel instance by early

Develop PUBLIC 409
unmanaged numbering. The content IDs of the instances and the corresponding keys provided by the
create operations are stored in the mapped_create structure of the MODIFY statement and are mapped
to the determined key values. The modify operation with in local mode is not supposed to fail. Hence, in
this case, there is no need for a failed data container.
• For the method changing parameter mapped-travel, the previously determined structures of the
corresponding operations are assigned. The RAP contract for instance factory actions only allows one
instance to be returned in mapped. Therefore, only the mapping condition for the new travel instance is
returned by the method, but no mapping for the child entities.
 Expand the following code sample to view the source code of Action CopyTravel.
 Sample Code

PRIVATE SECTION.
METHODS copyTravel FOR MODIFY IMPORTING keys FOR ACTION travel~copyTravel
RESULT result.
...
ENDCLASS.
...
METHOD copyTravel.
DATA:
travels TYPE TABLE FOR CREATE /DMO/I_Travel_M\\travel,
bookings_cba TYPE TABLE FOR CREATE /DMO/I_Travel_M\\travel\_booking,
booksuppl_cba TYPE TABLE FOR CREATE /DMO/I_Travel_M\
\booking\_booksupplement.
READ TABLE keys WITH KEY %cid = '' INTO DATA(key_with_inital_cid).
ASSERT key_with_inital_cid IS INITIAL.
ENTITY travel
ALL FIELDS WITH CORRESPONDING #( keys )
RESULT DATA(travel_read_result)
FAILED failed.
ALL FIELDS WITH CORRESPONDING #( travel_read_result )
RESULT DATA(book_read_result).
ALL FIELDS WITH CORRESPONDING #( book_read_result )
RESULT DATA(booksuppl_read_result).
LOOP AT travel_read_result ASSIGNING FIELD-SYMBOL(<travel>).
"Fill travel container for creating new travel instance
APPEND VALUE #( %cid = keys[ KEY entity %tky = <travel>-%tky ]-%cid
%data = CORRESPONDING #( <travel> EXCEPT
travel_id ) )

TO travels ASSIGNING FIELD-SYMBOL(
Action acceptTravel
This action provides the end user with the option of accepting individual travels without switching to EDIT
mode.
UI Preview
If you run the app, the resulting UI screen provides you with the label Accept Travel for the new action - as
shown in the figure below. The action is equipped with feature control. Only if the instance's status is not

410 PUBLIC Develop
already Accepted can the action be executed. For implementation details, see Adding Static and Dynamic
Feature Control [page 415].
Action on Fiori UI
Changed Status as a Result of Action Execution
Definition
Remember, in the behavior definition, the action acceptTravel is defined as follows:

...
{
...
...
}

Implementing acceptTravel Action in the Handler Class
The acceptTravel action is implemented in the set_status_accepted method within the handler class
lhc_travel which belongs to local types component of the behavior pool /DMO/BP_TRAVEL_M.
To update overall_status data of a selected travel instance, the operation UPDATE is specified in the EML
MODIFY statement. Note that the modifying operation takes place in LOCAL MODE. As a result, the update
operation is excluded from the authorization checks (that may be implemented later on). An EML modify
request in local mode for a managed BO provider is not supposed to fail. Therefore, the failed parameter
does not need to be retrieved.
A subsequent EML READ statement provides the instance data for the result of the action.
 Expand the following code sample to view the source code of Action AcceptTravel.

Develop PUBLIC 411
 Sample Code

PRIVATE SECTION.
METHODS set_status_accepted FOR MODIFY IMPORTING keys FOR ACTION
travel~acceptTravel RESULT result.
...
ENDCLASS.
...
METHOD set_status_accepted.
" Modify in local mode: BO-related updates that are not relevant for
authorization checks
MODIFY ENTITIES OF /DMO/I_Travel_M IN LOCAL MODE
ENTITY travel
UPDATE FIELDS ( overall_status )
WITH VALUE #( FOR key IN keys ( %tky = key-%tky
overall_status = 'A' ) ). "
Accepted
" Read changed data for action result
ENTITY travel
ALL FIELDS WITH
CORRESPONDING #( keys )
RESULT DATA(travels).
result = VALUE #( FOR travel IN travels ( %tky = travel-%tky
%param = travel ) ).
ENDMETHOD.

ENDCLASS.
 Tip
The implementation of the rejectTravel action is done in analogy to the acceptTravel action in the
handler class lhc_travel.
Action ReCalcTotalPrice
The action is called by the determinations whenever a relevant amount field is changed to calculate the total
travel price based on the amounts in the relevant instances.
As this action is an internal action that can only be called from inside the business object, it is not exposed to
the UI.
Definition
The action is defined in the behavior definition as follows:

...
{ ...
...

}

412 PUBLIC Develop
Implementing ReCalcTotalPrice
The ReCalcTotalPrice action is implemented in the method with the same name in the handler class
lhc_travel.
The calculation of the total price is done for each travel instance separately. EML READ statements read all the
requested travel instances with their booking fees and currency codes, the associated bookings with their flight
prices and currency codes, and their associated booking supplements with the price and currency codes . A
loop on the result table travels ensures that the amounts are summed for the corresponding travel instance.
In the loop, the prices of all associated bookings and their associated booking supplements are added to the
travel instance's booking fee if it has the same currency code. If the currency code differs the public method for
currency conversion is called to get all flight prices in the currency of the travel's booking fee.
In the end, the calculated total price for the instance is modified via an EML modify statement that update the
travel instance.
 Remember
An EML modify statement in local mode in a managed BO is not supposed to fail. Authorization, feature and
field control is not applied to EML calls in local mode. Therefore, there is no need to retrieve the failed or
reported parameter.
 Expand the following code sample to view the source code of Action ReCalCTotalPrice.
 Sample Code

PRIVATE SECTION.
METHODS recalctotalprice FOR MODIFY
IMPORTING keys FOR ACTION travel~recalctotalprice.
...
ENDCLASS.
...
METHOD recalctotalprice.
TYPES: BEGIN OF ty_amount_per_currencycode,
amount TYPE /dmo/total_price,
currency_code TYPE /dmo/currency_code,
END OF ty_amount_per_currencycode.
DATA: amounts_per_currencycode TYPE STANDARD TABLE OF
ty_amount_per_currencycode.
" Read all relevant travel instances.
ENTITY travel
FIELDS ( booking_fee currency_code )
DELETE travels WHERE currency_code IS INITIAL.
" Read all associated bookings and add them to the total price.
FIELDS ( flight_price currency_code )
WITH CORRESPONDING #( travels )
RESULT DATA(bookings).
" Read all associated booking supplements and add them to the total price.
FIELDS ( price currency_code )
WITH CORRESPONDING #( bookings )
RESULT DATA(bookingsupplements).
LOOP AT travels ASSIGNING FIELD-SYMBOL(<travel>).
" Set the start for the calculation by adding the booking fee.

Develop PUBLIC 413
amounts_per_currencycode = VALUE #( ( amount = <travel>-
booking_fee
currency_code = <travel>-
currency_code ) ).
LOOP AT bookings INTO DATA(booking) USING KEY id WHERE travel_id =
<travel>-travel_id
AND currency_code
IS NOT INITIAL.
COLLECT VALUE ty_amount_per_currencycode( amount = booking-
flight_price
currency_code = booking-
currency_code
) INTO
amounts_per_currencycode.
ENDLOOP.
LOOP AT bookingsupplements INTO DATA(bookingsupplement) USING KEY id
WHERE travel_id = <travel>-travel_id
AND currency_code IS NOT INITIAL.

COLLECT VALUE ty_amount_per_currencycode( amount =
bookingsupplement-price
currency_code =
bookingsupplement-currency_code
) INTO
amounts_per_currencycode.
ENDLOOP.
DELETE amounts_per_currencycode WHERE currency_code IS INITIAL.
CLEAR <travel>-total_price.
LOOP AT amounts_per_currencycode INTO DATA(amount_per_currencycode).
" If needed do a Currency Conversion
IF amount_per_currencycode-currency_code = <travel>-currency_code.
<travel>-total_price += amount_per_currencycode-amount.
ELSE.
/dmo/cl_flight_amdp=>convert_currency(
EXPORTING
iv_amount = amount_per_currencycode-amount
iv_currency_code_source = amount_per_currencycode-
currency_code
iv_currency_code_target = <travel>-currency_code
iv_exchange_rate_date =
cl_abap_context_info=>get_system_date( )
IMPORTING
ev_amount =
DATA(total_booking_price_per_curr)
).
<travel>-total_price += total_booking_price_per_curr.
ENDIF.
ENDLOOP.
ENDLOOP.
" write back the modified total_price of travels
ENTITY travel
UPDATE FIELDS ( total_price )
WITH CORRESPONDING #( travels ).
ENDMETHOD.

ENDCLASS.
4.2.2.3.3.3 Enabling Actions for UI Consumption
On the UI, actions are triggered by choosing an action button. This action button must be configured in the
backend in the related CDS view. Depending on where you want to use an action button on the UI (list report, or
object page), use the annotation @UI.lineItem or @UI.identification to display an action button.

414 PUBLIC Develop
 Note
The UI-annotations for actions must be used as element annotation. However, it does not have an impact
on which element the action is annotated. The action button always appears at the same position on the UI.
You can use the following UI annotation to expose actions to the consumer:
Syntax

define view <CDSEntity> as select from <DATA_SOURCE> as ..
{
@UI.lineItem: [ ...
{ type: #FOR_ACTION, dataAction: 'action_1', label: 'label 1', position:
10 },
{ type: #FOR_ACTION, dataAction: 'action_2', label: 'label 2',
position:20 },
... ]
@UI.identification: [ ...
{ type: #FOR_ACTION, dataAction: 'action_1', label: 'label 1', position:
10 },
{ type: #FOR_ACTION, dataAction: 'action_2', label: 'label 2',
position:20 },
... ]

}
 Note
The dataAction element references the name of the action as it is defined in the behavior definition.
4.2.2.3.4 Adding Static and Dynamic Feature Control
As an application developer you may want to determine, which entities of your business object should be
create-, delete- and update-enabled, so that they can be modified during consumption using EML or OData
services. In addition, you may also want to control which (UI) fields of an entity are read-only or which actions
in which usage scenarios are enabled or disabled for execution by the end users.
In ABAP RESTful application programming model, feature control is precisely the way to accomplish such
tasks. It allows you to control the visibility and changeability of fields, operations or entire entities.
The availability of feature control values is modeled in a behavior definition. Unlike static feature control,
instance feature control requires not only a definition but also an implementation in a handler class of the
behavior pool. Therefore, we also talk about dynamic feature control in case of instance feature control.
Feature control can be related to an entire entity or to individual elements of an entity, such as individual fields
or operations. For more information, see Feature Control [page 128].

Develop PUBLIC 415
1. Modeling Static and Dynamic Feature Control [page 416]

2. Implementing Dynamic Feature Control [page 417]
4.2.2.3.4.1 Modeling Static and Dynamic Feature Control
Both, static and dynamic feature control is defined for different levels (entity, field, or action level) in the
For a description on field characteristics, see CDS BDL - field characteristics, projection BDEF (ABAP -
Keyword Documentation) .
For a description on dynamo feature control, see CDS BDL - feature control (ABAP - Keyword Documentation).
Adding Feature Control to Behavior Definition /DMO/I_Travel_M
Corresponding to the coding below, add the static and dynamic feature control to each entity in the behavior
definition.
 Expand the following code sample to view the source code of defining the behavior for /DMO/I_Travel_M.
 Sample Code

...
{
// administrative fields: read only
field ( readonly ) last_changed_at, last_changed_by, created_at, created_by;
// mandatory fields that are required to create a travel
field ( mandatory ) agency_id, customer_id, begin_date, end_date,
overall_status, booking_fee, currency_code;
// Semantic Key field, which is readonly for the consumer, value is
assigned in early numbering
// dynamic action control
action ( features: instance ) acceptTravel result [1] $self;
action ( features: instance ) rejectTravel result [1] $self;
// dynamic operation control
association _Booking { create (features:instance); }
...
}
...
{
// static field control
field ( mandatory ) carrier_id, connection_id, flight_date, booking_status;
// Fields that are mandatory for create but should be read-only afterwards
field ( mandatory : create, readonly : update) booking_date, customer_id;
// dynamic operation control

416 PUBLIC Develop
association _BookSupplement { create (features:instance); }
...
}
...
{
field ( mandatory ) price,supplement_id;
...

}
For the travel entity, we define all admin fields as read-only, whereas the fields that are required for creating a
travel instance are defined as mandatory.
The key field travel_id is also set to readonly as the value is determined by early numbering. The
consumer of the BO must not be able to set the travel ID manually. The same is true for the other key fields
of the child entities and some other booking-specifics fields. This kind of field control is static, which means it
does not have to be implemented in the corresponding feature control implementation.
Examples of dynamic action control are the two methods acceptTravel and rejectTravel. Depending on
the status value (overall_status), these actions can become enabled or disabled.
Creating bookings by association is dynamically controlled. You can only create new bookings if the
overall_status of the corresponding travel instance is not rejected.
4.2.2.3.4.2 Implementing Dynamic Feature Control
The implementation of dynamic feature control is based on the ABAP language in a local handler class
(lhc_handler) as part of the behavior pool. For more information about instance dynamic feature control, see
Instance Feature Control [page 129].
Feature Control for Travel Entity
In the following step, we will apply the feature control specifically to our demo scenario.
UI Preview
The figure below shows the realization of the static and dynamic field control using the example of the travel
object page that has been switched to edit mode. All mandatory fields are marked with a red star.

Develop PUBLIC 417
Static and Dynamic Feature Control on Field Level
The following figure shows the effect of dynamic control on the two action buttons Accept Travel and Reject
Travel: Since the selected travel instance has the status Accepted, the action button Accept Travel is disabled.
Dynamic Feature Control for Actions
Another dynamic feature control is defined for the creating bookings by associations and creating booking
supplements by association. In this case the CREATE button for creating associated booking instance is
displayed if the travel instance's overall_status is not rejected. It is hidden, if the travel is set to rejected.
Likewise, the CREATE button for bookings supplements is displayed depending on the booking status of the
corresponding booking instance.

418 PUBLIC Develop
Dynamic Feature Control for Create By Association
Definition
In the behavior definition, the feature control for travel entity is defined as follows:

...
{
// administrative fields: read only
field ( readonly ) last_changed_at, last_changed_by, created_at, created_by;
// mandatory fields that are required to create a travel
field ( mandatory ) agency_id, customer_id, begin_date, end_date,
overall_status, booking_fee, currency_code;
// Semantic Key field, which is readonly for the consumer, value is assigned
in early numbering
// instance action and dynamic action control
action ( features: instance ) acceptTravel result [1] $self;
action ( features: instance ) rejectTravel result [1] $self;
association _Booking { create (features:instance); }
...

}

Develop PUBLIC 419
Implementing Dynamic Feature Control for Travel Entity
The method implementation begins with reading the travel_id and the overall_status field that is
designated for dynamic field control. The result of this read operation is stored in travels.
Since the feature control implementation is called before any other modification request, this EML read request
might fail if the imported keys parameter contains invalid key values. Therefore the changing parameter
failed is retrieved and its content directly written to the method's failed parameter.
Depending on the value of overall_status field, the actions rejectTravel and acceptTravel are
enabled or disabled, and the create by association is possible or not.
 Expand the following code sample to view the source code of Feature Control in /DMO/I_Travel_M.
 Sample Code

PRIVATE SECTION.
...
METHODS get_features FOR INSTANCE FEATURES
IMPORTING keys REQUEST requested_features FOR travel RESULT result.
ENDCLASS.
...
METHOD get_features.
ENTITY travel
FIELDS ( travel_id overall_status )
FAILED failed.
result = VALUE #( FOR travel IN travels
( %tky = travel-%tky
%features-%action-rejecttravel = COND #( WHEN travel-
overall_status = 'X'
THEN
if_abap_behv=>fc-o-disabled ELSE if_abap_behv=>fc-o-enabled )
%features-%action-accepttravel = COND #( WHEN travel-
overall_status = 'A'
THEN
%assoc-_booking = COND #( WHEN travel-
overall_status = 'X'
THEN
) ).
ENDMETHOD.

ENDCLASS.
Dynamic Feature Control for Booking Entity
UI Preview
The following figure shows the effect of static and dynamic field control after switching the Fiori UI object page
for bookings in edit mode.

420 PUBLIC Develop
Static and Dynamic Feature Control at Field Level
Definition

...
{
field ( mandatory ) carrier_id, connection_id, flight_date, booking_status;
// Fields that are mandatory for create but should be read-only afterwards
field ( mandatory : create, readonly : update) booking_date, customer_id;
// dynamic feature control create booking supplement by association

association _BookSupplement { create (features:instance); }
...

}
Implementing Dynamic Feature Control for Booking Entity

The get_features method implements dynamic field control for the create booking supplements by
association. Like the feature control for the travel entity, the affected booking instances must be read to
retrieve the values of the fields that are relevant for the feature control. Then the feature control values must be
assigned.
 Expand the following code sample to view the source code of Feature Control in the Booking Entity.
 Sample Code

PRIVATE SECTION.
...
IMPORTING keys FOR booking~validatestatus.
METHODS get_features FOR INSTANCE FEATURES
ENDCLASS.
...
ENTITY booking
FIELDS ( booking_id booking_status )
RESULT DATA(bookings)
FAILED failed.
result = VALUE #( FOR booking IN bookings
( %tky = booking-%tky
%assoc-_booksupplement = COND #( WHEN booking-
booking_status = 'B'

Develop PUBLIC 421
THEN
if_abap_behv=>fc-o-disabled ELSE if_abap_behv=>fc-o-enabled ) ) ).
ENDMETHOD.

ENDCLASS.
4.2.2.3.5 Developing Validations
For the managed scenario, add validations to check the values provided by the client.
Context and Procedure
Validations are used to check whether provided values by a client are consistent. They give direct feedback
(messages) before the BO instance is saved to the database. For conceptual information about validations, see
Validations [page 123].
For this demo scenario, define and implement validations for the entities travel and booking.
• Entity travel
• The validation validateCustomer checks if the customer ID that is entered by the consumer is valid.
• The validation validateAgency checks if the agency ID that is entered by the consumer is valid.
• The validation validateDates checks if the begin_date is in the future and if the value of the
end_date is after the begin_date.
• The validation validateStatus checks if the value of the overall_status field is valid.
• The validation validateCurrencyCode checks if the value the currency_code field is valid.
• Entity booking
• The validation validateStatus checks if the value of the booking_statusfield is valid.
• The validation validateCurrencyCode checks if the value the currency_code field is valid.
4.2.2.3.5.1 Defining Validations
Validations are defined in the behavior definition.
As depicted in the following sample code, add the following validations to each entity in the behavior definition.
 Sample Code

...
{
...
validation validateCustomer on save { create; field customer_id; }
validation validateAgency on save { create; field agency_id; }

422 PUBLIC Develop
validation validateDates on save { create; field begin_date,
end_date; }
validation validateStatus on save { create; field overall_status; }
validation validateCurrencyCode on save { create; field currency_code; }
}
...
{
...
validation validateStatus on save { create; field booking_status; }
}
...
{
...
// No validations

}
For the travel entity, we define the following validations:
• validateCustomer: Checks if the customer ID that is entered by the consumer is valid.

• validateAgency: Checks if the agency ID that is entered by the consumer is valid.
• validateDates: Checks if the begin_date is in the future and if the value of the end_date is after the
begin_date.
• validateStatus: Checks if the value of the overall_status field is valid.
• validateCurrencyCode: Checks if the value of the currency_code field is valid.
For the booking entity, we define the following validations:
• validateStatus: In contrast to the validation with the same name in the travel entity, booking_status
is specified as trigger field.
• validateCurrencyCode: Checks if the value of the currency_code field is valid.
4.2.2.3.5.2 Implementing Validations
Validations on Travel Entity
UI Preview
If the user enters an invalid Customer ID (an ID that is not available in the customer database table /DMO/
Customer) the validation is initiated at the save time. As a result saving the instance data is rejected and a
corresponding message is returned to the user.

Develop PUBLIC 423
Customer ID field validation on Fiori UI
Definition
In the behavior definition, the validations on the travel entity are defined as follows:

...
{
...
validation validateCustomer on save { create; field customer_id; }
validation validateAgency on save { create; field agency_id; }
validation validateDates on save { create; field begin_date, end_date; }
validation validateStatus on save { create; field overall_status; }

}
Implementation of validateCustomer
It should come as no surprise that the signatures of all four methods for implementing validations are very
similar.
In the following codeblock, you see details about the implementation of the validate_customer method:
First, the EML read operation READ ENTITY provides read access to the selected travel instance by using the
key.
To access data of the relevant entity fields, the FIELDS ( ) addition is used. As a result of the read operation
the entered (changed) value of the customer_id field for the selected travel instance are written into the table
travels. Only this value is relevant for the validation.
In the following lines of code, we prepare an optimization for the following database select. By using the sorted
table customers, we ensure that only data records with non-initial customer IDs are considered for database
access.
By accessing the contents of the database table /dmo/customer, we can check whether the entered
customer ID exists on the database at all.
If the validation detects inconsistencies (customer ID is not valid or is initial), we must provide the key of
all inconsistent instances as failed key and return error messages to the consumer. For all failed instances,
also corresponding messages are created, which is done with the NEW statement. For access to suitable
message texts, a message class /dmo/cm_flight_messages from the /DMO/FLIGHT package is used. For
more information, about raising messages in the RAP context, see Messages [page 261].

424 PUBLIC Develop
 Expand the following code sample to view the source code of Validation validateCustomer.
 Sample Code
CLASS ltc_managed DEFINITION DEFERRED FOR TESTING.

PRIVATE SECTION.
METHODS validate_customer FOR VALIDATE ON SAVE
IMPORTING keys FOR travel~validatecustomer.
ENDCLASS.
METHOD validate_customer.
" Read relevant travel instance data
ENTITY travel
FIELDS ( customer_id )
DATA customers TYPE SORTED TABLE OF /dmo/customer WITH UNIQUE KEY
customer_id.
" Optimization of DB select: extract distinct non-initial customer IDs
customers = CORRESPONDING #( travels DISCARDING DUPLICATES MAPPING
customer_id = customer_id EXCEPT * ).
DELETE customers WHERE customer_id IS INITIAL.
IF customers IS NOT INITIAL.
" Check if customer ID exists
SELECT FROM /dmo/customer FIELDS customer_id
FOR ALL ENTRIES IN @customers
WHERE customer_id = @customers-customer_id
INTO TABLE @DATA(customers_db).
ENDIF.
" Raise msg for non existing and initial customer id
LOOP AT travels INTO DATA(travel).
IF travel-customer_id IS INITIAL
OR NOT line_exists( customers_db[ customer_id = travel-
customer_id ] ).
APPEND VALUE #( %tky = travel-%tky ) TO failed-travel.
APPEND VALUE #( %tky = travel-%tky
customer_id = travel-customer_id
textid = /dmo/
cm_flight_messages=>customer_unkown
severity =
%element-customer_id = if_abap_behv=>mk-on
ENDIF.
ENDLOOP.
ENDMETHOD.

ENDCLASS.
Implementation of validateAgency
The validation to check if the agency ID is valid has exactly the same structure as validate_customer. The
code can be downloaded from ABAP Flight Reference Scenario in /DMO/BP_TRAVEL_M.
Implementation of validateDates
In the following codeblock, you see details about the implementation of the validate_dates method:
The EML read operation READ ENTITIES provides read access to data from trigger fields begin_date and
end_date. As a result of the read operation the entered (changed) values of the begin_date and end_date
fields for the selected travel instance are written into the table row travels.

Develop PUBLIC 425
The validation detects inconsistencies if the date value of end_date is before the date value of begin_date
or if the date value of begin_date is in the past. Each validation can produce failed keys and messages. Any
failed keys are stored in the table FAILED whereas the REPORTED table includes all instance-specific messages.
 Expand the following code sample to view the source code of Validation validateDates.
 Sample Code

PRIVATE SECTION.
METHODS validate_dates FOR VALIDATE ON SAVE
IMPORTING keys FOR travel~validatedates.
ENDCLASS.
METHOD validate_dates.
ENTITY travel
FIELDS ( begin_date end_date )
IF travel-end_date < travel-begin_date. "end_date before begin_date
textid = /dmo/
cm_flight_messages=>begin_date_bef_end_date
severity =
if_abap_behv_message=>severity-error
begin_date = travel-begin_date
end_date = travel-end_date
travel_id = travel-travel_id )
%element-begin_date = if_abap_behv=>mk-on
%element-end_date = if_abap_behv=>mk-on
ELSEIF travel-begin_date < cl_abap_context_info=>get_system_date( ).
"begin_date must be in the future
textid = /dmo/
cm_flight_messages=>begin_date_on_or_bef_sysdate
error )
%element-begin_date = if_abap_behv=>mk-on
%element-end_date = if_abap_behv=>mk-on
ENDIF.
ENDLOOP.
ENDMETHOD.

ENDCLASS.
Implementation of validateStatus
In the following codeblock, you see details about the implementation of the validateStatus method:
Checking the validity of overall_status values is performed within a case loop. The valid values O, X, and A
are specified directly in the source code.
 Expand the following code sample to view the source code of Validation validateStatus.

426 PUBLIC Develop
 Sample Code

PRIVATE SECTION.
METHODS validate_customer FOR VALIDATE ON SAVE
IMPORTING keys FOR travel~validatecustomer.
ENDCLASS.
METHOD validate_travel_status.
ENTITY travel
FIELDS ( overall_status )
CASE travel-overall_status.
WHEN 'O'. " Open
WHEN 'X'. " Cancelled
WHEN 'A'. " Accepted
WHEN OTHERS.
textid = /dmo/
cm_flight_messages=>status_invalid
severity =
status = travel-overall_status )
%element-overall_status = if_abap_behv=>mk-on
ENDCASE.
ENDLOOP.
ENDMETHOD.

ENDCLASS.
Implementation of validateCurrencyCode
In the following codeblock, you see details about the implementation of the validate_currencycode
method:
First, the EML read operation READ ENTITY provides read access to the selected travel instance by using the
key.
To access data of the relevant entity fields, the FIELDS ( ) addition is used. As a result of the read operation
the entered (changed) value of the currency_code field for the selected travel instance is written into the
table travels. Only this value is relevant for the validation.
In the following lines of code, we prepare an optimization for the following database select. By using the
sorted table currencies, we ensure that only data records with non-initial currency codes are considered for
database access.
By accessing the contents of the standard CDS view I_currency, we can check whether the entered currency
code exists on the database at all.
If the validation detects inconsistencies (currency code is not valid or is initial), we must provide the key of
all inconsistent instances as failed key and return error messages to the consumer. For all failed instances,
also corresponding messages are created, which is done with the NEW statement. For access to suitable
message texts, a message class /dmo/cm_flight_messages from the /DMO/FLIGHT package is used. For
more information, about raising messages in the RAP context, see Messages [page 261].

Develop PUBLIC 427
 Sample Code

PRIVATE SECTION.
METHODS validate_currencycode FOR VALIDATE ON SAVE
IMPORTING keys FOR travel~validatecurrencycode.
ENDCLASS.
METHOD validate_currencycode.
ENTITY travel
FIELDS ( currency_code )
DATA: currencies TYPE SORTED TABLE OF I_Currency WITH UNIQUE KEY currency.
currencies = CORRESPONDING #( travels DISCARDING DUPLICATES MAPPING
currency = currency_code EXCEPT * ).
DELETE currencies WHERE currency IS INITIAL.
IF currencies IS NOT INITIAL.
SELECT FROM I_Currency FIELDS currency
FOR ALL ENTRIES IN @currencies
WHERE currency = @currencies-currency
INTO TABLE @DATA(currency_db).
ENDIF.
IF travel-currency_code IS INITIAL.
" Raise message for empty Currency
APPEND VALUE #( %tky = travel-%tky ) TO failed-
travel.
textid = /dmo/
cm_flight_messages=>currency_required
severity =
%element-currency_code = if_abap_behv=>mk-on
ELSEIF NOT line_exists( currency_db[ currency = travel-
currency_code ] ).
" Raise message for not existing Currency
travel.
textid = /dmo/
cm_flight_messages=>currency_not_existing
severity =
currency_code =
travel-currency_code )
ENDIF.
ENDLOOP.
ENDMETHOD.

ENDCLASS.

428 PUBLIC Develop
Validation on Booking Entity
UI Preview
In this case, we want to validate the status values of booking instances. If a user enters the wrong value K,
according to the figure below, the instance with its data is not saved and an error message is displayed instead.
Booking Status Validation on Fiori UI
Definition

...
{
...
validation validateStatus on save { create; field booking_status; }

}
Implementation of validateStatus for the Booking entity

The validate_booking_status method is implemented analogously to the one of the previous case when
checking travel status.
 Sample Code

PRIVATE SECTION.

Develop PUBLIC 429
METHODS validateStatus FOR VALIDATE ON SAVE
importing keys FOR booking~validateStatus.
...
ENDCLASS.
METHOD validateStatus.
ENTITY booking
FIELDS ( booking_status )
LOOP AT bookings INTO DATA(booking).
CASE booking-booking_status.
WHEN 'N'. " New
WHEN 'X'. " Canceled
WHEN 'B'. " Booked
WHEN OTHERS.
APPEND VALUE #( %tky = booking-%tky ) TO failed-booking.
APPEND VALUE #( %tky = booking-%tky
textid = /dmo/
cm_flight_messages=>status_invalid
status = booking-booking_status
severity =
%element-booking_status = if_abap_behv=>mk-on
%path = VALUE #( travel-travel_id = booking-
travel_id )
) TO reported-booking.
ENDCASE.
ENDLOOP.
ENDMETHOD.

ENDCLASS.
Implementation of validateCurrencyCode for the Booking entity

The validate_currencycode method is implemented analogously to the one on the travel entity..
 Sample Code

PRIVATE SECTION.
METHODS validate_currencycode FOR VALIDATE ON SAVE
IMPORTING keys FOR booking~validatecurrencycode.
...
ENDCLASS.
METHOD validate_currencycode.
ENTITY booking
FIELDS ( currency_code )
DATA: currencies TYPE SORTED TABLE OF i_currency WITH UNIQUE KEY currency.
currencies = CORRESPONDING #( bookings DISCARDING DUPLICATES MAPPING
currency = currency_code EXCEPT * ).
SELECT FROM i_currency FIELDS currency
ENDIF.

430 PUBLIC Develop
IF booking-currency_code IS INITIAL.
APPEND VALUE #( %tky = booking-%tky ) TO failed-
booking.
textid = /dmo/
severity =
%path = VALUE #( travel-
travel_id = booking-travel_id )
ELSEIF NOT line_exists( currency_db[ currency = booking-
currency_code ] ).
booking.
textid = /dmo/
severity =
currency_code =
booking-currency_code )
%path = VALUE #( travel-
travel_id = booking-travel_id )
ENDIF.
ENDLOOP.
ENDMETHOD.

ENDCLASS.
4.2.2.3.6 Developing Determinations
For the managed scenario, add determinations to calculate values implicitly.
With determinations, you can generalize the calculation of values in the business logic of a managed BO. For
conceptual information about determinations, see Determinations [page 119].
For this demo scenario, define and implement determinations for the entities travel,booking and booking
supplement.
• Entity travel
The determination calculateTotalPrice calculates the total price for a travel, including the
booking_fee (travel entity), flight_price (booking entity) and price (booking supplement entity).
Technically speaking, this determination is a determination on modify with the trigger fields
booking_fee and currency_code.
• Entity booking

Develop PUBLIC 431
The determination calculateTotalPrice invokes the same calculation as the determination on the
travel entity. Technically speaking, this determination is a determination on modify with the trigger
fields flight_price and currency_code.
• Entity booking supplement
The determination calculateTotalPrice invokes the same calculation as the determination on the
travel entity. Technically speaking, this determination is a determination on modify with the trigger
fields price and currency_code.
The best practice for determinations that trigger the same calculation is to outsource the calculation to an
internal action. Like this, every determination on its entity respectively calls the action that is defined and
implementation on the root entity.
4.2.2.3.6.1 Defining Determinations
Determinations are defined in the behavior definition.
As depicted in the following sample coding, add the following determinations to relevant entities in the behavior
definition.
 Expand the following code sample to view the source code of defining behavior for /DMO/I_Travel_M.
 Sample Code

...
{ ...
determination calculateTotalPrice on modify {create; field booking_fee,
currency_code; }
}
...
{...
// determination for calculation of total flight price
determination calculateTotalPrice on modify { create; field flight_price,
currency_code; }
}
...
{...
// determination for calculation of total suppl. price
determination calculateTotalPrice on modify {create; field price,
currency_code; }

}
The determination calculateTotalPrice, which is defined for all three entities handles the calculation of
total price of one travel. It includes the booking fee, the flight prices and the booking supplement prices. The
determination will be triggered by on modify as determination time when creating new instances or updating
the prices that are included in the calculation or when changing the currency. In other words: the trigger
conditions for all determinations are create and the respective trigger fields on each entity.

432 PUBLIC Develop
4.2.2.3.6.2 Implementing Determinations
Determination on Travel Entity
Definition
In the behavior definition, the determination on the travel entity is defined as follows:

...
{
...
determination calculateTotalPrice on modify {create; field flight_price,
currency_code; }

}
calculateTotalPrice
Since the pricing calculation is required for all three determinations and we will access them from
different handler classes, we outsource the more generic code to the internal action Implementation of
ReCalcTotalPrice, which we already developed in one of the previous steps, see Developing Actions [page
405]. The implementation for the determination simply consists of an EML call to execute the action.
 Expand the following code sample to view the source code of determination calculateTotalPrice.
 Sample Code

PRIVATE SECTION.
...
METHODS calculatetotalprice FOR DETERMINE ON MODIFY
IMPORTING keys FOR travel~calculatetotalprice.
ENDCLASS.
METHOD calculatetotalprice.
ENTITY travel
EXECUTE recalctotalprice
FROM CORRESPONDING #( keys ).
ENDMETHOD.
...

ENDCLASS.
Determination on Booking Entity
UI Preview
The figure below refers to the starting point of viewing with a newly created travel instance with the initial
amount (Total Price) and the travel currency 0.00 EUR.

Develop PUBLIC 433
The Newly Created Travel with a Total Price 0.00 EUR.
Implementation ofIf a user adds a flight booking to the travel, then also the travel’s Total Price is updated.
Added Bookings Triggers an Update on Travel Data
If the user switches the booking’s object page to edit mode and then changes the Flight Price, then the Total
Price is also updated at root level.

434 PUBLIC Develop
Updated Total Price at Root Level
Definition
In the behavior definition, the determination on the booking entity is defined as follows:

...
{
...
determination calculateTotalPrice on modify {create; field flight_price,
currency_code; }

}
Implementation of calculateTotalPrice on the Booking Entity

Since the pricing calculation is required for all three determinations and we will access them from different
handler classes, we outsource the more generic code to the internal action ReCalcTotalPrice, which we
already developed in one of the previous steps, see Developing Actions [page 405]. In the implementation of
the determination, we first discard duplicate travel IDs from the imported keys and then execute the action for
the remaining travel IDs.
 Sample Code

PRIVATE SECTION.
...
METHODS calculateTotalPrice FOR DETERMINE ON MODIFY
IMPORTING keys FOR booking~calculateTotalPrice.
ENDCLASS.
METHOD calculatetotalprice.
DATA: travel_ids TYPE STANDARD TABLE OF /dmo/i_travel_m WITH UNIQUE
HASHED KEY key COMPONENTS travel_id.
travel_ids = CORRESPONDING #( keys DISCARDING DUPLICATES MAPPING
travel_id = travel_id ).
ENTITY Travel
EXECUTE ReCalcTotalPrice
FROM CORRESPONDING #( travel_ids ).
ENDMETHOD.

Develop PUBLIC 435
...

ENDCLASS.
Determination on Booking Supplement Entity
UI Preview
If the user adds a supplement to a given flight booking, then the travel amount is re-calculated.
Added Supplement Changes the Travel Amount
The updated travel amount is displayed in as new value of Total Price.
Updated Total Price of the Travel Instance
In addition to the price, the currency was also defined as another trigger field for determination. In this way, we
want to ensure that currency conversion is also carried out when the total amount is re-calculated. In our case,
the supplement price with the current currency (USD) is converted into the travel currency (EUR).

436 PUBLIC Develop
Currency Conversion of Supplement Price and Updated Total Price in EUR
Definition
In the behavior definition, the determination on the booking supplement entity is defined as follows:

...
{
...
determination calculateTotalPrice on modify {create; field price,
currency_code; }

}
Implementation of calculateTotalPrice on the Booking Supplement Entity

Since the pricing calculation is required for all three determinations and we will access them from different
handler classes, we outsource the more generic code to the internal action ReCalcTotalPrice, which we
already developed in one of the previous steps, see Developing Actions [page 405]. In the implementation of
the determination, we first discard duplicate travel IDs from the imported keys and then execute the action for
the remaining travel IDs.
 Sample Code

PRIVATE SECTION.
METHODS calculateTotalPrice FOR DETERMINE ON MODIFY
IMPORTING keys FOR booksuppl~calculateTotalPrice.
...
ENDCLASS.
METHOD calculateTotalPrice.
DATA: travel_ids TYPE STANDARD TABLE OF /dmo/i_travel_m WITH UNIQUE
HASHED KEY key COMPONENTS travel_id.
travel_ids = CORRESPONDING #( keys DISCARDING DUPLICATES MAPPING
travel_id = travel_id ).
ENTITY Travel
EXECUTE ReCalcTotalPrice
FROM CORRESPONDING #( travel_ids ).
ENDMETHOD.


Develop PUBLIC 437
ENDCLASS.
4.2.2.3.7 Integrating Additional Save in Managed Business

Objects
This section explains how you can integrate Additional Save within the transactional life cycle of managed
business objects.
Use Case
In some application scenarios, an external functionality must be invoked during the save sequence, after the
managed runtime has written the changed data of business object’s instances to the database but before the
final commit work has been executed.
For example, reuse services like change documents and the application log must be triggered during the save
sequence and the changes of the current transaction must be written to change requests.
In real-life business applications, the data of business objects may change frequently. It is often helpful, and
sometime even necessary, to be able to trace or reconstruct changes for objects that are critical, for example
for investigation or auditing purposes. The ABAP Application Server records changes to business data objects
in change documents.
Application events can be centrally recorded in the application log. The entries of an application log contain
information about who gave rise to a given event at what time and with which program.
In order to integrate the additional save into the save sequence as a part of the managed runtime, you must
first add the corresponding syntax to the behavior definition and then implement the saver handler method as
a part of the behavior pool.
 Note
If you would like to prevent the managed runtime from saving the entity's data and reuse your own save
logic instead, you can integrate the unmanaged save instead. More on this: Integrating Unmanaged Save in
Managed Business Objects [page 447].
Additional Save Within the Transactional Life Cycle
The following figure depicts the additional save within the transactional life cycle of a managed business object.

438 PUBLIC Develop
Additional Save within the Transactional Processing
Develop PUBLIC 439
The save sequence is triggered for each business object after at least one successful modification (create,
update, delete) was performed and saving data has been explicitly requested by the consumer. The save
sequence starts with the FINALIZE processing step performing the final calculations and determinations
before data changes can be persisted.
If the subsequent CHECK_BEFORE_SAVE call, including all onSave validations (validations with the trigger
time on save), is positive for all transactional changes, the point-of-no-return is reached. From now on, a
successful save is guaranteed by all involved BOs.
If, on the other hand, the result of the checks is negative at the time of CHECK_BEFORE_SAVE, a save is denied
and the save sequence is interrupted. The consumer has now the option of modifying business object data and
then trigger the save sequence again.
After the point-of-no-return, the save call persists all BO instance data from the transactional buffer in the
database.
For each entity of an individual business object, the following options are available to execute the SAVE
processing step:
• Managed save (default)

• Managed save in conjunction with additional save
• Unmanaged save (to prevent the managed runtime from saving the entities data)
All change requests of the current LUW are committed. The actual save execution is finished by COMMIT WORK.
The final CLEANUP clears all transactional buffers of all business objects involved in the transaction.
• Defining Additional Save in the Behavior Definition [page 440]

• Implementing Additional Save [page 441]
4.2.2.3.7.1 Defining Additional Save in the Behavior Definition
In this topic, you will learn the syntax for defining the additional save for managed business objects.
In the following behavior definition, the additional save is defined for the travel (root) entity and the
booksuppl child entity, whereas for the booking child entity, the (default) managed save is defined.
For a detailed syntax description, see CDS BDL - saving options (ABAP - Keyword Documentation) .
Behavior Definition with Additional Save
managed;

strict;
...
{

440 PUBLIC Develop
...
}
...
{
...
}
...
{
...

}
4.2.2.3.7.2 Implementing Additional Save
The additional save of the relevant business object’s entity is implemented in the behavior pool (ABAP_CLASS)
that is specified in the behavior definition by the keyword implementation in class ABAP_CLASS
[unique].
The implementation takes place in a local saver class as a part of the behavior pool. As depicted in the listing
below, each such local class inherits from the base saver class CL_ABAP_BEHAVIOR_SAVER. This superclass
provides the predefined method save_modified that needs to be redefined in the local saver class.
General Implementation Steps
The following listing provides a template with the main steps for implementing additional save within the
save_modified method.
The essential elements of this method are the predefined, implicit parameters:
• CREATE-EntityName
• UPDATE-EntityName
• DELETE-EntityName
These parameters contain not only the table type of the entity to be modified, but also the %control structure
that identifies the fields that have been changed in the current LUW. Only the fields that are flagged with true
in the %control structure contain the correct values for saving in the additional save.
 Note
If you use function modules in the additional save implementation that import all fields of an instance and
write all of them to the database, execute a preliminary read and read all fields of the instance, before you
use the instance in your function module.

Develop PUBLIC 441
Accessing Element Information for the Implicit Parameter Type (F2)
Template for Implementing Additional Save

of method Save_Modified.
 Sample Code

PROTECTED SECTION.
ENDCLASS.
CLASS lcl_saver IMPLEMENTATION.
METHOD save_modified.
IF CREATE-EntityName IS NOT INITIAL.
" Provide table of instance data of all instances that have been
created during current transaction
" Use %CONTROL to get information on what entity fields have been set
when creating the instance
ENDIF.
IF UPDATE-EntityName IS NOT INITIAL.
" Provide table of instance data of all instances that have been
updated during current transaction
" Use %CONTROL to get information on what entity fields have been
updated
ENDIF.
IF DELETE-EntityName IS NOT INITIAL.
" Provide table with keys of all instances that have been deleted
during current transaction
" NOTE: There is no information on fields when deleting instances
ENDIF.
ENDMETHOD.
...

ENDCLASS.

442 PUBLIC Develop
Additional Save Implementation in the Travel BO
The following example shows you in detail how you can implement additional save based on our travel demo
scenario [page 309].
In this example, all essential changes to the root instance of the travel business object are recorded in a log
table. This is defined in such a way that it can hold different travel instance data and contains the following
fields:
Log Table
Log Table Field Description
change_id Identifier for an individual change
travel_id Key field of the travel entity
changing_operation Standard operation for travel instances: create, update and delete
changed_field_name Name of the field that has been created or changed
changed_value Value of a created or changed entity field
created_at Date and time of instance data creation, update or deletion
The following listing shows you the definition of the corresponding table /DMO/LOG_TRAVEL in the table editor.
Listing: Source code with table definition

@EndUserText.label : 'flight reference scenario: log changes to travel entity'
@AbapCatalog.dataMaintenance : #LIMITED
define table /dmo/log_travel {
key change_id : abap.raw(16);
travel_id : /dmo/travel_id not null;
changing_operation : abap.char(10);
changed_field_name : abap.char(32);
changed_value : abap.char(32);

}

Develop PUBLIC 443
UI Preview
Consumer modifies business data on Fiori UI
After successful save, the relevant entries are recorded in the log table
Definition
In the behavior definition, the additional save for the root entity may be defined as follows:

...
{
...

}
Implementation
The source code of our example implementation is divided into three sections:
Each of these sections is initiated with an IF statement, each of which checks whether
• the travel instances have been created (IF create-travel IS NOT INITIAL),
• their elements have been modified (IF update-travel IS NOT INITIAL), or
• deleted (IF delete-travel IS NOT INITIAL) by a consumer.

444 PUBLIC Develop
The relevant instance data is written to the internal table travel_log and passed to the log table for
persistent storage on the database (INSERT /dmo/log_travel...).
When creating new travel instances and updating instance data, the %control structure is used to get
information on what fields have been provided or updated by the consumer. The %control structure contains
a flag if_abap_behv=>mk-on for each field, which indicates whether the field was provided (or changed) by
the consumer or not.
When creating instances (1), the new values for relevant fields of the travel entity are written into the internal
table travel_log_create. In our demo code, we select the two fields booking_fee and overall_status
as an example. Their values are transferred as separate rows by means of APPEND into travel_log_create
and finally written into the log table /dmo/log_travel with INSERT.
Similarly, in the update case (2), we also select two fields, namely customer_id and description, as
relevant fields for recording. So whenever the value of one of these fields is changed for an existing travel
instance by a consumer, a new table row (with the corresponding change ID) is appended to the internal table
travel_log_create.
The last section (3) deals with the deletion of travel instances. However, in this case we are only interested
in the information of which instances have been deleted. Therefore, there is no information of fields available
when deleting instances.
 Expand the following code sample to view the source code of method Save_Modified.
 Sample Code
CLASS lcl_save DEFINITION INHERITING FROM cl_abap_behavior_saver.

PROTECTED SECTION.
ENDCLASS.
PROTECTED SECTION.
ENDCLASS.
DATA travel_log TYPE STANDARD TABLE OF /dmo/log_travel.
DATA travel_log_create TYPE STANDARD TABLE OF /dmo/log_travel.
DATA travel_log_update TYPE STANDARD TABLE OF /dmo/log_travel.
" (1) Get instance data of all instances that have been created
IF create-travel IS NOT INITIAL.
" Creates internal table with instance data
travel_log = CORRESPONDING #( create-travel ).
LOOP AT travel_log ASSIGNING FIELD-SYMBOL(<travel_log>).
<travel_log>-changing_operation = 'CREATE'.
" Generate time stamp
GET TIME STAMP FIELD <travel_log>-created_at.
" Read travel instance data into ls_travel that includes %control
structure
READ TABLE create-travel WITH TABLE KEY entity COMPONENTS travel_id =
<travel_log>-travel_id INTO DATA(travel).
IF sy-subrc = 0.
" If new value of the booking_fee field created
IF travel-%control-booking_fee = cl_abap_behv=>flag_changed.
" Generate uuid as value of the change_id field
TRY.
<travel_log>-change_id =
cl_system_uuid=>create_uuid_x16_static( ) .
CATCH cx_uuid_error.
"handle exception

Develop PUBLIC 445
ENDTRY.
<travel_log>-changed_field_name = 'booking_fee'.
<travel_log>-changed_value = travel-booking_fee.
APPEND <travel_log> TO travel_log_create.
ENDIF.
" If new value of the overall_status field created
IF travel-%control-overall_status = cl_abap_behv=>flag_changed.
TRY.
<travel_log>-change_id =
"handle exception
ENDTRY.
<travel_log>-changed_field_name = 'overall_status'.
<travel_log>-changed_value = travel-overall_status.
APPEND <travel_log> TO travel_log_create.
ENDIF.
" IF ls_travel-%control-...
ENDIF.
ENDLOOP.
" Inserts rows specified in lt_travel_log_c into the DB table /dmo/
log_travel
INSERT /dmo/log_travel FROM TABLE @travel_log_create.
ENDIF.
" (2) Get instance data of all instances that have been updated during
the transaction
IF update-travel IS NOT INITIAL.
travel_log = CORRESPONDING #( update-travel ).
LOOP AT update-travel ASSIGNING FIELD-SYMBOL(<travel_log_update>).
ASSIGN travel_log[ travel_id = <travel_log_update>-travel_id ] TO
FIELD-SYMBOL(<travel_log_db>).
<travel_log_db>-changing_operation = 'UPDATE'.
GET TIME STAMP FIELD <travel_log_db>-created_at.
IF <travel_log_update>-%control-customer_id = if_abap_behv=>mk-on.
<travel_log_db>-changed_value = <travel_log_update>-customer_id.
TRY.
<travel_log_db>-change_id =
"handle exception
ENDTRY.
<travel_log_db>-changed_field_name = 'customer_id'.
APPEND <travel_log_db> TO travel_log_update.
ENDIF.
IF <travel_log_update>-%control-description = if_abap_behv=>mk-on.
<travel_log_db>-changed_value = <travel_log_update>-description.
TRY.
<travel_log_db>-change_id =
"handle exception
ENDTRY.
<travel_log_db>-changed_field_name = 'description'.
APPEND <travel_log_db> TO travel_log_update.
ENDIF.
"IF <fs_travel_log_u>-%control-...
ENDLOOP.
" Inserts rows specified in lt_travel_log_u into the DB table /dmo/
log_travel
INSERT /dmo/log_travel FROM TABLE @travel_log_update.
ENDIF.
" (3) Get keys of all travel instances that have been deleted during the
transaction
IF delete-travel IS NOT INITIAL.

446 PUBLIC Develop
travel_log = CORRESPONDING #( delete-travel ).
LOOP AT travel_log ASSIGNING FIELD-SYMBOL(<travel_log_delete>).
<travel_log_delete>-changing_operation = 'DELETE'.
GET TIME STAMP FIELD <travel_log_delete>-created_at.
TRY.
<travel_log_delete>-change_id =
"handle exception
ENDTRY.
ENDLOOP.
" Inserts rows specified in lt_travel_log into the DB table /dmo/
log_travel
INSERT /dmo/log_travel FROM TABLE @travel_log.
ENDIF.
ENDMETHOD.

ENDCLASS.
4.2.2.3.8 Integrating Unmanaged Save in Managed

Business Objects
This section explains how you can integrate unmanaged save within the transactional life cycle of managed
business objects.
Use Case
In certain use cases you might be requested to prevent business object’s managed runtime from saving
business data (changes). By default, the managed runtime saves all changed instances of business object’s
entity in the database table that is specified as persistent table DB_TABLE in the behavior definition
(managed save). However, you define for each entity of the business object or for the entire business
object whether the complete save is done by the managed runtime or by the unmanaged save instead. This
implementation flavor of a managed scenario may be relevant to you if you need to implement the interaction
phase for your application anyway, but the update task function modules are already available.
The following figure outlines the main components of business objects managed runtime that integrates
function modules for persistent save of business data changes. Within the interaction phase, a consumer calls
the business object operations to change business data and read instances with or without the transactional
changes. The business object runtime keeps the changes in its internal transactional buffer which represents
the state of instance data. After all changes on the related entity were performed, the instance data can be
persisted. This is realized during the save sequence. To prevent the managed runtime from saving the data,
the function modules (for the update task) are called to save data changes of the relevant business object’s
entity (unmanaged save). In order to persist the business data changes, the function modules access the
corresponding tables of the HANA database.
Note that the behavior handler can also directly access table data from the database during the interaction
phase: Authorization checks, for example, require direct access to the table data on the database.

Develop PUBLIC 447
Runtime for the Managed Business Objects with Unmanaged Save
Unmanaged Save in Transactional Life Cycle
The following figure depicts the unmanaged save within the transactional life cycle of a managed business
object.

448 PUBLIC Develop
Unmanaged Save within the Transactional Processing
Develop PUBLIC 449
The save sequence is triggered for each business object after at least one successful modification (create,
update, delete) was performed and saving data has been explicitly requested by the consumer. The save
sequence starts with the FINALIZE processing step performing the final calculations and determinations
before data changes can be persisted.
If the subsequent CHECK_BEFORE_SAVE call, including all onSave validations (validations with the trigger
time on save), is positive for all transactional changes, the point-of-no-return is reached. From now on, a
successful save is guaranteed by all involved BOs.
If, on the other hand, the result of the checks is negative at the time of CHECK_BEFORE_SAVE, a save is denied
and the save sequence is interrupted. The consumer has now the option of modifying business object data and
then trigger the save sequence again.
After the point-of-no-return, the save call persists all BO instance data from the transactional buffer in the
database.
For each entity of an individual business object, the following options are available to execute the SAVE
processing step:
• Managed save (default)

• Managed save in conjunction with additional save
• Unmanaged save (to prevent the managed runtime from saving the entities data)
All change requests of the current LUW are committed. The actual save execution is finished by COMMIT WORK.
The final CLEANUP clears all transactional buffers of all business objects involved in the transaction.
In order to integrate unmanaged save into the save sequence as a part of the managed runtime, you must first
add the corresponding syntax to the behavior definition and then implement the saver handler method as a
part of the behavior pool.
• Defining Unmanaged Save in the Behavior Definition [page 450]

• Implementing the Save Handler Method [page 451]
4.2.2.3.8.1 Defining Unmanaged Save in the Behavior

Definition
In this topic, you will learn the syntax for defining unmanaged save for managed business objects.
travel (root) entity, whereas for the child entity booking the (default) managed save and for the child entity
booksuppl an additional save is defined.
For a detailed syntax description, see CDS BDL - saving options (ABAP - Keyword Documentation) .
Behavior Definition with Unmanaged Save
managed;


450 PUBLIC Develop
...
{
...
}
...
{
...
}
with unmanaged save
...
{
...

}
4.2.2.3.8.2 Implementing the Save Handler Method
The unmanaged save of the relevant business object’s entity is implemented in the behavior pool
(ABAP_ClASS) that is specified in the behavior definition by the keyword implementation in class
ABAP_ClASS [unique].
The implementation takes place in a local saver class as a part of the behavior pool. As depicted in the
listing below, each such local class inherits from the base saver class CL_ABAP_BEHAVIOR_SAVER. This
superclass provides the predefined method save_modified that needs to be redefined in the local saver class
lhc_saver.
 Remember
Convention: The local saver class that implements the save_modified method is either a separate global
class or a part of the root implementation (behavior pool for the root entity).
General Implementation Steps
The following listing provides a template with the main steps for implementing unmanaged save within the
save_modified method.
The essential elements of this method are the predefined, implicit parameters:
• CREATE-EntityName
• UPDATE-EntityName
• DELETE-EntityName

Develop PUBLIC 451
These parameters contain not only the table type of the entity to be modified, but also the %control
[page 155] structure that can be used for identifying which elements have been changed during the current
transaction. .
Accessing Element Information for the Implicit Parameter Type (F2)
The actual implementation steps of the save_modified method are shown in the template below:
Template for Implementing Unmanaged Save

PROTECTED SECTION.
ENDCLASS.
CLASS lcl_saver IMPLEMENTATION.
IF CREATE-EntityName IS NOT INITIAL.
" Provide table of instance data of all instances that have been created
" Use %CONTROL to get information on what entity fields have been set or
updated during the current transaction
ENDIF.
IF UPDATE-EntityName IS NOT INITIAL.
" Provide table of instance data of all instances that have been updated
" Use %CONTROL to get information on what entity fields have been updated
ENDIF.
IF DELETE-EntityName IS NOT INITIAL.
" Provide table with keys of all instances that have been deleted during
current transaction
" NOTE: There is no information on fields when deleting instances
ENDIF.
ENDMETHOD.
...

ENDCLASS.

452 PUBLIC Develop
Implementing Unmanaged Save in the Travel BO
The following example shows you in detail how you can implement unmanaged save specifically based on our
travel demo scenario [page 309]. In particular, the previous implementation must be extended in such a way
that the available function modules are used to save changes to business data of the booking supplement child
entity.
Function Modules
In our example, the corresponding function modules for creating, changing, and deleting instances of
the booking supplement entity are already available in the corresponding function group of the demo
package /DMO/FLIGHT_MANAGED.
Available Function Modules
Function module /DMO/FLIGHT_BOOKSUPPL_C
FUNCTION /dmo/flight_booksuppl_c

IMPORTING
VALUE(values) TYPE /dmo/tt_booksuppl_m.
INSERT /dmo/booksuppl_m FROM TABLE @values.

ENDFUNCTION.
 Note
To use this source code, the table type /dmo/tt_booksuppl_m is also required for the values importing
parameter.

Develop PUBLIC 453
Definition of Table Type /DMO/TT_BOOKSUPPL_M in the Dictionary Tool
The following listing provides you with the function module’s source code for persistent storage of individual
elements of existing booking supplement instances.
Function module /DMO/FLIGHT_BOOKSUPPL_U
FUNCTION /dmo/flight_booksuppl_u

IMPORTING
UPDATE /dmo/booksuppl_m FROM TABLE @values.

ENDFUNCTION.
The following listing provides you with the source code of the function module for deleting booking supplement
instances.
Function module /DMO/FLIGHT_BOOKSUPPL_D
FUNCTION /dmo/flight_booksuppl_d

IMPORTING
DELETE /dmo/booksuppl_m FROM TABLE @values.
ENDFUNCTION.

Definition
In the behavior definition, the unmananged save for the child entity booksuppl may be defined as follows:
managed;

strict
...
{
...

454 PUBLIC Develop
}
...
with unmanaged save
...
{
...

}
Implementation
As shown in the listing below, the source code of our example implementation is divided into three sections:
Each of these sections is initiated with an IF statement, each of which checks whether the booking
supplement instances have been created, their elements have been modified, or deleted by a consumer. The
relevant instance data is written to the internal table booksuppls_db and passed to the respective function
module for persistent storage on the database.
In case of updating instance data (IF update-booksuppl IS NOT INITIAL), the %control structure is
used to get information on what fields have been updated by the consumer. The %control structure contains
a flag if_abap_behv=>mk-on for each field, which indicates whether the field was provided (changed) by the
consumer or not.
To eliminate the option that the unchanged fields are overwritten with default values, we must ensure that they
are kept according to the database data. This is the reason why we read the current data set from the database
using the statement SELECT * FROM /dmo/booksuppl_m FOR ALL ENTRIES IN @booksuppls_db...
 Expand the following code sample to view the source code of method Save_Modified.
 Sample Code

PROTECTED SECTION.
ENDCLASS.
DATA booksuppls_db TYPE STANDARD TABLE OF /dmo/booksuppl_m.
" (1) Get instance data of all instances that have been created
IF create-booksuppl IS NOT INITIAL.
booksuppls_db = CORRESPONDING #( create-booksuppl ).
CALL FUNCTION '/DMO/FLIGHT_BOOKSUPPL_C' EXPORTING values =
booksuppls_db .
ENDIF.
" (2) Get instance data of all instances that have been updated during
the transaction
booksuppls_db = CORRESPONDING #( update-booksuppl ).
IF booksuppls_db IS NOT INITIAL.
" Read all field values from database
SELECT * FROM /dmo/booksuppl_m FOR ALL ENTRIES IN @booksuppls_db
WHERE booking_supplement_id = @booksuppls_db-
booking_supplement_id
INTO TABLE @booksuppls_db .
" Take over field values that have been changed during the transaction
LOOP AT update-booksuppl ASSIGNING FIELD-SYMBOL(<unmanaged_booksuppl>).
ASSIGN booksuppls_db[ travel_id = <unmanaged_booksuppl>-travel_id
booking_id = <unmanaged_booksuppl>-booking_id
booking_supplement_id = <unmanaged_booksuppl>-
booking_supplement_id
] TO FIELD-SYMBOL(<booksuppl_db>).
IF <unmanaged_booksuppl>-%control-supplement_id = if_abap_behv=>mk-on.

Develop PUBLIC 455
<booksuppl_db>-supplement_id = <unmanaged_booksuppl>-supplement_id.
ENDIF.
IF <unmanaged_booksuppl>-%control-price = if_abap_behv=>mk-on.
<booksuppl_db>-price = <unmanaged_booksuppl>-price.
ENDIF.
IF <unmanaged_booksuppl>-%control-currency_code = if_abap_behv=>mk-on.
<booksuppl_db>-currency_code = <unmanaged_booksuppl>-currency_code.
ENDIF.
ENDLOOP.
" Update the complete instance data
CALL FUNCTION '/DMO/FLIGHT_BOOKSUPPL_U' EXPORTING values =
booksuppls_db .
ENDIF.
" (3) Get keys of all travel instances that have been deleted during the
transaction
IF delete-booksuppl IS NOT INITIAL.
booksuppls_db = CORRESPONDING #( delete-booksuppl ).
CALL FUNCTION '/DMO/FLIGHT_BOOKSUPPL_D' EXPORTING values =
booksuppls_db .
ENDIF.
ENDMETHOD.

ENDCLASS.
4.2.2.4 Developing a Projection Layer for Flexible Service

Consumption
For a more flexible service consumption, every transactional business object is projected onto a service
specific context. In other words, only those elements of the data model and those behavior characteristics and
operations that are needed in the relevant business service context are exposed for the service. By means of
projections, you can expose one BO in different business contexts by using different BO subsets. The general
business logic is defined in the BO whereas the BO projection adopts a subset of the business logic.
A layering with projections enables robust application programming. You can change or enhance the BO
without changing the exposed service as the scope of the service is defined in the projection layer. Enhancing
the business object with additional structure or behavior does not have any effect on the resulting service.
Projection Layers in the Travel Business Scenario
The business object that you developed with the help of the previous sections is ready to run. It uses the
managed runtime for CRUD (create, read, update, delete) operations. In addition, the relevant business logic
for managing travels with action, determinations and validations was implemented. The BO CDS entities
expose every element that might be relevant for any business service scenario. The behavior is defined and
implemented for any kind of business service.
This demo scenario uses two projections with a different service scope. The resulting apps represent two
role-based approaches for managing travels:
One business object projection uses the BO characteristics and the operations that are relevant for processing
travel data. This resulting UI service serves the role of a data processor. The responsible person can enter the
information about travels, bookings and booking supplements into the role-based app for processing travel
data. This person needs functionality to create, update and delete entries on all three tiers of the business

456 PUBLIC Develop
object. In addition, the action copyTravel is designed to facilitate the creation of new travel entries. The
instance-bound action reads the values of the selected entry and its subentries and creates new entries based
on these values.
The other business object projection is the basis for a UI service that contains the functionality that is relevant
for an approver. Imagine a person, maybe a manager of a travel agency, that approves the data that was
entered by the processor. That means, this person sees the travel information and the corresponding booking
data. Based on this data, the approver can either accept or reject the travel. For a minimal scope of fields in
the travel entity the approver is enabled to edit the values, for example the BookingFee or the Description.
The information about bookings is set to read-only for the approver. The approver is not allowed to change the
fields of the booking entity.
See Business Scenario [page 378] for a detailed list of features for the respective roles.
The design time artifacts that you need for these projection scenarios are illustrated in the following figure. The
CDS views, as well as the behavior definition must be projected for both roles. To expose the BO projections
for a UI service, you need to create a service definition and binding for both BO projections. The behavior
implementation is not projected. Every behavior characteristic or operation that is used in the BO projection
must be implemented in the underlying BO implementation. You cannot define new behavior that needs
implementation in the BO projection.
Business Projections for the Processor and the Approver
1. Providing a Data Model for Projections [page 458]

1. Projection Views for the Processor BO Projection [page 459]
2. Projection Views for the Approver BO Projection [page 470]
2. Providing Behavior for Projections [page 476]

Develop PUBLIC 457
1. Behavior for the Processor BO Projection [page 477]
2. Behavior for the Approver BO Projection [page 478]
3. Defining Business Services Based on Projections [page 479]
Related Information
Business Object Projection [page 198]
4.2.2.4.1 Providing a Data Model for Projections
The data model for the BO projection is defined in CDS projection views. Projection views are data definition
artifacts with a syntax that differs slightly from CDS views. With projection views, you define the consumption-
specific data model.
For a detailed explanation of the syntax, see CDS Projection View [page 201].
Data Model in the Travel Scenario
For our travel scenario, the data models for the two projections have to be defined. For the processor BO,
all three entities of the underlying BO are projected; the approver BO only uses the travel entity and the
booking entity. All elements are aliased as an automatic mapping is provided for the elements in the projection
views. For both projections, we use all elements from the underlying CDS views and the associations that are
defined in the projected entity. For the processor BO, the only language-dependent text element in the booking
supplement entity must be localized to get the desription in the relevant language.
For both BO projections, the compositions have to be redirected.
UI Specifics for the Travel Scenario
Since the projection layer is the first service-specific layer, all UI specification must be defined in the CDS
projection views. In the travel scenario, the following UI specifics are relevant on the projection layer:
• UI annotations defining position, labels, and facets of UI elements

• Search Enablement
• Text elements (language dependent and independent)
• Value Helps
These features have to be defined via annotations in the projection views.
The following sections provide a detailed description on how to project the existing BO to define a data model
for one business object that is tailored to expose a UI service for a data processor and one that is tailored for a
data approver.
• Projection Views for the Processor BO Projection [page 459]

• Projection Views for the Approver BO Projection [page 470]

458 PUBLIC Develop
Related Information
CDS Projection View [page 201]
4.2.2.4.1.1 Projection Views for the Processor BO Projection
To define a data model for the BO projection that defines the scope for the processor application, the following
tasks need to be done:
• Creating the Projection CDS Views for the Processor [page 459]
• Defining the Data Model for the Processor Projection Views [page 460]
4.2.2.4.1.1.1 Creating the Projection CDS Views for the

Processor
A data processor needs to be able to create, update, and delete entries for the travel entity, the booking
entity, and the booking supplement entity. That means, all three nodes of the composition structure must be
projected.
For the following CDS views, create the corresponding projection views by choosing the projection view
template in the creation wizard for data definitions.
CDS views for BO /DMO/ /DMO/ /DMO/

structure I_TRAVEL_M I_BOOKING_M I_BOOKSUPPL_
M
CDS views for BO /DMO/ /DMO/ /DMO/
projection C_TRAVEL_PRO C_BOOKING_PR C_BOOKSUPPL_
CESSOR_M OCESSOR_M PROCESSOR_M
 Note
The names are assigned according to the naming conventions for projection views: Naming Conventions
for Development Objects [page 306].
For information about the syntax in projection views, see Define View Entity as Projection (ABAP Keyword
Documentation).

Develop PUBLIC 459
4.2.2.4.1.1.2 Defining the Data Model for the Processor
Projection Views
The following topics provide you with a detailed description on how to define the data model for the CDS
projection views that are used in the BO projection for the processor.
• Travel Projection View /DMO/C_TRAVEL_PROCESSOR_M [page 460]

• Booking Projection View /DMO/C_BOOKING_PROCESSOR_M [page 464]
• Booking Supplement Projection View /DMO/C_BOOKSUPPL_PROCESSOR_M [page 467]
4.2.2.4.1.1.2.1 Travel Projection View /DMO/C_TRAVEL_PROCESSOR_M
For the service specific projection, the elements as well as all the UI specifics need to be defined.
The data model defines which elements are exposed for the UI service. In addition, in data definitions for
projection views you define all UI specifications.
The following UI is achieved by implementing the corresponding features in the CDS Travel projection view for
the processor.
Preview: UI Application for Processor
Travel List Report
Travel Object Page

460 PUBLIC Develop
 Expand the following code sample to view the source code of the Travel Projection View /DMO/
C_Travel_Processor_M.
 Sample Code
@EndUserText.label: 'Travel projection view'

@UI: {
headerInfo: { typeName: 'Travel', typeNamePlural: 'Travels', title: { type:
#STANDARD, value: 'TravelID' } } }
define root view entity /DMO/C_Travel_Processor_M
provider contract transactional_query
as projection on /DMO/I_Travel_M
{
@UI.facet: [ { id: 'Travel',
purpose: #STANDARD,
label: 'Travel',
position: 10 },
{ id: 'Booking',
purpose: #STANDARD,
label: 'Booking',
position: 20,
targetElement: '_Booking'}]
@UI: {
lineItem: [ { position: 10, importance: #HIGH } ,
{ type: #FOR_ACTION, dataAction: 'copyTravel',
label: 'Copy Travel' } ],
identification: [ { position: 10, label: 'Travel ID' } ] }
key travel_id as TravelID,
@UI: {
lineItem: [ { position: 20, importance: #HIGH } ],
identification: [ { position: 20 } ],
selectionField: [ { position: 20 } ] }
@Consumption.valueHelpDefinition: [{ entity : {name: '/DMO/I_Agency',
element: 'AgencyID' } }]
@ObjectModel.text.element: ['AgencyName']
agency_id as AgencyID,
_Agency.Name as AgencyName,
@UI: {
@Consumption.valueHelpDefinition: [{ entity : {name: '/DMO/I_Customer',
element: 'CustomerID' } }]
@ObjectModel.text.element: ['CustomerName']
customer_id as CustomerID,
_Customer.LastName as CustomerName,
@UI: {
lineItem: [ { position: 40, importance: #MEDIUM } ],
identification: [ { position: 40 } ] }
begin_date as BeginDate,
@UI: {
end_date as EndDate,
@UI: {
booking_fee as BookingFee,
@UI: {

Develop PUBLIC 461
identification: [ { position: 43, label: 'Total Price' } ] }
@Consumption.valueHelpDefinition: [{entity: {name: 'I_Currency',
element: 'Currency' }}]
@UI: {
identification: [ { position: 45, label: 'Status' } ],
selectionField: [{ position: 40 }],
textArrangement: #TEXT_ONLY
}
I_Overall_Status_VH', element: 'OverallStatus' }}]
@ObjectModel.text.element: ['OverallStatusText']
overall_status as OverallStatus,
@UI.hidden: true
_OverallStatus._Text.Text as OverallStatusText : localized,
@UI: {
identification:[ { position: 46 } ] }
description as Description,
@UI.hidden: true
last_changed_at as LastChangedAt,
/* Associations */
_Booking : redirected to composition child /DMO/C_Booking_Processor_M,
_Agency,
_Customer,
_OverallStatus
}

Explanation
For the data model of the travel projection view in our scenario, you can adopt all elements of the projected
view, except for created_by, created_at and last_changed_by. Those element are not needed for our
service use cases. The element last_changed_at, however, is needed to store the eTag, but the other
administrative elements are not needed in the scenario. The other elements for travel information are used to
process travel data.
 Remember
The eTag is needed for optimistic concurrency check. In the travel BO, all nodes use their own master eTag.
All elements of the projection can be given an alias with an automatic mapping done by the service framework.
The travel projection view uses a subset of the associations that are defined in the projected view. _Agency,
_Customer and _OverallStatus are needed for text provisioning. These associations can simply be adopted
in the projection view. On the other hand, the composition to the child entity booking must be redirected as
the target entity changes in the projection layer. The association _Currency is not necessary in the projection
view. It is only defined in the underlying BO data model to represent a complete data model structure.
 Note
Before you can activate the travel projection root view for the processor, you need to create the booking
projection view with the redirection of the composition to parent in the booking projection child view.
Compositions must always be consistent from parent to child and vice-versa.
UI Specifics
The UI header information is given in an entity annotation to label the list report page.

462 PUBLIC Develop
The travel processor projection view is the root node of the BO projection. When opening the travel processing
app, the travel entries are displayed as list items with a navigation to their object page and the corresponding
bookings. From this object page, it is possible to navigate to the booking supplements. In the back end,
navigating is implemented by compositions. For the UI to enable navigation, UI facets need to be defined in the
travel projection view for the identification reference of the travel entity on the object page and for the line item
reference of the booking entity.
In addition, the elements for list items and the identification reference for the object page need to be annotated
in the projection view with the respective UI annotations to define position, importance and possible labels.
For more information about UI navigation and positioning of elements, see Designing the User Interface for a
Fiori Elements App [page 332] or UI Annotations [page 1260].
The annotations that are used in the projected entity are propagated to the projection view. You do not
need to reannotate elements with the same annotations as in the projected entity. However, if an annotation
draws reference to a specific element and the name of that specific element is changed with an alias in
the projection view, the propagated annotation keeps the reference that was given in the projected entity. A
semantic relationship between two elements can then be lost. In such a case, you have to reuse the same
annotation and use the alias name in the element reference of the annotation.
In our example scenario, this is the case for the semantic relationship between CurrencyCode and
TotalPrice or BookingFee. In the projection view, you do not need to annotate CurrencyCode with
@Semantics.currencyCode: true as this annotation is inherited from the projected entity. The annotation
@Semantics.amount.currencyCode: 'currency_code' is inherited as well, but the name of the field
has changed in the projection view. So you need to reannotate the element with the new alias name:
@Semantics.amount.currencyCode: 'CurrencyCode'.
 Tip
Check the Active AnnotationsView to find out which annotations are active for the current CDS view and
what the values of the active annotations are. For more information, see .
To be able to search for a specific data set, the travel projection view must be search enabled and at least one
element must be assigned as default search element. In addition, you can define selection fields to provide
a filter bar for certain elements. For more information about search enabling, see Enabling Text and Fuzzy
Searches in SAP Fiori Apps [page 897]. For more information about selection fields, see List Report Header
[page 335]
To access corresponding texts or descriptions, the relationship between the elements AgencyID,
CustomerID, OverallStatus and their text elements in the associated text provider views must be
established. The text elements of the text provider view must be integrated in the projection view. The
text provider view must be associated to the projection view and the text element in the text provider
view must be annotated with @Semantics.text: true. The annotation @ObjectModel.text.element:
establishes the link between the annotated element and its descriptive text element whose values are
displayed in the respective logon language. To indicate, that only the text element is to be displayed, the
annotation textArrangement: #TEXT_ONLY is used for the element OverallStatus. The denormalized
field OverallStatusText is hidden using the annotation @UI.hidden: true to prevent the display of
redundant information. For more information about text provisioning, see Working with Text Elements [page
891].
Especially for a data processing role, value helps are particularly important to find the necessary values for
the elements AgencyID, CustomerID, CurrencyCode and OverallStatus. Value helps are defined with

Develop PUBLIC 463
the annotation @Consumption.valueHelpDefinititon. The value help provider view does not have to be
associated to get the value help as the entity and the element are referenced in the annotation. For more
information, see Providing Value Help [page 776].
In the projection view, you also have to define the position of the execution button of actions, that you have
defined in the behavior definition. On the list report page, the position of the button for the action copyTravel
is defined. For more information about the action, see Developing Actions [page 405].
4.2.2.4.1.1.2.2 Booking Projection View /DMO/C_BOOKING_PROCESSOR_M
For the service-specific projection, the elements as well as all the UI specifics must be defined.
The data model defines which elements are exposed for the UI service. In addition, in data definitions you have
to define all UI specifications.
The following UI is achieved by implementing the corresponding features in the CDS Booking projection view
for the processor.
Booking List Report Page
Booking Object Page
 Expand the following code sample to view the source code of Booking Projection View /DMO/
C_Booking_Processor_M.
 Sample Code
@EndUserText.label: 'Booking projection view'

@UI: {
headerInfo: { typeName: 'Booking',
typeNamePlural: 'Bookings',
title: { type: #STANDARD, value: 'BookingID' } } }
define view entity /DMO/C_Booking_Processor_M
as projection on /DMO/I_Booking_M
{
@UI.facet: [ { id: 'Booking',

464 PUBLIC Develop
purpose: #STANDARD,
label: 'Booking',
position: 10 },
{ id: 'BookingSupplement',
purpose: #STANDARD,
label: 'Booking Supplement',
position: 20,
targetElement: '_BookSupplement'} ]
@UI: { lineItem: [ { position: 20, importance: #HIGH } ],
key booking_id as BookingID,
booking_date as BookingDate,
@Consumption.valueHelpDefinition: [{entity: {name: '/DMO/I_Customer',
element: 'CustomerID' }}]
@Consumption.valueHelpDefinition: [{entity: {name: '/DMO/I_Carrier',
element: 'AirlineID' }}]
@ObjectModel.text.element: ['CarrierName']
carrier_id as CarrierID,
_Carrier.Name as CarrierName,
@Consumption.valueHelpDefinition: [ {entity: {name: '/DMO/I_Flight',
element: 'ConnectionID'},
additionalBinding:
[ { localElement: 'FlightDate', element: 'FlightDate'},
{ localElement: 'CarrierID', element: 'AirlineID'},
{ localElement: 'FlightPrice', element: 'Price'},
{ localElement: 'CurrencyCode', element: 'CurrencyCode' } ] } ]

connection_id as ConnectionID,
element: 'FlightDate' },
additionalBinding:
[ { localElement: 'ConnectionID', element: 'ConnectionID'},
{ localElement: 'CarrierID', element: 'AirlineID'},
{ localElement: 'FlightPrice', element: 'Price' },
{ localElement: 'CurrencyCode', element: 'CurrencyCode' }]}]

flight_date as FlightDate,
flight_price as FlightPrice,

Develop PUBLIC 465
@UI: { lineItem: [ { position: 90, importance: #HIGH, label:
'Status' } ],
textArrangement: #TEXT_ONLY }
I_Booking_Status_VH', element: 'BookingStatus' }}]
@ObjectModel.text.element: ['BookingStatusText']
booking_status as BookingStatus,
@UI.hidden: true
_BookingStatus._Text.Text as BookingStatusText : localized,
@UI.hidden: true
/* Associations */
_Travel : redirected to parent /DMO/C_Travel_Processor_M,
_BookSupplement : redirected to composition child /DMO/
C_BookSuppl_Processor_M,
_Customer,
_Carrier,
_BookingStatus
}

Explanation
For the data model of the booking projection view, you can adopt all elements of the projected view.
The booking projection view uses a subset of the associations that are defined in the projected view.
The associations _Customer, _Carrier and _BookingStatusare needed for text provisioning. These
associations can simply be adopted in the projection view. On the other hand, the compositions to the parent
entity _Travel and to the child entity _BookSupplement must be redirected as the target entities change in
the projection layer. The association _Connection is not necessary in the projection view. It is defined in the
underlying BO data model to complete the BO data model structure.
 Note
Before you can activate the booking projection view for the processor, you need to create the booking
supplement projection view with the redirection to the composition to parent from the booking supplement
projection child view. Compositions must always be consistent from parent to child and vice-versa.
UI Specifics
Like in the travel projection view, the UI header information for the booking projection view is given in an entity
annotation.
For the UI to enable navigation from the Booking to the BookingSupplement entity, you need to define UI
facets. The booking entity must be defined as identification reference and the BookingSupplement as line item
reference.
In addition, the elements for list items and identification reference for the second navigation need to be
annotated in the booking projection view with the respective UI annotations to define position, importance,
and possible labels.
As in the travel projection view, the annotation @Semantics.amount.currencyCode: 'CurrencyCode'

needs to be repeated in the projection view, since the annotation value changes due to aliasing.

466 PUBLIC Develop
To be able to search for a specific data set, the booking projection view must be search enabled and at least
one element must be assigned as default search element. For more information about search enabling, see
Enabling Text and Fuzzy Searches in SAP Fiori Apps [page 897].
To access the corresponding texts or descriptions, the relationship between the elements CarrierID,
BookingStatus and their text element in the associated text provider view must be established. Therefore,
you need the association to the text provider view. The text element of the text provider view must be
integrated in the projection view. The text provider view must be associated to the projection view and the
text element in the text provider view must be annotated with @Semantics.text: true. The annotation
@ObjectModel.text.element: establishes the link between the annotated element and its descriptive text
element whose values are displayed in the respective logon language. To indicate, that only the text element is
to be displayed, the annotation textArrangement: #TEXT_ONLY is used for the element BookingStatus.
The denormalized field BookingStatusText is hidden using the annotation @UI.hidden: true to prevent
the display of redundant information. For more information about text provisioning, see Working with Text
Elements [page 891].
Especially for a data processing role, value helps are important to find the necessary values for the elements
CustomerID, CarrierID, ConnectionID and to find adequate values for FlightDate, CurrencyCode and
BookingStatus. Value helps are defined with the annotation @Consumption.valueHelpDefinititon. The
value help for ConnectionID and FlightDate use additional bindings, so that only those values appear that
match the entries in the given local elements. The value help provider view does not have to be associated
to get the value help as the entity and the element are referenced in the annotation. However, it needs to be
included in the service definition. For more information, see Providing Value Help [page 776].
The administrative field last_changed_at is only used for concurrent processing and does not have to be
displayed on the UI. The annotation @UI.hidden = true is used for that purpose.
4.2.2.4.1.1.2.3 Booking Supplement Projection View /DMO/

C_BOOKSUPPL_PROCESSOR_M
For the service-specific projection, the elements as well as all the UI specifics must be defined.
The following UI is achieved by implementing the corresponding features in the CDS Booking Supplement
projection view for the processor.

Develop PUBLIC 467
Booking Supplement List Report Page
 Expand the following code sample to view the source code of Booking Supplement Projection View /DMO/
C_BookSuppl_Processor_M.
 Sample Code
@EndUserText.label: 'Booking supplement projection view'

@UI: { headerInfo: { typeName: 'Booking Supplement',
typeNamePlural: 'Booking Supplements',
title: { type: #STANDARD,
value: 'BookingSupplementID' } } }
define view entity /DMO/C_BookSuppl_Processor_M as projection on /DMO/
I_BookSuppl_M
{
@UI.facet: [ { id: 'BookingSupplement',
purpose: #STANDARD,
position: 10 } ]
key booking_supplement_id as BookingSupplementID,
@Consumption.valueHelpDefinition: [ {entity: {name: '/DMO/I_SUPPLEMENT',
element: 'SupplementID' } ,
additionalBinding: [ { localElement:
'Price', element: 'Price' },
{ localElement:
'CurrencyCode', element: 'CurrencyCode' }] }]
@ObjectModel.text.element: ['SupplementDescription']
supplement_id as SupplementID,
_SupplementText.Description as SupplementDescription:
localized,


468 PUBLIC Develop
price as Price,
@Consumption.valueHelpDefinition: [{entity: {name: 'I_Currency', element:
'Currency' }}]
@UI.hidden: true
/* Associations */
_Travel : redirected to /DMO/C_Travel_Processor_M,
_Booking : redirected to parent /DMO/C_Booking_Processor_M,
_SupplementText
}

For the data model of the booking supplement projection view, you can adopt all elements of the projected
view.
The booking supplement projection view uses a subset of the associations that are defined in the projected
view. The association _SupplementText is needed for text provisioning. This association can simply be
adopted in the projection view. On the other hand, the composition to the parent entity _Booking and to the
root entity _Travel must be redirected as the target entity changes in the projection layer. The association
_Supplement is not necessary in the projection view of the service context. It is defined in the underlying BO
data model to complete the BO data model structure.
 Note
Now, that all compositions are redirected, you can activate the three projection views for the processor.
UI Specifics
Like in the travel and the booking projection view, the UI header information for the booking supplement
projection view is given in an entity annotation.
 Restriction
The Fiori Elements Preview does not support the navigation to more than one child entity. Hence, when
accessing the preview via entity set Travel and association to_Booking, it is not possible to navigate
to the object page of the BookingSupplement entity. That means, some of the UI annotations are not
relevant if you only use the preview to test your application. For example, the UI annotations referring to
identification cannot be shown in the preview, when testing via the root node Travel.
However, if you want to develop a real application or test your service with the Web IDE, you can configure
the application to enable navigation to any number of child entities. That is why, the UI annotation
concerning identification are included in the following description.
You can imitate the behavior of the Web IDE for the second-level navigation by accessing the Fiori Elements
Preview via entity set Booking and Association to_BookSupplement.
To show the entries of the booking supplement entity on its object page, the UI facet for
#IDENTIFICATION_REFERENCE must be defined.
In addition, the elements for list items (to appear on the object page of the booking entity) and identification
must be annotated in the Booking Supplement projection view with the respective UI annotation to define
position, importance, and possible labels.

Develop PUBLIC 469
As in the travel projection view, the annotation @Semantics.amount.currencyCode: 'CurrencyCode'
needs to be repeated in the projection view, since the annotation value changes due to aliasing.
To be able to search for a specific data set, the booking supplement projection view must be search enabled
and at least one element must be assigned as default search element. For more information about search
enabling, see Enabling Text and Fuzzy Searches in SAP Fiori Apps [page 897].
To access the corresponding texts or descriptions for ID elements, the relationship between the element
SupplementID and its text element in the associated text provider view must be established. Therefore, you
need the association to the text provider view. The text element of the text provider view must be integrated
in the projection view. The text provider view must be associated to the projection view and the text element
in the text provider view must be annotated with @Semantics.text: true. For more information about text
provisioning, see Working with Text Elements [page 891].
Especially for a data processing role, value helps are important to find the necessary values for the
ID element SupplementID as well as for CurrencyCode. Value helps are defined with the annotation
@Consumption.valueHelpDefinititon. The value help for SupplementID uses additional binding, so that
only those values appear that match the entry in the field CurrencyCode field. The value help provider view
does not have to be associated to get the value help as the entity and the element are referenced in the
annotation. For more information, see Providing Value Help [page 776].
The administrative field last_changed_at is only used for concurrent processing and does not have to be
displayed on the UI. The annotations @UI.hidden = true is used for that purpose.
4.2.2.4.1.2 Projection Views for the Approver BO Projection
To define a data model for the BO projection that defines the scope for the approver application, the following
tasks need to be done:
• Creating the Projection CDS Views for the Approver [page 470]
• Defining the Data Model for the Approver Projection Views [page 471]
4.2.2.4.1.2.1 Creating the Projection CDS Views for the

Approver
The scope of the UI service for the approver is more limited than for the processor. The approver can only
modify the travel entity with accepting or rejecting the travel entries. The values in the corresponding booking
entries are the basis for this decision-making. Only these two entities are relevant for the approver app. That
means, only these two entities must be projected for the approver BO projection.
For the following CDS views, create the corresponding projection views by choosing the projection view
template in the creation wizard for data definitions.
CDS views for BO /DMO/ /DMO/

structure I_TRAVEL_M I_BOOKING_M

470 PUBLIC Develop
projection C_TRAVEL_APP C_BOOKING_AP
ROVER_M PROVER_M
 Note
The resulting CDS projection views must have the following syntax:
define [root] view entity <projection_view>

[provider contract transactional_query]

as projection on <projected_view>
For more information about the syntax in projection views, see Define View Entity as Projection (ABAP Keyword
Documentation).
4.2.2.4.1.2.2 Defining the Data Model for the Approver

Projection Views
The following topics provide you with a detailed description on how to define the data model for the CDS
projection views that are used in the BO projection for the approver.
• Travel Projection View /DMO/C_TRAVEL_APPROVER_M [page 471]

• Booking Projection View /DMO/C_BOOKING_APPROVER_M [page 474]
4.2.2.4.1.2.2.1 Travel Projection View /DMO/C_TRAVEL_APPROVER_M
For the service-specific projection, the elements as well as all the UI specifics for the approver BO projection
must be defined.
The following UI is achieved by implementing the corresponding features in the CDS Travel projection view for
the approver.

Develop PUBLIC 471
Preview: UI Application for Approver
Travel List Report Page
Travel Object Page
 Expand the following code sample to view the source code of Travel Projection View /DMO/
C_Travel_Approver_m.
 Sample Code
@EndUserText.label: 'Travel projection view'

@UI: {
headerInfo: { typeName: 'Travel', typeNamePlural: 'Travels', title: { type:
#STANDARD, value: 'TravelID' } } }
define root view entity /DMO/C_Travel_Approver_M
as projection on /DMO/I_Travel_M
{
purpose: #STANDARD,
label: 'Travel',
position: 10 } ,
{ id: 'Booking',
purpose: #STANDARD,
label: 'Booking',
position: 20,
@UI: {
@UI: {

472 PUBLIC Develop
@Consumption.valueHelpDefinition: [ { entity : {name: '/DMO/I_Agency',
element: 'AgencyID' } } ]
@UI: {
@Consumption.valueHelpDefinition: [ { entity : {name: '/DMO/
I_Customer', element: 'CustomerID' } } ]
@UI: {
@UI: {
@UI: {
@UI: {
identification: [ { position: 43, label: 'Total Price' } ] }
@Consumption.valueHelpDefinition: [ {entity: {name: 'I_Currency',
element: 'Currency' } } ]
@UI: {
lineItem: [ { position: 15, importance: #HIGH },
{ type: #FOR_ACTION, dataAction: 'acceptTravel',
label: 'Accept Travel' },
{ type: #FOR_ACTION, dataAction: 'rejectTravel',
label: 'Reject Travel' } ],
identification: [ { position: 15 },
label: 'Reject Travel' } ] ,
textArrangement: #TEXT_ONLY,
@EndUserText.label: 'Overall Status'
I_Overall_Status_VH', element: 'OverallStatus' }}]
@UI.hidden: true
@UI: {
/* Admininstrative fields */
@UI.hidden: true
/* Associations */

Develop PUBLIC 473
_Booking : redirected to composition child /DMO/C_Booking_Approver_M,
_Agency,
_Customer,
_OverallStatus
}

Explanation
Except for the actions, which are different in the processor and the approver projection, the CDS projection
views for the processor and the approver BO are identical. Refer to explanation [page 462] for a thorough
description on the travel projection view.
Actions
The position and the label for the action button must be defined in the CDS projection views. In the case of an
approver, the available actions concerning the travel entity set are Accept Travel and Reject Travel. The
implementation of these actions is done in the behavior pool, see Developing Actions [page 405]. It is simply
the UI appearance that needs to be configured in the projection view. The action buttons for the respective
actions are designed to appear on the travel list report page and on the travel object page. That is why the
annotations are used in the list item and identification UI annotation. When executing the action on the list
report page, a travel instance must be selected to assign an instance for the instance-bound action. On the
object page, the instance for which the action shall be executed is clear. For more information about the
annotations to define the action buttons, see Enabling Actions for UI Consumption [page 414].
4.2.2.4.1.2.2.2 Booking Projection View /DMO/C_BOOKING_APPROVER_M
Preview: UI Application Approver
Booking List Report Page

474 PUBLIC Develop
Booking Object Page
 Expand the following code sample to view the source code of Booking Projection View /DMO/
C_Booking_Approver_M.
 Sample Code
@EndUserText.label: 'Booking projection view'

@UI: {
title: { type: #STANDARD, value: 'BookingID' }
}
}
define view entity /DMO/C_Booking_Approver_M
as projection on /DMO/I_Booking_M
{
purpose: #STANDARD,
label: 'Booking',
position: 10 }]
selectionField: [{ position: 10 }]
}
carrier_id as CarrierID,

Develop PUBLIC 475
@UI: { lineItem: [ { position: 90, importance: #HIGH, label:
'Status' } ],
@UI.hidden: true
_BookingStatus._Text.Text as BookingStatusText : localized,
/* Admininstrative fields */
@UI.hidden: true
/* Associations */
_Travel : redirected to parent /DMO/C_Travel_Approver_M,
_Customer,
_Carrier,
_BookingStatus
}

Explanation
The CDS projection views for the processor and the approver BO are almost identical. Refer to Booking
Projection View /DMO/C_BOOKING_PROCESSOR_M [page 464] for a thorough description on the booking
projection view.
4.2.2.4.2 Providing Behavior for Projections
The behavior for the BO projection is defined in a behavior definition of type projection. The type is defined
in the behavior definition header. The projection behavior definition provides the behavior for the projection
CDS view. All characteristics and operations that you want to include in the BO projection must be listed
explicitly. The keyword for this is use.
For a detailed description on the syntax of projection behavior definitions, see CDS BDL - CDS behavior
definition header, projection BDEF (ABAP - Keyword Documentation) andCDS BDL - entity behavior definition,
projection BDEF (ABAP - Keyword Documentation) .
Defining the BO Projection Behavior in the Travel Scenario
As described in Reference Business Scenario [page 375], the BO projections for the processor and the
approver differ with regard to their behavior. The following sections provide a detailed description on how
to project the existing BO to define a behavior for one business object that is tailored to expose a UI service for
a data processor and one that is tailored for a data approver.
• Behavior for the Processor BO Projection [page 477]

• Behavior for the Approver BO Projection [page 478]

476 PUBLIC Develop
Related Information
Projection Behavior Definition [page 203]
4.2.2.4.2.1 Behavior for the Processor BO Projection
The behavior for the BO projection that defines the scope for the processor application is defined in a behavior
definition with type projection.
4.2.2.4.2.1.1 Creating a Behavior Definition for the Processor

BO Projection
The easiest way to create a projection behavior definition is to use the context menu in the project explorer
by selecting the relevant projection root view /DMO/C_TRAVEL_PROCESSOR_M and choosing New Behavior
Definition. The behavior definition always uses the same name as the corresponding root view.
As the behavior definition is created on the basis of the root projection view, the template with type
projection is generated.
4.2.2.4.2.1.2 Defining the Behavior for the Processor BO

Projection
When creating the behavior definition based on the projection view, the template automatically creates the
type projection and lists all available characteristics and operations of the underlying behavior definition.
That means, if nothing is done explicitly the BO projection has exactly the same behavior as the underlying BO.
For the processor projection, only the following elements are used:
projection;

strict;
define behavior for /DMO/C_Travel_Processor_M alias TravelProcessor
use etag
{
field ( readonly ) TotalPrice;
use create;
use update;
use delete;
use action copyTravel;
use association _BOOKING { create; }
}
define behavior for /DMO/C_Booking_Processor_M alias BookingProcessor
use etag
{
use update;

Develop PUBLIC 477
// use delete; // workaround for missing determination on delete
use association _BOOKSUPPLEMENT { create; }
use association _Travel { }
}
define behavior for /DMO/C_BookSuppl_Processor_M alias BookSupplProcessor
use etag
{
use update;
// use delete; // workaround for missing determination on delete
use association _Travel { }
use association _Booking { }

}
Explanation
Only the characteristics and operations that are relevant for the processor are used in the projection behavior
definition. This is only a subset of the behavior that was defined in the underlying BO. See Developing Business
Logic [page 394] to compare the projection BO to the underlying one.
The ETag handling that was defined in the underlying BO is used for all three entities. Especially for the
processor role, which is enabled to modify, it is necessary to have a concurrency check. By using a master ETag
on all entities, concurrent processing is enabled for the travel BO.
The static field control that was defined for the underlying BO cannot be modified.
All standard operations are used for the processor on all the root entity. The child entities can only be created
via a create_by_association. The delete is not enabled for the view Booking and BookingSupplement
as the determination to calculate the total flight price is not triggered on delete.
For the travel entity, the action to copy travels is enabled for the processor.
4.2.2.4.2.2 Behavior for the Approver BO Projection
The behavior for the BO projection that defines the scope for the approver application id defined in a behavior
definition with type projection.
4.2.2.4.2.2.1 Creating a Behavior Definition for the Approver

BO Projection
The easiest way to create a projection behavior definition is to use the context menu in the project explorer
by selecting the relevant projection root view /DMO/C_TRAVEL_APPROVER_M and choosing New Behavior
Definition. The behavior definition always uses the same name as the corresponding root view.
As the behavior definition is created on the basis of the root projection view, the template with type
projection is generated.

478 PUBLIC Develop
4.2.2.4.2.2.2 Defining the Behavior for the Approver BO
Projection
When creating the behavior definition based on the projection, the template automatically creates the type
projection and lists all available characteristics and operations of the underlying behavior definition. That
means, if nothing is done explicitly the BO projection has exactly the same behavior as the underlying BO.
For the approver projection, only the following elements are used:
projection;

strict;
define behavior for /DMO/C_Travel_Approver_M alias Approver
use etag
{
field ( readonly ) BeginDate, EndDate, TotalPrice, CustomerID;
use update;
use action acceptTravel;
use action rejectTravel;
}

Explanation
Only the characteristics and operations that are relevant for the approver are used in the projection behavior
definition. This is only a subset of the behavior that was defined in the underlying BO. See Developing Business
Logic [page 394] to compare the projection BO to the underlying one.
The eTag that was defined in the underlying BO is used in the approver projection as well. The concurrency
check is relevant for the approver. It must be ensured that the data has not been changed between checking
the data and executing the action accept or reject travel.
The static field control that was defined for the underlying BO cannot be modified. However, new controls are
added to correspond the approver role. The fields that are mandatory for the processor are set to read-only
for the approver. In the approver application, one can only change the fields OverallStatus, AgencyID,
BookingFee and Description.
The update operation is enabled for the approver as a modification on the travel entries must be available.
The actions accept and reject are enabled to change the status of the travel entry.
There is no behavior defined for the booking entity. All fields are read-only in this case.
The booking supplement entity is not part of the approver BO projection, so there is no behavior for this entity
either.
4.2.2.5 Defining Business Services Based on Projections
With the help of the previous sections, you developed a business object and its projection for two
complementary business roles. The next step is to build a business service for both projections in order to
consume the business object. The business service defines the scope of the service and binds it to a specific
OData protocol. For more information, see Business Service [page 196].

Develop PUBLIC 479
This scenario is designed to build a UI service for both business object projections. Follow the development
steps to build an application for both BO projections. For a detailed step-by-step description, see Creating an
OData Service [page 323].
1. Create a service definition for the processor service and one for the approver service.
2. Expose the relevant CDS views for each service.
 Note
Only the projection CDS views of the business object projection must be exposed for the service. The
delegation to the underlying BO is automatically done.
1. Service Definition for Processor Service:
@EndUserText.label: 'Service definition for managing travels'

@ObjectModel.leadingEntity.name: '/DMO/C_Travel_Processor_M'
define service /DMO/UI_TRAVEL_PROCESSOR_M {
expose /DMO/C_Travel_Processor_M as Travel;
expose /DMO/C_Booking_Processor_M as Booking;
expose /DMO/C_BookSuppl_Processor_M as BookingSupplement;
expose /DMO/I_Supplement_StdVH as Supplement;
expose /DMO/I_SupplementCategory_VH as SupplementCategory;
expose /DMO/I_Customer_StdVH as Passenger;
expose /DMO/I_Agency_StdVH as TravelAgency;
expose /DMO/I_Carrier_StdVH as Airline;
expose /DMO/I_Connection_StdVH as FlightConnection;
expose /DMO/I_Flight_StdVH as Flight;
expose /DMO/I_Airport_StdVH as Airport;
expose /DMO/I_Overall_Status_VH as OverallStatus;
expose /DMO/I_Booking_Status_VH as BookingStatus;
expose I_CurrencyStdVH as Currency;
expose I_CountryVH as Country;

}
The complete composition hierarchy is exposed for the data processing service. In addition, the text
and value help provider views are necessary components of the service scope to get the respective
feature for the service.
2. Service Definition for Approver Service

@ObjectModel.leadingEntity.name: '/DMO/C_Travel_Approver_M'
define service /DMO/UI_TRAVEL_APPROVER_M {
expose /DMO/C_Travel_Approver_M as Travel;
expose /DMO/C_Booking_Approver_M as Booking;
expose /DMO/I_Customer as Passenger;
expose /DMO/I_Agency as TravelAgency;
expose /DMO/I_Overall_Status_VH as OverallStatusVH;
expose /DMO/I_Booking_Status_VH as BookingStatusVH;

}
The approver service contains only two entities of the travel BO and a more limited number of text and
value help provider views.
3. Create a service binding with binding type ODATA V2 - UI for both service definitions and activate the
local service endpoints.
As soon as the service is activated, it is ready for consumption through an OData client such as an
SAP Fiori app. You can use the preview function in the service binding to check how the UI of the Fiori
application looks like.

480 PUBLIC Develop
4.2.3 Developing Unmanaged Transactional Apps
This section explains the main development tasks required for enabling transactional processing in a business
objects provider that integrates existing business logic.
Based on an end-to-end example, you create and implement all requisite artifacts for providing OData services
that combine CDS data model and business object semantics with transactional processing from legacy
application logic.
Introduction
In unmanaged business objects, the application developer must implement essential components of the REST
contract. There is no standard functionality provided by the RAP framework. It is only the frame of a business
object, that an application developer needs to adhere to. The behavior must be specified in the behavior
definition but implemented manually in ABAP classes in the behavior pool. All existing business logic can be
integrated, including standard behavior like create, update and delete. In addition, the transactional buffer
must be provided and handled by the application developer in the ABAP behavior pool.
 Note
In a managed implementation type, on the other hand, a behavior definition would on its own be sufficient
to obtain a ready-to-run business object.
The underlying scenario reuses the existing business application logic and the existing persistence, which
manages business data.
Architecture Overview – Integration of Existing Application Logic
Prerequisites

Develop PUBLIC 481
 Restriction
 Remember
However, if you want to recreate all development objects of this demo content, make sure that you use
different names from this documentation.
Development Process in Overview
The development of new business services by integrating the transactional behavior of an existing (legacy)
application mainly requires developers to perform the following fundamental activities:
1. Defining a CDS Data Model and the Business Object Structure

The formal structure of a business object consists of a tree of entities (Travel, Booking, Passenger, and so on)
where the entities are linked using associations. Each entity of this tree structure is an element that is modeled
with a CDS entity. Entities of this kind are CDS views that are generally defined on top of the underlying
persistence layer, which in turn is based on the corresponding database tables or public interface CDS views.
The root entity is of particular importance: this is indicated in the source code of the CDS data definition by the
keyword ROOT. The root entity is a representation of the business object and defines the top node in a business
object's structure.
The structure of the business object is projected in CDS projection views where you can define service-
specifics for the data model. For the UI-related annotations, metadata extensions are used to separate data
model from domain-specific semantics
More on this: Providing CDS Data Model with Business Object Structure [page 487]
2. Defining and Implementing the Transactional Behavior of Business Objects
Each node of a business object can offer the standard operations create(), update(), and delete() and
specific operations with a dedicated input and output structure known as actions. All operations provided by a
business object are defined in the behavior definition artifact that is created as an ABAP repository object.

482 PUBLIC Develop
The implementation of the transactional behavior is done in specific class pools, which refer to the behavior
definition. The concrete implementation of the business object provider is based on the ABAP language (which
has been expanded from the standard with a special syntax) and the corresponding API for Implementing the
Unmanaged BO Contract. The implementation tasks are roughly divided into an interaction phase and a save
sequence.
The behavior that is relevant for the specific UI service is then projected in projection behavior definition.
More on this: Defining and Implementing Behavior of the Business Object [page 507]
3. Exposing the Relevant Application Artifacts for OData Service Enablement
For the service enablement, the relevant artifacts must be exposed to OData as a canonical OData service. This
is implemented by data and behavior models, where the data model and the related behavior is projected in
a service-specific way. This projection is separated into two different artifacts: the service definition and the
service binding. The service definition is a projection of the data model and the related behavior to be exposed,
whereas the service binding implements a specific protocol and the kind of service to be offered to a consumer.
More on this: Defining Business Service for Fiori UI [page 563]
4. Testing the OData (UI) Service
In ABAP Development Tools, you have the option of publishing the service to the local system repository. As
soon as the service is published, it is ready for consumption through an OData client, such as an SAP Fiori app.
The service binding editor offers a preview tool that you can use for testing the resulting app within your ABAP
development environment.
 Note
Via ABAPGit You can import the service including the related development objects into your development
environment for comparison and reuse. You find the service in the package /DMO/FLIGHT_UNMANAGED.
The suffix for development objects in this development guide is _U.
4.2.3.1 Reference Business Scenario
The Managing of Flight Travels scenario used in this guide provides an example of an existing stateful
business application whose business logic is reused in the new implementation for transactional apps. This
application represents only a part of the full ABAP Flight Reference Scenario (in short: Flight Scenario) that is
intended to be used for demonstration and learning purposes in the context of the ABAP RESTful programming
model.
The application demo provided (which represents a legacy stateful application) allows a user to create and
manipulate flight bookings. It involves different data sources and entities such as travel, travel agencies,
customers (passengers), flights, and bookings. Some of these are editable (that is, they can be created or
manipulated) and some are not.

Develop PUBLIC 483
Persistency and Data Model of an Existing Application
The following table gives an overview of the different travel entities involved in the current scenario, including a
categorization into editable and non-editable entities.
Flight Reference Scenario Objects Involved in the Business Scenario
Entity Description Editable
Travel A Travel entity defines general travel data, such as the agency ID or customer Yes
ID, status of the travel booking, and the price of travel. The travel data is stored in
the database table /DMO/TRAVEL.
Agency An Agency entity defines travel agency data, such as the address and contact No
data. The corresponding data is stored in the database table /DMO/AGENCY.

The flight data model defines a 1:n cardinality between Agency and Travel.
Booking The booking data is stored in the database table /DMO/BOOKING. The flight Yes
data model defines a 1:n cardinality between a Travel and the Booking
entity.
Flight The specific flight data for each connection is stored in the database ta- No
ble /DMO/FLIGHT. The flight data model defines a 1:n cardinality between
a Connection and the Flight entity.
Connection The flight connections are stored in the database table /DMO/CONNECTION. No
Carrier The IDs and names of airlines are stored in the database table /DMO/CARRIER. No
Each airline has a number of flight connections. Therefore, the data model de-
fines a 1:n cardinality between a Carrier and the Connection entity.
Customer A Customer entity provides a detailed description of a flight customer (passen- No

ger) such as the name, the address, and contact data.
The corresponding data is stored in the database table /DMO/CUSTOMER. The

flight data model defines a 1:n cardinality between Customer and Travel.
Booking This entity is used to add additional products to a travel booking. The booking Yes
Supplement supplement data is stored in the database table /DMO/BOOK_SUPPL. The flight
data model defines an n:1 cardinality between a Booking Supplement
entity and a Booking entity.
Supplement A Supplement entity defines product data that the customer can book to- No
gether with a flight, for example a drink or a meal.
The supplement data is stored in the database table /DMO/SUPPLEMENT. The

flight data model defines a 1:1 cardinality between a Supplement entity and
the Booking Supplement entity.

484 PUBLIC Develop
Travel Status This entity is used to provide the possible values for the travel status. The cor- No
responding data is stored in the database table /dmo/trvl_stat. The flight

data model defines a 1:1 cardinality between Travel and Travel Status.
The localized texts for the travel statuses are provided by the Travel Status
Text entity.
Travel Status This entity is used to provide the localized texts for the travel statuses. The corre- No
Text sponding data is stored in the database table /dmo/trvl_stat_t. The flight
data model defines a 1:N cardinality between Travel Status and Travel
Status Text.
Compositions and Associations
The figure below shows the relationships between the travel, travel status, agency, customer, and booking
entities, where the travel entity represents the root of the data model. Additional entities for currencies
(I_Currency) and countries (I_Country) are generally available in your system and are included in our data
model using associations.
 Note
For didactic reasons, we have kept the data model as simple as possible. We have hence reduced the
number of entities in our end-to-end guide (compared with the predefined ABAP flight model) to a
minimum set of entities.

Develop PUBLIC 485
Travel Entities Involved in the Present Scenario and Their Relationships
Business Logic
The following figure summarizes the essential elements of the business logic:
• The function group /DMO/FLIGHT_TRAVEL_API is used to group all function modules that represent the
application’s legacy code.
• The class /DMO/CL_FLIGHT_LEGACY provides the actual implementation of the business logic in a more
convenient (object-oriented) way.
• The interface /DMO/IF_FLIGHT_LEGACY defines global types and constants for reuse.
• Exception class /DMO/CX_FLIGHT_LEGACY.

486 PUBLIC Develop
Main Elements of the Legacy Business Logic
4.2.3.2 Providing CDS Data Model with Business Object

Structure
From a structural point of view, a business object consists of a tree of entities that are linked by special
associations known as compositions. A composition is a specialized association that defines a whole-part
relationship. A composite part only exists together with its parent entity (whole).
 Note
For didactic reasons, we will demonstrate a one-level composition in our sample application, defining a root
entity for the Travel BO and one child entity for bookings. This relationship also means that booking data
can only be created to a given travel instance.
Every entity in this composition tree is an element that is modeled with a CDS entity. The root entity is
of particular importance, since it defines the top node in a business object's structure and serves as a
representation of the business object. This is considered in the source code of the CDS data definition with the
keyword ROOT when defining the corresponding CDS entity.
For details about the syntax for defining a root entity, see CDS DDL - DEFINE VIEW ENTITY (ABAP- Keyword
Documentation)

Develop PUBLIC 487
Effect:
Using this syntax, you define the root_entity as a root of the compositional hierarchy for the business object
to be created.
With the keyword COMPOSITION, a child_entity is defined as a direct child entity to the business object’s
root. The child_entity is a CDS entity, which is the target of the composition. _comp_name defines the
name of the composition and must be added to the element_list (like associations). The cardinality to the
child entity is expressed in the composition definition with square brackets [min .. max].
For min and max, positive integers (including 0) and asterisks (*) can be specified:
• max cannot be 0.
• An asterisk * for max means any number of rows.
• min cannot be *.
The meaning of the other elements of the syntax is identical to that of DEFINE VIEW ENTITY.
Further information: Define View Entity as Projection (ABAP Keyword Documentation)
For details about the syntax for defining a child entity, see CDS DDL - DEFINE VIEW ENTITY (ABAP- Keyword
Documentation)
Effect:
Using this syntax, you define a CDS entity child_entity that serves as a sub node in the compositional
hierarchy of the business object structure. The sub node is a node in a business object's structure that is
directly connected to another node when moving away from the root.
CDS entities that do not represent the root node of the hierarchy must have an association to their
compositional parent entity parent_entity or root_entity. This relationship is expressed by the keyword
ASSOCIATION TO PARENT...
The meaning of the other elements in the association syntax is identical to that of ASSOCIATION in the CDS
SELECT statement.
Next Steps
Creating Data Definitions for CDS Views [page 489]
Defining the Data Model in CDS Views [page 491]

488 PUBLIC Develop
4.2.3.2.1 Creating Data Definitions for CDS Views
In this step you create a CDS views as the basis for the data model of our demo scenario. To do this, you create
the appropriate data definitions as transportable ABAP repository objects, as specified in the table below.
Data Definitions and CDS Views to Create
 Note
Naming CDS views: Since CDS views are (public) interface views, they are prefixed with I_ in accordance
with the VDM (virtual data model) naming convention. In addition, we add the suffix _U to the view name in
case it is specific for our unmanaged implementation type scenario. For detailed information, see: Naming
Conventions for Development Objects [page 306]
 Remember
The namespace /DMO/ is reserved for the demo content. Therefore, do not use the namespace /DMO/
when creating your own development objects and do not create any development objects in the
downloaded packages.
Data Definitions Required for the Root Node (Travel):
Data Definition
/DMO/I_TRAVEL_U /DMO/ This CDS view defines the root entity. The root entity is a represen-
TRAVEL tation of the travel business object and defines the top node in a
/DMO/I_Travel_U
business object's structure.
(DB table)
It is used for managing general travel data, such as the booking status
of a travel or the total price of a travel.
/DMO/I_AGENCY /DMO/ This CDS view represents the travel agency in the data model of our
AGENCY demo scenario.

/DMO/I_Agency
(DB table)
/DMO/I_CUSTOMER /DMO/ This CDS view defines the data model for managing flight travel cus-
CUSTOMER tomers (passengers).

/DMO/I_Customer
(DB table)
/DMO/I_TRAVEL_STATUS_VH /dmo/ This CDS view defines the data model for managing travel statuses.
/DMO/ trvl_stat
I_Travel_Status_VH (DB table)

Develop PUBLIC 489
Data Definition
/DMO/ /dmo/ This CDS view defines the data model for managing localized texts of
I_TRAVEL_STATUS_VH_TEXT trvl_stat_ travel statuses.
/DMO/ t
I_Travel_Status_VH_Tex (DB table)
t
Data Definitions Required for the Sub Node (Booking):
Data Definition
/DMO/I_BOOKING_U /DMO/ This CDS view defines the flight booking entity. The booking entity is
BOOKING a sub node representation of the travel business object structure. .

/DMO/I_Booking_U
(DB table) It is used for managing flight booking data, such as the customer, the
flight connection, or the price and flight date.
/DMO/I_FLIGHT /DMO/ This CDS view represents the concrete flights in the travel data
FLIGHT model. In our demo scenario, the CDS view is used for value help
/DMO/I_Flight
definition for specific elements in the booking view.
(DB table)
/DMO/I_CONNECTION /DMO/ This CDS view defines the data model for managing flight connec-
/DMO/I_Connection CONNECTION tions.
(DB table) In our demo scenario, the connection view is used to retrieve the text
information for the associated elements in the booking view.
/DMO/I_CARRIER /DMO/ This CDS view defines the data model for managing the airline data
CARRIER (ID and the name).

/DMO/I_Carrier
(DB table) In our demo scenario, the carrier view is used to retrieve the text
information for the associated elements in the booking view.
Procedure: Creating a Data Definition
To launch the wizard tool for creating a data definition, do the following:

2. In your ABAP project (or ABAP cloud project), select the relevant package node in Project Explorer.
3. Open the context menu and choose New Other ABAP Repository Object Core Data Services Data
Definition

490 PUBLIC Develop
Results
This procedure creates a data definition as a transportable development object in the selected package. For
each data definition, the related CDS view is created.
4.2.3.2.2 Defining the Data Model in CDS Views
Travel Root View /DMO/I_Travel_U
The listing 1 (below) provides you with the implementation of the CDS data model for managing flights,
where the database table /dmo/travel serves as the data source for the corresponding CDS view /DMO/
I_Travel_U (note the camel case notation).
This CDS view defines the root entity of the data model and represents the root of the compositional hierarchy
for the travel business object to be created.
From a structural point of view, a business object consists of a tree of nodes that are linked by special
associations known as compositions. To define a composition relationship from the root to a child entity the
keyword COMPOSITION is used. In our example, you specify the /DMO/I_Booking_U as child entity of the
composition _Booking. As a result, the booking node is defined as a direct sub node to the business object’s
root. With cardinality [0 .. *] you express that any number of booking instances can be assigned to each
travel instance.
To be able to access business data from semantically related entities, a set of associations is defined in the
CDS source code. These associations refer to CDS views that are part of our demo application scenario. Some
of these views are used primarily as text views for retrieving text information and as value help provider views
for specific UI fields, see Projecting the Data Model in CDS Projection Views [page 498].
Except for the administrative fields createdby, lastchangedby, and createdat, all fields of the data source
table /dmo/travel have been added to the element list in the CDS view. The database table provides
several administrative fields that are used for administrative data which usually includes the user who
created or last changed an instance and the corresponding timestamps. In this example however, the element
LastChangedAt plays a special part, as it is used for ETag checks to determine whether two representations
of an entity are the same. If the representation of the entity ever changes, a new and different ETag value is
assigned. ETags play a significant part in the lock lifetime when working with business objects.
For all elements, we can provide an alias to provide a readable name for the elements.
The price elements and the element CurrencyCode have a semantic relationship. This relationship is
manifested in the business object view via the @semantics annotations. In a Fiori UI, the amount and the
currency value can then be displayed together.
 Expand the following listing to view the source code.
Listing 1: Source Code of the CDS Root View /DMO/I_Travel_U

Develop PUBLIC 491

@EndUserText.label: 'Travel view - CDS data model'
define root view entity /DMO/I_Travel_U
as select from /dmo/travel as Travel -- the travel table is the data source
for this view
composition [0..*] of /DMO/I_Booking_U as _Booking
association [0..1] to /DMO/I_Agency as _Agency on $projection.AgencyID =
_Agency.AgencyID
association [0..1] to /DMO/I_Customer as _Customer on $projection.CustomerID
= _Customer.CustomerID
$projection.CurrencyCode = _Currency.Currency
association [1..1] to /DMO/I_Travel_Status_VH as _TravelStatus on
$projection.Status = _TravelStatus.TravelStatus
{
key Travel.travel_id as TravelID,
Travel.agency_id as AgencyID,
Travel.customer_id as CustomerID,
Travel.begin_date as BeginDate,
Travel.end_date as EndDate,
Travel.booking_fee as BookingFee,
Travel.total_price as TotalPrice,
Travel.currency_code as CurrencyCode,
Travel.description as Memo,
Travel.status as Status,
Travel.lastchangedat as LastChangedAt,
/* Associations */
_Booking,
_Agency,
_Customer,
_Currency,
_TravelStatus
}

Booking View /DMO/I_Booking_U
Listing 2 (below) provides you with a data model implementation of the booking entity. In the data definition
of the root entity /DMO/I_Travel_U, you specified the booking entity /DMO/I_Booking_U as a child entity.
This composition relationship requires an association to their compositional parent entity for the booking
child entity to be specified in the data model implementation. This relationship is expressed by the keyword
ASSOCIATION TO PARENT. Using this syntax, you define the CDS entity /DMO/I_Booking_U as a direct sub
node in the compositional hierarchy of the travel business object structure.
The SELECT list includes all elements of a booking entity that are relevant for building the BO structure. These
elements are provided with an alias. Like in the Travel CDS view, the semantic relationship between Price
and CurrencyCode is established with the @Semantics annotation.
To be able to access data from other entities, a set of additional associations (_Customer, _Carrier, and
_Connection) is defined in the CDS source code. These views are primarily used as text views for retrieving
text information and as value help provider views for specific booking fields on the UI, Projecting the Data
Model in CDS Projection Views [page 498].

492 PUBLIC Develop
Listing 2: CDS View /DMO/I_Booking_U

@EndUserText.label: 'Booking view'
define view entity /DMO/I_Booking_U
as select from /dmo/booking as Booking
association to parent /DMO/I_Travel_U as _Travel on
$projection.TravelID = _Travel.TravelID
$projection.CustomerID = _Customer.CustomerID
$projection.AirlineID = _Carrier.AirlineID
$projection.AirlineID = _Connection.AirlineID
and
$projection.ConnectionID = _Connection.ConnectionID
{
key Booking.travel_id as TravelID,
key Booking.booking_id as BookingID,
Booking.booking_date as BookingDate,
Booking.customer_id as CustomerID,
Booking.carrier_id as AirlineID,
Booking.connection_id as ConnectionID,
Booking.flight_date as FlightDate,
Booking.flight_price as FlightPrice,
Booking.currency_code as CurrencyCode,
/* Associations */
_Travel,
_Customer,
_Carrier,
_Connection

}
Travel Status View /DMO/I_Travel_Status_VH
Listing 3 (below) provides you with a data definition for handling travel status data. The CDS view /DMO/
I_Travel_Status_VH serves as a value help view providing the possible travel status values.
The database table /dmo/trvl_stat is the data source for the CDS view. The travel status field in table /dmo/
trvl_stat has been added to the element list in the CDS view.
To enable a value selection via a drop-down-menu, the annotation

@ObjectModel.resultSet.sizeCategory: #XS is used.
The associated CDS view /DMO/I_Travel_Status_VH_Text serves as a provider view for localized
texts. Hence, the CDS view /DMO/I_Travel_Status_VH contains an association as well as
the annotation @ObjectModel.text.association: '_Text' pointing to the CDS view /DMO/
I_Travel_Status_VH_Text.
To ensure that only the texts provided by the associated CDS view /DMO/I_Travel_Status_VH_Text are
displayed in the value help, the annotation @UI.textArrangement: #TEXT_ONLY is used.
The annotation @UI.lineItem: [{importance: #HIGH}] ensures that the travel status data are displayed
even when little display space is available.
The @Objectmodel.usageType annotations define the expected performance parameters and contained
data class for the value help view. For more information, refer to ObjectModel Annotations [page 1207].

Develop PUBLIC 493
Listing 3: Travel Status View /DMO/I_Travel_Status_VH
@AbapCatalog.viewEnhancementCategory: [#NONE]

@EndUserText.label: 'Travel Status Value Help'
@Metadata.ignorePropagatedAnnotations: true
@ObjectModel.usageType:{
serviceQuality: #A,
sizeCategory: #S,
dataClass: #MASTER
}
@ObjectModel.resultSet.sizeCategory: #XS
define view entity /DMO/I_Travel_Status_VH
as select from /dmo/trvl_stat
association [0..*] to /DMO/I_Travel_Status_VH_Text as _Text on
$projection.TravelStatus = _Text.TravelStatus
{
@UI.textArrangement: #TEXT_ONLY
@UI.lineItem: [{importance: #HIGH}]
@ObjectModel.text.association: '_Text'
key travel_status as TravelStatus,
_Text
}

Travel Status Text View /DMO/I_Travel_Status_VH_Text
Listing 4 (below) provides you with a data definition for handling travel status text data. This CDS entity
provides the texts for the travel statuses on the list report page and in the value help.
The database table /dmo/trvl_stat_t is the data source for the corresponding CDS view /DMO/
I_Travel_Status_VH_Text. All fields have been added to the element list in the CDS view.
To enable a value selection via a drop-down-menu, the annotation

@ObjectModel.resultSet.sizeCategory: #XS is used.
The annotation @ObjectModel.text.element: ['Text'] establishes the link between the annotated
element and its descriptive element Text. By using the annotation @Semantics.text: true for the element
Text, at runtime, this field is read from the database and filtered by the logon language of the OData consumer
automatically. The annotation @Semantics.language: true specifies the field used for this language filter.
The @Objectmodel.usageType annotations define the expected performance parameters and contained
data class for the value help view. For more information, refer to ObjectModel Annotations [page 1207].
Listing 4: Travel Status Text View /DMO/I_Travel_Status_VH_Text

@EndUserText.label: 'Travel Status Value Help'
serviceQuality: #A,
sizeCategory: #S,

494 PUBLIC Develop
dataClass: #MASTER
}
@ObjectModel.resultSet.sizeCategory: #XS
define view entity /DMO/I_Travel_Status_VH_Text
as select from /dmo/trvl_stat_t
association [1..1] to /DMO/I_Travel_Status_VH as _TravelStatus on
$projection.TravelStatus = _TravelStatus.TravelStatus
{
@ObjectModel.text.element: ['Text']
key travel_status as TravelStatus,
@Semantics.language: true
key language as Language,
text as Text,
_TravelStatus
}

Travel Agency View /DMO/I_Agency
Listing 5 (below) provides you with a data definition for handling travel agency data. The database table /dmo/
agency is the data source for the corresponding CDS view /DMO/I_Agency.
Since the travel agency's data can vary from one country to another, the data model refers to the I_Country
view using the association _Country.
This CDS entity also serves as a text provider view. For this purpose, the annotation @Semantics.text:
true is used to identify the Name element as a text element, which - in this case - points to a textual description
of agency names. In the travel and the booking projection views, the associated text element is added as a field
to the referencing entity. At runtime, this field is read from the database and filtered by the logon language of
the OData consumer automatically.
In addition, the data model enables search capabilities on the Name element: The
annotation @Search.searchable: true marks the CDS view as searchable, whereas
@Search.defaultSearchElement: true specifies that the annotated Name element is to be considered
in a full-text search. For detailed information, see: Enabling Text and Fuzzy Searches in SAP Fiori Apps [page
897]
Listing 5: Agency CDS View /DMO/I_Agency

@EndUserText.label: 'Agency view - CDS data model'
define view entity /DMO/I_Agency
as select from /dmo/agency as Agency -- the agency table serves as the data
source for this view
association [0..1] to I_Country as _Country on $projection.CountryCode =
_Country.Country
{
key Agency.agency_id as AgencyID,
Agency.name as Name,
Agency.street as Street,

Develop PUBLIC 495
Agency.postal_code as PostalCode,
Agency.city as City,
Agency.country_code as CountryCode,
Agency.phone_number as PhoneNumber,
Agency.email_address as EMailAddress,
Agency.web_address as WebAddress,
/* Associations */
_Country
}

Customer View /DMO/I_Customer
Listing 6 (below) is used as a data model implementation for managing passenger data. The database
table /dmo/customer serves as the data source for the corresponding CDS view /DMO/I_Customer.
Except for the administrative fields (createdby, createdat, lastchangedat and lastchangedby), all
fields of the table /dmo/customer have been added to the element list in the CDS view.
Since a passenger’s data can vary from one country to another, the data model refers to the I_Country view
using a corresponding association _Country.
The annotation @Semantics.text: true is added to the LastName element. This element serves as a text
element, which - in this case - points to texts with customer names. This text annotation allows you to use
this customer view as a text provider for the associated elements in the target views /DMO/I_Travel_U
and /DMO/I_Booking_U.
Listing 6: Customer CDS view /DMO/I_Customer

@EndUserText.label: 'Customer view - CDS data model'
define view entity /DMO/I_Customer
as select from /dmo/customer as Customer -- the customer table serves as the
data source
_Country.Country
{
key Customer.customer_id as CustomerID,
Customer.first_name as FirstName,
Customer.last_name as LastName,
Customer.title as Title,
Customer.street as Street,
Customer.postal_code as PostalCode,
Customer.city as City,
Customer.country_code as CountryCode,
Customer.phone_number as PhoneNumber,
Customer.email_address as EMailAddress,
/* Associations */
_Country
}


496 PUBLIC Develop
Flight View /DMO/I_Flight
Listing 7 (below) provides you with a data definition for flights. The data of specific flights is stored in
the database table /dmo/flight, which serves as the data source for the corresponding CDS view /DMO/
I_Flight.
As demonstrated in listing 2 (above), you can implement the value help with additional binding. To define filter
conditions for the value help based on the same value help provider, the flight view /DMO/I_Flight is used to
filter the value help result list for the annotated elements.
Listing 7: CDS View /DMO/I_Flight

@EndUserText.label: 'Flight view'
define view entity /DMO/I_Flight as select from /dmo/flight as Flight
{

key Flight.connection_id as ConnectionID,
Flight.price as Price,
Flight.currency_code as CurrencyCode,
Flight.seats_max as MaximumSeats,
Flight.seats_occupied as OccupiedSeats
}

Flight Connections View /DMO/I_Connection
Listing 8 (below) is used as a data definition for flight connections. The flight connections are stored in the
database table /dmo/connection, which serves as the data source for the corresponding CDS view /DMO/
I_Connection.
Except for the administrative fields, all fields in the table /dmo/connection have been added to the element
list in the CDS view.
Using the annotation @Semantics.quantity.unitOfMeasure, the DistanceUnit element is referenced as

an element containing a unit of measure for the value stored in the element Distance.
Listing 8: CDS View /DMO/I_Connection

@EndUserText.label: 'Connection view'
define view entity /DMO/I_Connection
{

Develop PUBLIC 497
}

Carrier View /DMO/I_Carrier
The following data definition for the carrier CDS entity provides you with IDs and names of airlines that are
stored in the database table /DMO/CARRIER.
This CDS entity mainly serves as a text provider view. It provides text data through text associations as defined
in the travel and the booking views (Listing 1 and Listing 2).
For this purpose, a text annotation is required at element level in order to annotate the text elements from the
view’s element list: In this example, the Name element is identified as the text element.
Listing 9: CDS View /DMO/I_Carrier

@EndUserText.label: 'Carrier view'
define view entity /DMO/I_Carrier as select from /dmo/carrier as Airline
{
}

4.2.3.2.3 Projecting the Data Model in CDS Projection

Views
You use CDS projection views to expose the general data model for a specific business service.
Whereas the general business object defines all available entities and elements, the Business Object Projection
[page 198] defines those entities and elements that are used for a specific service, in our case a service that is
exposed for UI consumption. That means, in the projection layer, we define the data model and its functionality
that is needed for the use case of a UI service of the travel scenario. UI services include:
• value helps
• text elements
• search
• UI layout annotations
These UI enrichments are modeled via CDS annotations in the CDS projection view. It is best practice,
to outsource the annotations related to UI layout in metadata extensions, as these annotations can easily

498 PUBLIC Develop
overload the projection view. A CDS metadata extension is always assigned to a layer such as industry, partner
or customer to easily extend the scope of the metadata extension.
For more information, see Business Object Projection [page 198] and .
Creating CDS Projection Views
For the Travel UI service, create projection views for those CDS entities that are part of the compositional
hierarchy of the business object. These are:
root layer 1st child layer

structure I_TRAVEL_U I_BOOKING_U
projection C_TRAVEL_U C_BOOKING_U
 Note
For more information, see (tool reference).
For information about the syntax in projection views, see Define View Entity as Projection (ABAP Keyword
Documentation).
Data Modeling for the Business Object Projection
The unmanaged scenario provides just one projection use case that reuses all elements that are defined in
the business object views. In the projection layer the data model is enriched with UI functionality that is
implemented via CDS annotations or keywords in the projection view and manifested in the service metadata.
Root Projection View /DMO/C_Travel_U
The following codeblock provides you with the implementation of the CDS view projection, where the CDS
view /DMO/I_Travel_U serves as the projection source for the corresponding CDS projection view /DMO/
C_Travel_U. It projects every element from the underlying view.
The Travel projection view also exposes all associations that are defined in the underlying travel view /DMO/
I_Travel_U. However, the composition to the child /DMO/I_Booking_U must be redirected to the newly
created projection counterpart. The syntax for defining redirected compositions is described in CDS Projection
View [page 201].

Develop PUBLIC 499
To define a relationship between the elements AgencyID, CustomerID, Status and their corresponding
texts or descriptions, the text elements must be denormalized in the CDS projection view. Therefore
the elements of the associated text provider views (_Agency.Name, _Customer.LastName and
_TravelStatus._Text.Text) are included in the select list of the projection view. Their corresponding ID
elements are annotated with @ObjectModel.text.element. At runtime, the referenced element is read from
the database and filtered by the logon language of the OData consumer automatically. For detailed information,
see: Working with Text Elements [page 891]
Value helps are defined in the source code of the CDS projection view /DMO/C_Travel_U by
adding the annotation @Consumption.valueHelpDefinition to the elements AgencyID, CustomerID,
CurrencyCode and Status. The value help annotation allows you to reference the value help provider view
without implementing an association. You simply assign a CDS entity as the value help provider and specify
an element for the mapping in the annotation. All fields of the value help provider are displayed on the UI.
When the end user chooses one of the entries of the value help provider, the value of the referenced element
is transferred to the corresponding input field on the UI. For detailed information, see: Simple Value Help [page
778]
 Note
For the default implementation of value help, note that you can reuse any CDS entity that contains the
required values of the element that corresponds to the input field on the UI. You do not need to explicitly
define a CDS entity as the value help provider
In the projection view, you model the ability to search for specific values in the view. The entity annotation
@Search.searchable is used in the travel projection to enable the general HANA search. This annotation
also triggers the search bar in the Fiori elements UI. By using this annotation, you have to define elements
that are primarily used as the search target for a free text search. These elements are annotated with
@Search.defaultSearchElement. In addition, you can define a fuzziness threshold that defines the how
exact the search values must be to be able to find element values. For more information on search, see
The listing below does not include annotations that define the UI layout. They are outsourced to metadata
extensions, see Adding UI Metadata to the Data Model [page 503].
 Expand the following code sample to view the source code of CDS Root Projection View /DMO/C_Travel_U.
 Sample Code
@EndUserText.label: 'Travel Projection View'

@Metadata.allowExtensions: true
define root view entity /DMO/C_Travel_U
as projection on /DMO/I_Travel_U
{ ///DMO/I_Travel_U
key TravelID,
@Consumption.valueHelpDefinition: [{ entity: { name: '/DMO/I_Agency',
AgencyID,
I_Customer',
element:
'CustomerID' } }]

500 PUBLIC Develop
CustomerID,
BeginDate,
EndDate,
BookingFee,
TotalPrice,
@Consumption.valueHelpDefinition: [{entity: { name: 'I_Currency',
element: 'Currency' } }]
CurrencyCode,
Memo,
I_Travel_Status_VH', element: 'TravelStatus' }}]
@ObjectModel.text.element: ['StatusText']
Status,
_TravelStatus._Text.Text as StatusText : localized,

LastChangedAt,
/* Associations */
///DMO/I_Travel_U
_Booking : redirected to composition child /DMO/C_Booking_U,
_Agency,
_Currency,
_Customer,
_TravelStatus
}

Child Projection View /DMO/C_Booking_U
The following codeblock provides you with the implementation of the CDS view projection, where the CDS
view /DMO/I_Booking_U serves as the projection source for the corresponding CDS projection view /DMO/
C_Booking_U. It projects every element from the underlying view.
The Booking projection view also exposes all associations that are defined in the underlying booking
view /DMO/I_Travel_U. However, the composition to the parent /DMO/I_Travel_U must be redirected to
the newly created projection counterparts. The syntax for defining redirected compositions is described in CDS
Projection View [page 201].
To access the corresponding texts or descriptions, the relationship between the elements AirlineID
and ConnectionID and the text elements in the associated text provider views /DMO/I_Carrier
and /DMO/I_Connection are used in this example. Their corresponding ID elements are annotated with
@ObjectModel.text.element. At runtime, the referenced element is read from the database and filtered
by the logon language of the OData consumer automatically. For detailed information, see: Working with Text
Elements [page 891]
Value helps are defined in the source code of the booking entity /DMO/C_Booking_U by adding the annotation
@Consumption.valueHelpDefinition to the relevant elements. You simply assign a CDS entity as the
value help provider to the elements CustomerID, AirlineID, and CurrencyCode, and specify an element for
the mapping in the annotation. This simple value help approach is convenient if you only want to display values
from the value help provider view for an input field. In this case, the annotation defines the binding to the value
help providing entity. You only have to specify the entity name and the element providing the possible values for
the annotated element. For detailed information, see: Simple Value Help [page 778]

Develop PUBLIC 501
Listing 2 also demonstrates how you can implement the value help with additional binding, which defines
a filter condition. Different filter conditions for the value help on the same value help provider entity /DMO/
I_Flight are defined for filtering the value help result list for the elements ConnectionID and FlightDate.
For detailed information, see: Value Help with Additional Binding [page 783]
The elements in the booking projection view are also searchable in a UI service. The annotations related to
search are therefore also maintained in the booking view on entity level and on certain elements to mark them
as primary search element. For more information on search, see Enabling Text and Fuzzy Searches in SAP Fiori
Apps [page 897].
The listing below does not include annotations that define the UI layout. They are outsourced to metadata
extensions, see Adding UI Metadata to the Data Model [page 503].
 Expand the following code sample to view the source code of CDS Root Projection View /DMO/C_Travel_U.
 Sample Code
@EndUserText.label: 'Booking Projection View'

define view entity /DMO/C_Booking_U
as projection on /DMO/I_Booking_U
{ ///DMO/I_Booking_U
key TravelID,
key BookingID,
BookingDate,
@Consumption.valueHelpDefinition: [ { entity: { name: '/DMO/
I_Customer',
element:
'CustomerID' } } ]
CustomerID,
I_Carrier',
element:
'AirlineID' } } ]
@ObjectModel.text.element: ['AirlineName']
AirlineID,
_Carrier.Name as AirlineName,
I_Flight',
element:
'ConnectionID' },
additionalBinding:
[ { localElement: 'FlightDate', element: 'FlightDate' },
{ localElement: 'AirlineID', element: 'AirlineID' },

ConnectionID,

I_Flight',
element: 'FlightDate' },
additionalBinding:
[ { localElement: 'ConnectionID', element: 'ConnectionID' },

502 PUBLIC Develop
{ localElement: 'AirlineID', element: 'AirlineID' },

FlightDate,
FlightPrice,
@Consumption.valueHelpDefinition: [ {entity: { name: 'I_Currency',

element: 'Currency' } } ]
CurrencyCode,
/* Associations */
///DMO/I_Booking_U
_Travel: redirected to parent /DMO/C_Travel_U,
_BookSupplement: redirected to composition child /DMO/
C_BookingSupplement_U,
_Carrier,
_Connection,
_Customer
}

The other CDS views that are relevant for text provisioning and value helps to complete the data model
structure do not have to be projected as they are not part of the business object.
Related Information
Business Object Projection [page 198]
4.2.3.2.3.1 Adding UI Metadata to the Data Model
Use @UI annotations to define the layout of the Fiori UI.
To enable the business service to be consumable by any UI client, UI relevant metadata are added to the
backend service. These metadata are maintained with @UI annotations that are either added to the whole
entity or, if it relates to a specific UI element, to the corresponding CDS element. Since these annotations can
become excessive, it is recommended to maintain the UI annotations in metadata extensions.
Metadata extensions are used to define CDS annotations for a CDS view outside of the corresponding
data definition. The use of metadata extensions allows the separation of concerns by separating the data
model from domain-specific semantics, such as UI-related information for UI consumption. A CDS metadata
extension is always assigned to a specific layer such as core, industry, partner or customer. These industries
can extend the metadata for the data model.
Creating Metadata Extension for the Projection Views
For the Travel UI service, create metadata extensions for the CDS projection views that are part of the
compositional hierarchy of the business object. These are:

Develop PUBLIC 503
root layer 1st child layer

structure I_TRAVEL_U I_BOOKING_U
projection C_TRAVEL_U C_BOOKING_U
Metadata exten- /DMO/ /DMO/
sion for UI annota- C_TRAVEL_U C_BOOKING_U
tions
 Note
The names of metadata extensions are the same as their related CDS entities, according to the naming
conventions for metadata extensions: Naming Conventions for Development Objects [page 306].
To create a metadata extension object, open the context menu in the project explorer of the related CDS entity
and choose New Metadata Extension. Follow the steps in the wizard to get a metadata extension template that
annotates the related projection view.
Syntax:
@Metadata.layer: layer

annotate view CDSProjectionView
with
{
element_name;

}
Define a metadata layer for your metadata extension and insert the elements that you want to annotate. The
layering of metadata extension allows a stacking for each development layer, beginning with #CORE. Each layer
can then add its own layer specific metadata to the service.
To enable the usage of metadata extensions for the projection views, add the annotation
@Metadata.allowExtensions:true on entity level in your projection view. For more information, see .
Annotating CDS Elements in Metadata Extensions
Any CDS element that you want to annotate in metadata extensions must be inserted in the element list.
Metadata Extension for CDS Projection View /DMO/C_Travel_U
The listing below (listing 1) provides you with the implementation of the metadata extension /DMO/
C_Travel_U for the projection view with the same name. It annotates the projection view itself and its
elements.
To specify the header texts for Fiori UIs, the annotation @UI.headerInfo is used at entity level. It specifies the
list title as well as the title for the object page. The main building blocks of the UI are specified as UI facets. The

504 PUBLIC Develop
annotation @UI.facet also enables the navigation to the child entity, which is represented as list in the page
body of the object page.
The annotations on element level are used to define the position of the element in the list report and on the
object page. In addition, they specify the importance of the element for the list report. If elements are marked
with low importance, they are not shown on a device with a narrow screen. The selection fields are also defined
on the elements that require a filter bar in the UI.
For actions, you can define an action button on the Fiori Elements UI. This scenario contains the action to set
the travel status to booked. To expose the action on the list report page, the information for the action button is
added to the @UI.lineItem annotation on an element.
Syntax to expose an action button on the UI:
@UI: { lineItem: { type: #FOR_ACTION, dataAction: 'action_name', label:

'Button Label' } ] }

element;
Listing 1: Source Code of the Metadata Extension /DMO/C_Travel_U
@Metadata.layer: #CORE

@UI: { headerInfo: { typeName: 'Travel',
typeNamePlural: 'Travels',
value: 'TravelID' } } }
annotate view /DMO/C_Travel_U with
{
purpose: #STANDARD,
label: 'Travel',
position: 10 },
{ id: 'Booking',
purpose: #STANDARD,
label: 'Booking',
position: 20,
@UI: { lineItem: [ { position: 10,
importance: #HIGH } ],
TravelID;
AgencyID;
CustomerID;
importance: #MEDIUM } ],
BeginDate;
EndDate;
@UI: { identification: [ { position: 42 } ] }

Develop PUBLIC 505
BookingFee;
TotalPrice;
@UI: { identification:[ { position: 45,
label: 'Comment' } ] }
Memo;
importance: #HIGH },
{ type: #FOR_ACTION,
dataAction: 'set_status_booked',
label: 'Set to Booked' } ],
identification: [ { position: 46, label: 'Travel Status' } ],
Status;
@UI.hidden: true
StatusText;

}
Metadata Extension for CDS Projection View /DMO/C_Booking_U
The listing below (listing 2) provides you with the implementation of the metadata extension /DMO/
C_Booking_U for the projection view with the same name. It annotates the projection view itself and its
elements.
To specify the header texts for Fiori UIs, the annotation @UI.headerInfo is used at entity level. It specifies the
list title as well as the title for the object page. The main building blocks of the UI are specified as UI facets.
The annotations on element level are used to define the position of the element in the list report and on the
object page. In addition, they specify the importance of the element for the list report. The selection fields are
also defined on the elements that require a filter bar in the UI.
Listing 2: Source Code of the Metadata Extension /DMO/C_Booking_U

@UI: {
value: 'BookingID' } } }
annotate view /DMO/C_Booking_U with
{
purpose: #STANDARD,
label: 'Booking',
position: 10 } ]
BookingID;
BookingDate;

506 PUBLIC Develop
CustomerID;
AirlineID;
ConnectionID;
FlightDate;
FlightPrice;

}
4.2.3.3 Defining and Implementing Behavior of the

Business Object
Behavior of a Business Object
To specify the business object's behavior, the behavior definition as the corresponding development object
is used. A business object behavior definition (behavior definition for short) is an ABAP Repository object
that describes the behavior of a business object in the context of the ABAP RESTful application programming
model. A behavior definition is defined using the Behavior Definition Language (BDL).
A behavior definition always refers to a CDS data model. As shown in the figure below, a behavior definition
relies directly on the CDS root entity. One behavior definition refers exactly to one root entity and one CDS root
entity has at most one behavior definition (a 0..1 cardinality), which also handles all included child entities that
are included in the composition tree. The implementation of a behavior definition can be done in a single ABAP
class (behavior pool) or can be split between an arbitrary set of ABAP classes (behavior pools). The application
developer can assign any number of behavior pools to a behavior definition (1..N cardinality).

Develop PUBLIC 507
Relationship Between the CDS Entities and the Business Object Behavior
Overview of Steps
1. Create the Behavior Definition Object

2. Model the Behavior for Managing Travels
3. Create the Behavior Pool
4. Implement the Transactional Behavior of the Travel Business Object
Related Information

Business Service [page 196]

508 PUBLIC Develop
4.2.3.3.1 Adding Behavior to the Business Object
Creating a Behavior Definition /DMO/I_TRAVEL_U
Create the behavior definition by using the creation wizard in ADT. When using the context menu on the
root view entity (/DMO/I_Travel_M), you can directly create a new behavior definition for the complete BO
hierarchy. In the wizard, choose the implementation type Unmanaged. For a detailed description, see .
 Remember
By creating a behavior definition, the referenced root entity and its compositions (child entities) gain a
transactional character. The behavior definition is hence the implementation of the BO concept within the
context of the current programming model. All supported transactional operations of a concrete business
object must be specified in the same behavior definition.
Defining the Transactional Behavior of the TRAVEL Business Object
It consists of a header information and two definitions for entity behavior: one for the root entity and one
for the child entity – corresponding to the composition tree of the business object. Note that for each entity
of the composition tree, the transactional behavior can be defined in the behavior definition at most once.
All supported transactional operations of a concrete business object’s node must be specified in the same
behavior definition (that is introduced by the keyword DEFINE BEHAVIOR FOR ... ).
For a detailed syntax description of a behavior definition header, see CDS BDL - CDS behavior definition header
For a detailed syntax description of an entity behavior definition, see CDS BDL - entity behavior definition
As expected, the header specifies the unmanaged implementation type of our business object’s contract
provider since we're going to integrate the legacy business logic in the new app. For this implementation type,
you as application developer must implement the essential components of the business object’s itself. In this
case, you must specify all required operations (create, update, delete, or any application-specific actions)
in the corresponding behavior definition and implement them manually in ABAP.
Our TRAVEL business object refers to the underlying CDS data model, which is represented by root
entity /DMO/I_Travel_U. Behavior for the root entity can only be implemented in the specified behavior
pool /DMO/BP_TRAVEL_U.
Static field control is defined in the behavior definition. In our scenario, the value for the key field TravelID is
drawn by the function module for creating travel instances. Thus, the field must not be editable by the end user
on the UI. Likewise, the field TotalPrice is set to read only. The total price isn'tcalculated by the price of the
associated bookings and the booking fee in the function module. In this scenario, the total price is editable by
the end user.

Develop PUBLIC 509
Mandatory fields are AgencyID, CustomerID, BeginDate and EndDate. These fields contain mandatory
information for a travel instance. For more information about field control, see Instance Feature Control [page
129].
The transactional handling of the business object's root node is determined by the standard operations
create, update, and delete, and an instance-related action set_status_booked. Using this action, the
end user is able to set the status of selected travel instances to booked. The action in our example affects the
output instances with the same entity type and one input instance is related to exactly one output instance.
Therefore, the output parameter is defined with the predefined type $self and the cardinality [1]. The
fact that in our scenario new instances of the booking sub node can only be created for a specific travel
instance is considered by the addition of the _Booking association. The keyword {create;} declares that
this association is create-enabled what exactly means that instances of the associated bookings can be
created by a travel instance.
Dynamic operation control is defined for the create by association operation. That means, new bookings can
only be created if the corresponding travel instance isn't set to booked or canceled. For more information about
field control, see Feature Control [page 128].
The names of the database table fields and the names of the CDS data model names differ. That is why, we
specify the mapping contract for every field in the CDS data model. To map the control structure accordingly,
the control structure /dmo/s_booking_intx is defined for the database table. For more information, see
Using Type and Control Mapping [page 861].
The etag master field ensures transactional access to data by multiple users while avoiding inconsistencies
and unintentional changes of already modified data. Each MODIFY is logged with the etag field (in this case a
timestamp) to ensure data consistency. For more information, see Optimistic Concurrency Control [page 33].
The lock master prevents parallel modification to data on the database by more than one user and ensures
data consistency. For more information, see Pessimistic Concurrency Control (Locking) [page 38].
The authorization master defines how and when a RAP BO can be accessed. With the addition ,global
the authorization is checked before any request is executed. For more information, see Authorization Control
[page 80].
late numbering defines that the primary ID value is only assigned just before the instance is saved on the
database. For late numbering, the method ADJUST NUMBERS must be implemented. For more information, see
Unmanaged Internal Late Numbering [page 29].
The sub node of TRAVEL business object refers to the corresponding data model for bookings that is
represented by the child entity for /DMO/I_Booking_U. Behavior for the child entity can only be implemented
in the specified behavior pool /DMO/BP_BOOKING_U. The transactional handling of the booking sub node
of TRAVEL business object is determined by the standard operations update and delete. The creation of
booking instances is handled by the create by association, that means bookings can only be created as a
subnode of its travel parent.
 Expand the following code sample to view the source code of behavior definition /DMO/I_Travel_U.
 Sample Code

unmanaged implementation in class /DMO/BP_TRAVEL_U unique;
strict;
// behavior defintion for the TRAVEL root entity
define behavior for /DMO/I_Travel_U alias Travel
implementation in class /DMO/BP_TRAVEL_U unique
etag master LastChangedAt

510 PUBLIC Develop
lock master
authorization master ( global )
late numbering
{
field ( readonly ) TravelID;
create;
update;
delete;
action ( features : instance ) set_status_booked result [1] $self;
association _Booking { create (features: instance); }
mapping for /dmo/travel control /dmo/s_travel_intx
{
AgencyID = agency_id;
BeginDate = begin_date;
BookingFee = booking_fee;
CurrencyCode = currency_code;
CustomerID = customer_id;
EndDate = end_date;
LastChangedAt = lastchangedat;
Memo = description;
Status = status;
TotalPrice = total_price;
TravelID = travel_id;
}
}
// behavior definition for the BOOKING child entity
define behavior for /DMO/I_Booking_U alias Booking
implementation in class /DMO/BP_BOOKING_U unique
etag dependent by _Travel
late numbering
{
field ( readonly ) TravelID, BookingID;
field ( mandatory ) BookingDate, CustomerID, AirlineID, ConnectionID,
FlightDate;
update;
delete;
association _Travel;
mapping for /dmo/booking control /dmo/s_booking_intx
{
AirlineID = carrier_id;
BookingDate = booking_date;
BookingID = booking_id;
ConnectionID = connection_id;
FlightDate = flight_date;
FlightPrice = flight_price;
}
}

Related Information

Develop PUBLIC 511
4.2.3.3.2 Implementing the Behavior of the Business
Object
Behavior Pool
The transactional behavior of a business object in the context of the current programming model is
implemented in one or more global ABAP classes. These special classes are dedicated only to implementing
the business object’s behavior and are called behavior pools. You can assign any number of behavior pools
to a behavior definition (a 1: n relationship). Within a single global class, you can define multiple local classes
that handle the business object’s behavior. The global class is just a container and is basically empty while the
actual behavior logic is implemented in local classes.
Behavior Pools of the Travel Business Object
For details about the syntax for defining a behavior pool, see CLASS, FOR BEHAVIOR OF (ABAP- Keyword
Documentation)

512 PUBLIC Develop
Effect
The above syntax defines a special ABAP class (a behavior pool) for the behavior specified in the behavior
definition MyRootBehavior (which in turn has the same name as the CDS root entity). This special property
and relationship are persisted and transported using a corresponding system table. This specific information is
assigned to the properties of the behavior pool and can no longer be changed. The behavior pool is dependent
on the behavior definition, meaning the changes to the behavior definition cause it to be regenerated.
This global class is defined as abstract and final, which means there is no reason to instantiate or inherit this
global behavior pool. In addition, such a ban prevents possible misuse.
A behavior pool can have static methods, namely CLASS-DATA, CONSTANTS, and TYPES. The application may
place common or even public aspects of its implementation in these methods.
Distributing Behavior Pool Implementation
You can assign any number of behavior pools to a behavior definition (1: n relationship). This allows the
application developers to distribute their implementations between multiple units, for example one global class
(behavior pool) for each business object’s node, and one or more separate auxiliary classes for implementing
helper methods. The figure below illustrates this distribution pattern for our sample application.
 Note
Best Practices: Splitting the implementation into different global classes allows developers to work in
parallel (distributed work mode). If operations on each node have to be forwarded to different APIs
(function module calls), then we recommend using a separate global class (behavior pool) for each node of
the business object’s compositional tree.

Develop PUBLIC 513
Splitting the implementation into different behavior pools
Related Information
Business Object Provider API [page 137]

Handler Classes [page 139]
Saver Classes [page 149]
Naming Conventions for Development Objects [page 306]
4.2.3.3.2.1 Creating the Behavior Pool for the Root Entity
In this step, you create a behavior pool that is the implementation artifact of the corresponding behavior
definition that you created earlier.
In doing so, we apply the contribution pattern and split the behavior implementation into two different behavior
pools, one for the travel root entity and the other for the booking child entity. In addition, we create a separate
auxiliary class for implementing helper methods (such as for mapping and message handling) that can be
reused in both behavior implementation classes.
 Note
Best Practices for Modularization and Performance:

514 PUBLIC Develop
The granularity of the existing application code influences the granularity of handler implementation. If the
existing legacy application logic has different APIs (function modules) for create, update, delete, and other
transactional operations, then we recommend spreading the operations across different handler classes.
If, for example, the called API only implements one operation for CREATE and another API implements one
for UPDATE, it is advisable to implement each operation in a different local handler class.
If, on the other hand, the called API of your application code is able to process multiple changes in
one call, the handler should reflect this to achieve the best performance. In such a case, we combine all
operations supported by this API in one common handler class.
Otherwise the application code is called multiple times with different input, which can result in bad
performance.
If the application code supports a deep create (for example creation for root and child entity in one step),
then this should be reflected in the design of handler classes to achieve best performance.
 Remember
Beyond the performance aspects, it is beneficial to implement operations in different FOR MODIFY
methods, since the orchestration is then passed to the BO runtime and the code of the behavior
implementation is more readable.
 Note
Convention: The saver class that implements the save sequence for data persistence is either a separate
global class or a part of the root implementation (behavior pool for the root entity).
Procedure 1: Create a Behavior Pool /DMO/BP_TRAVEL_U
To launch the wizard tool for creating a behavior implementation, do the following:
implementation in class /dmo/bp_travel_u unique

2. The behavior definition offers a quick fix to create a behavior pool corresponding to the behavior described
in the behavior definition. Follow the quick fix to start the wizard for creating an ABAP class.

Develop PUBLIC 515
Creating a Behavior Pool – Wizard
Results: Global Behavior Pool

The generated class pool (in our case Procedure 2: Define a Skeleton of Local Classes Corresponding to the
Behavior Model /DMO/BP_TRAVEL_U) provides you with an extension FOR BEHAVIOR OF.

516 PUBLIC Develop
New Global Behavior Pool
The real substance of a behavior pool is located in Local Types. Here you can define two types of special
local classes, namely handler classes for the operations within the Procedure 2: Define a Skeleton of Local
Classes Corresponding to the Behaviorinteraction phase and saver classes for the operations within the
save sequence. These classes can be instantiated or invoked only by the ABAP runtime environment (virtual
machine).
 Note
All local class source code within a single global class is stored within a single include, the CCIMP include.
Based on the declarations in the behavior definition /DMO/I_TRAVEL_U, the behavior implementation offers a
skeleton of the local classes for the root entity:
Listing: Template for local classes of /DMO/BP_TRAVEL_U

**********************************************************************
*
* Handler class for managing travels
*
**********************************************************************
PRIVATE SECTION.
METHODS get_instance_features FOR INSTANCE FEATURES
METHODS get_global_authorizations FOR GLOBAL AUTHORIZATION
IMPORTING REQUEST requested_authorizations FOR travel RESULT result.
METHODS create FOR MODIFY

Develop PUBLIC 517
IMPORTING entities FOR CREATE travel.
METHODS update FOR MODIFY
IMPORTING entities FOR UPDATE travel.
METHODS delete FOR MODIFY
IMPORTING keys FOR DELETE travel.
METHODS read FOR READ
IMPORTING keys FOR READ travel RESULT result.
METHODS lock FOR LOCK
IMPORTING keys FOR LOCK travel.
METHODS rba_Booking FOR READ
IMPORTING keys_rba FOR READ travel\_Booking FULL result_requested RESULT
result LINK association_links.
METHODS cba_Booking FOR MODIFY
IMPORTING entities_cba FOR CREATE travel\_Booking.
METHODS set_status_booked FOR MODIFY
IMPORTING keys FOR ACTION travel~set_status_booked RESULT result.
METHODS map_messages
IMPORTING
cid TYPE string OPTIONAL
travel_id TYPE /dmo/travel_id OPTIONAL
messages TYPE /dmo/t_message
EXPORTING
failed_added TYPE abap_bool
CHANGING
failed TYPE tt_travel_failed
reported TYPE tt_travel_reported.
METHODS map_messages_assoc_to_booking
IMPORTING
cid TYPE string
is_dependend TYPE abap_bool DEFAULT abap_false
EXPORTING
CHANGING
failed TYPE tt_booking_failed
reported TYPE tt_booking_reported.
ENDCLASS.
METHOD get_instance_features.
ENDMETHOD.
METHOD get_global_authorizations.
ENDMETHOD.
METHOD create.
ENDMETHOD.
METHOD update.
ENDMETHOD.
METHOD delete.
ENDMETHOD.
METHOD read.
ENDMETHOD.
METHOD lock.
ENDMETHOD.
METHOD rba_Booking.
ENDMETHOD.
METHOD cba_Booking.
ENDMETHOD.
METHOD set_status_booked.
ENDMETHOD.
METHOD map_messages.
ENDMETHOD.
METHOD map_messages_assoc_to_booking
.
ENDMETHOD.
ENDCLASS.
**********************************************************************
*
* Saver class implements the save sequence for data persistence
*

518 PUBLIC Develop
**********************************************************************
CLASS lsc_saver DEFINITION INHERITING FROM cl_abap_behavior_saver.
PROTECTED SECTION.
METHODS cleanup REDEFINITION.
ENDCLASS.
CLASS lsc_saver IMPLEMENTATION.
METHOD finalize REDEFINITION.
ENDMETHOD.
METHOD check_before_save REDEFINITION.
ENDMETHOD.
METHOD adjust_numbers REDEFINITION.
ENDMETHOD.
METHOD save REDEFINITION.
ENDMETHOD.
METHOD cleanup REDEFINITION.
ENDMETHOD.
METHOD cleanup_finalize REDEFINITION.
ENDMETHOD.
ENDCLASS.

Procedure 3: Create an Auxiliary Class /DMO/CL_TRAVEL_AUXILIARY
Message handling can be reused by different behavior pools and is therefore outsourced in a separate helper
class.
1. In your ABAP project (or ABAP Cloud Project), select the select the Source Code Library Classes
node of the relevant package.
2. To launch the creation wizard, open the context menu and choose New ABAP Class.

Develop PUBLIC 519
Creating ABAP Class – Wizard
4.2.3.3.2.2 Implementing the Interaction Phase and the Save

Sequence
The business object runtime has two parts: The first part is the interaction phase where a consumer calls
business object operations to change data and read instances with or without the transactional changes.
The business object keeps the changes in its internal transactional buffer, which represents the state. This
transactional buffer is always required for a business object, regardless of how it is implemented. After all
changes are performed, the data should be persisted. This is implemented within the save sequence.
Further information: (Reference) [page 137]

520 PUBLIC Develop
The Interaction Phase and the Save Sequence
Implementation Steps
1. Implementing the CREATE Operation for Travel Instances [page 522]

2. Implementing the UPDATE Operation for Travel Data [page 527]
3. Implementing the READ Operation for Travel Data [page 531]
4. Implementing the DELETE Operation for Travel Instances [page 533]
5. Implementing the CREATE Operation for Associated Bookings [page 535]
6. Implementing the READ Operation for Associated Bookings [page 541]
7. Implementing the SET_STATUS_BOOKED Action [page 547]
8. Instance Feature Control [page 129]
9. Implementing the UPDATE, DELETE, and READ Operations for Booking Instances [page 553]
Related Information


Develop PUBLIC 521
4.2.3.3.2.2.1 Implementing the CREATE Operation for Travel
Instances
In this topic, you will be guided through all implementation steps required for creation of new travel instances.
We will motivate the steps for the implementation, starting from the UI.
Preview
If you run the UI service based on SAP Fiori Elements Fiori Launchpad, the resulting UI provides you with a list of
existing travel items, including all fields exposed for UI consumption.
To create a travel item, the end user must click the Create button and fill all required fields in the related object
page to specify the required information for a new travel instance.
Object Page for Editing Individual Values
As soon as the user clicks the Save button on the object page, the data is persisted in the corresponding
database table and a travel instance with a new travel ID is created.
Saved Data Displayed on Fiori UI

522 PUBLIC Develop
Defining the Handler Class for Creation of Travel Instances

Corresponding to the template [page 517] for the root node behavior implementation, a local handler class
lhc_travel is defined to implement each changing operation in one individual FOR MODIFY method. In this
case, the create FOR MODIFY method should only be used to implement the create operation for root
instances. Therefore, the signature of this method includes only one import parameter it_travel_create
for referring to the travel (root) instances to be created. To identify the root entity, the alias travel is used -
according to the alias that is specified in the behavior definition. Note that import parameter entities does
not have fixed data type at the design time. At runtime, the data type is assigned by the compiler with the types
derived from behavior definition.
 Note
The local handler class lhc_travel inherits from class cl_abap_behavior_handler and is
automatically instantiated by the framework.
Further information: <method> FOR MODIFY [page 140]
Implementing the <method> FOR MODIFY for Creation of New Travel Instances
As given in the listing below, the basic structure of the <method> FOR MODIFY implementation includes:
• A loop on all new travel instances to be created for the root node.
• Mapping the CDS view field names to the database table fields names by using the operator MAPPING
FROM ENTITY USING CONTROL. This operator maps only the fields that are flagged in the control
structure of the importing parameter.
• Call of the business logic function module /DMO/FLIGHT_TRAVEL_CREATE for creation of new travel
instances.
• Call of ADJUST_NUMBERS to assign the TRAVEL_ID and BOOKING_ID
• Message handling for processing messages in case of failure. See Message Handling [page 524].
Each create action call can produce failed keys (<travel_create>-%cid) and messages (messages). Any
failed keys are stored in the table FAILED [page 152] whereas the REPORTED [page 153] table includes all
messages. For more information about FAILED and REPORTED, seeABAP EML -Response Parameters (ABAP-
Keyword Documentation). In some use cases, a consumer works with data that is not yet persisted and might
not have a primary key yet. The primary key can be created in the <method> FOR MODIFY call or later in
the save sequence (late numbering).In the late numbering use case that is used in this scenario , a temporary
primary key, the content ID (%CID and %PID) for an instance, is used for processing as long as no primary key
was created by the RAP BO runtime. The content ID is consequently also used then as a foreign key.
In case of success (messages IS INITIAL) , the two values with the content ID %CID and the new key
travelid assigned in the ADJUST NUMBERS method are written into the mapped-travel table.
Creating travel instances

METHOD create.
DATA: messages TYPE /dmo/t_message,
travel_in TYPE /dmo/travel,

Develop PUBLIC 523
travel_out TYPE /dmo/travel.
LOOP AT entities ASSIGNING FIELD-SYMBOL(<travel_create>).
travel_in = CORRESPONDING #( <travel_create> MAPPING FROM ENTITY USING
CONTROL ).
CALL FUNCTION '/DMO/FLIGHT_TRAVEL_CREATE'
EXPORTING
iv_numbering_mode = /dmo/if_flight_legacy=>numbering_mode-late
IMPORTING
es_travel = travel_out
et_messages = messages.
map_messages(
EXPORTING
cid = <travel_create>-%cid
messages = messages
IMPORTING
failed_added = DATA(failed_added)
CHANGING
failed = failed-travel
reported = reported-travel
).
IF failed_added = abap_false.
INSERT VALUE #(
%cid = <travel_create>-%cid
travelid = travel_out-travel_id )
INTO TABLE mapped-travel.
ENDIF.
ENDLOOP.
ENDMETHOD.
...
ENDCLASS.

Message Handling
Declaration of the method get_cause_from _message at the beginning of the helper

class /dmo/cl_travel_auxiliary

CLASS /dmo/cl_travel_auxiliary DEFINITION
INHERITING FROM cl_abap_behv
PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
CLASS-METHODS get_cause_from_message
IMPORTING
msgid TYPE symsgid
msgno TYPE symsgno
RETURNING
VALUE(fail_cause) TYPE if_abap_behv=>t_fail_cause.
ENDCLASS.
CLASS /dmo/cl_travel_auxiliary IMPLEMENTATION.
METHOD get_cause_from_message.
fail_cause = if_abap_behv=>cause-unspecific.
IF msgid = '/DMO/CM_FLIGHT_LEGAC'.
CASE msgno.
WHEN '009' "Travel Key initial
OR '016' "Travel does not exist
OR '017' "Booking does not exist
OR '021'. "BookingSupplement does not exist
IF is_dependend = abap_true.
fail_cause = if_abap_behv=>cause-unspecific.
ELSE.
fail_cause = if_abap_behv=>cause-not_found.

524 PUBLIC Develop
ENDIF.
WHEN '032'. "Travel is locked by
fail_cause = if_abap_behv=>cause-locked.
WHEN '046'. "You are not authorized
fail_cause = if_abap_behv=>cause-unauthorized.
ENDCASE.
ENDIF.
ENDMETHOD.
ENDCLASS.

Performing a Final Commit and Releasing Caches
Performing a Final Commit and Releasing Caches
ADJUST NUMBERS
When the ADJUST_NUMBERS method is called during the save after the point-of-no-return, the function
module /DMO/FLIGHT_TRAVEL_ADJ_NUMBERS is executed and key values are generated. Then the preliminary
key values are mapped from %tmp to the final key values. In this use case, inplace numbering is used,
meaning that the temporary key values are assigned to %key during the RAP interaction phase. For more
information %tmp, see ABAP EML -%tmp (ABAP- Keyword Documentation). For more information about
ADJUST_NUMBERS, see ADJUST_NUMBERS [page 230].

...
DATA: travel_mapping TYPE /dmo/if_flight_legacy=>tt_ln_travel_mapping,
booking_mapping TYPE /dmo/if_flight_legacy=>tt_ln_booking_mapping,
bookingsuppl_mapping TYPE /dmo/
if_flight_legacy=>tt_ln_bookingsuppl_mapping.
CALL FUNCTION '/DMO/FLIGHT_TRAVEL_ADJ_NUMBERS'
IMPORTING
et_travel_mapping = travel_mapping
et_booking_mapping = booking_mapping
et_bookingsuppl_mapping = bookingsuppl_mapping.
mapped-travel = VALUE #( FOR travel IN travel_mapping
( %tmp = VALUE #( TravelID = travel-preliminary-travel_id )
TravelID = travel-final-travel_id ) ).
mapped-booking = VALUE #( FOR booking IN booking_mapping
( %tmp = VALUE #( TravelID = booking-preliminary-travel_id
BookingID = booking-preliminary-booking_id )
TravelID = booking-final-travel_id
BookingID = booking-final-booking_id ) ).
mapped-bookingsupplement = VALUE #( FOR bookingsuppl IN bookingsuppl_mapping
( %tmp = VALUE #( TravelID = bookingsuppl-preliminary-
travel_id
BookingID = bookingsuppl-preliminary-
booking_id
BookingSupplementID = bookingsuppl-preliminary-
booking_supplement_id )
TravelID = bookingsuppl-final-travel_id
BookingID = bookingsuppl-final-booking_id

Develop PUBLIC 525
BookingSupplementID = bookingsuppl-final-booking_supplement_id ) ).
ENDMETHOD.


...
METHOD save.
CALL FUNCTION '/DMO/FLIGHT_TRAVEL_SAVE'.
ENDMETHOD.
METHOD cleanup.
CALL FUNCTION '/DMO/FLIGHT_TRAVEL_INITIALIZE'.
ENDMETHOD.
ENDCLASS.

SAVE Sequence
When the save method is called, the final commit is executed on the database and the data entered by the
user is persisted to the new travel instance. As depicted in the listing below, the save method only executes a
call to the function module /DMO/FLIGHT_TRAVEL_SAVE from the legacy business logic.
Further information: SAVE [page 231]
To discard all changes after the last save, the cleanup method is used. This method delegates the call to the
function module /DMO/FLIGHT_TRAVEL_INITIALIZE from legacy code.
Add the definition for the cleanup method to lsc_saver and call the function module in the implementation.
Implemented save sequence

...
METHOD save.
CALL FUNCTION '/DMO/FLIGHT_TRAVEL_SAVE'.
ENDMETHOD.
METHOD cleanup.
CALL FUNCTION '/DMO/FLIGHT_TRAVEL_INITIALIZE'.
ENDMETHOD.
ENDCLASS.

Checking Results
At this point, you have the opportunity to check how does the resulting app work, and especially the new
implementation of the CREATE operation. For this to happen, however, a suitable business service for UI
consumption must first be defined and published.
For more information, see: Defining Business Service for Fiori UI [page 563]

526 PUBLIC Develop
Related Information

Derived Data Types [page 150]
4.2.3.3.2.2.2 Implementing the UPDATE Operation for Travel

Data
This topic guides you through the implementation steps required for data updates to an existing travel
instance. In this case, however, in addition to the <method> FOR MODIFY, the <method> FOR READ
must also be implemented. It provides read access to the application buffer, which is necessary for ETag
comparison.
Preview
In our travel application scenario, the appropriate business data should be modifiable for all required items of
the travel instance when, for example, the user clicks the Edit button on the Fiori UI.
Saved Travel Data
In change mode, the end user is able to change the relevant travel fields as shown in the figure below. As soon
as the user chooses the Save button on the object page, the changed travel data is saved in the corresponding
tables and a new version of the related travel instance is created.

Develop PUBLIC 527
Saved Travel Data
Defining the Method for Implementing Travel Data Update

Corresponding to the template [page 517] for the root node behavior implementation, a local handler class
lhc_travel is defined to implement each changing operation. In this case, the update FOR MODIFY method
should only be used to implement the update operation for root instances. Therefore, the signature of this
method includes only one import parameter entities for referring to the travel (root) instances to be
updated.
Signature of the <method> FOR MODIFY (excerpt from template)

PRIVATE SECTION.
METHODS:
...
IMPORTING entities FOR UPDATE travel.

ENDCLASS.
Implementing the <method> FOR MODIFY for Travel Data Update

The basic structure of the FOR MODIFY method implementation is very similar to that of the handler class for
creation of travel instances:
- A loop on all new travel instances to be updated for the root node.
- Mapping the CDS view field names to the database table fields names using the operator MAPPING FROM
ENTITY. This operator maps every field that is declared in the mapping specification in the behavior definition.
- Mapping of the %control-structure of the importing parameter to the predefined flag structure
ls_travelx. The control structure identifies which entity fields were changed by the client. It contains the
key and the flag structure to the data fields and is used in BAPIs to flag each individual data field as changed.
- Call of the business logic function module /DMO/FLIGHT_TRAVEL_UPDATE to update travel instances.
- Message handling for processing messages in case of failure.
Each update call can produce failed keys and messages (lt_messages). Failed keys are addressed by the
content ID (<travel_update>-%cid_ref) and the value <travel_update>-travelid). In case of failure,

528 PUBLIC Develop
failed keys are saved in the failed-travel table, whereas the reported-travel table includes all instance-
specific messages.
Updating data of travel instances

...
METHOD update.
travel TYPE /dmo/travel,
travelx TYPE /dmo/s_travel_inx. "refers to x structure (> BAPIs)
LOOP AT entities ASSIGNING FIELD-SYMBOL(<travel_update>).
travel = CORRESPONDING #( <travel_update> MAPPING FROM ENTITY ).
travelx-travel_id = <travel_update>-TravelID.
travelx-_intx = CORRESPONDING #( <travel_update> MAPPING FROM ENTITY ).
CALL FUNCTION '/DMO/FLIGHT_TRAVEL_UPDATE'
EXPORTING
is_travel = CORRESPONDING /dmo/s_travel_in( travel )
is_travelx = travelx
IMPORTING
map_messages(
EXPORTING
cid = <travel_update>-%cid_ref
travel_id = <travel_update>-travelid
messages = messages
CHANGING
).
ENDLOOP.
ENDMETHOD.
...
ENDCLASS.


Develop PUBLIC 529
F2 Access for <fs_travel_update>
Implementing the <method> FOR READ for ETag Handling

In the context of data updates to an existing travel data set, it is important to retrieve current data from the
application buffer. As you remember, we specified an ETag for the root entity in the behavior definition:

etag master LastChangedAt
{
...

}
An ETag determines the changes to the requested data set to help prevent simultaneous updates of a data set
from overwriting each other. This is precisely the reason why the ETag check requires data from the buffer. The
<method> FOR READ is designed to return the data from the application buffer.
For more information on how to implement this method, see Implementing the READ Operation for Travel Data
[page 531].
Related Information


530 PUBLIC Develop
4.2.3.3.2.2.3 Implementing the READ Operation for Travel

Data
This topic guides you through the implementation steps required to read travel instances from the
Context
In contrast to the CREATE, UPDATE, or DELETE operation, the READ does not have its direct trigger on a Fiori UI.
 Remember
The GO button on the UI does not call the <method> FOR READ (the transactional READ) in the behavior
pool. Instead, the GO button executes a query via the RAP runtime engine and reads data directly from the
database.
The READ operation provides read access to the application buffer. It is used to retrieve data for further
processing during the interaction phase. This is necessary, for example, for ETag comparison when executing
an UPDATE. Before the to check the conditions for actions and decide if they are enabled or disabled. In the
travel scenario, the action <method> for UPDATE is called, the ETag value in the application buffer must be
compared to the value that is displayed on the UI. Only if these values correspond is the UPDATE to triggered.
This check ensures that the data the end user sees on the UI has not been changed by other consumers.
The READ is also necessary for dynamic action control [page 129] set_to_booked is disabled when the
status is booked. Hence, the data from the transactional buffer must be read to display the action button
correspondingly.
Both use cases are relevant for our travel scenario. Therefore it is necessary to implement a <method> FOR
READ.
The READ is also necessary to complete the business object and make it accessible by EML. In this case, you
can consume the business object directly from ABAP.
The READ operation cannot be declared in the behavior definition as it is always implicitly assumed that a READ
is implemented.
 Note
 Cloud If you use groups in your behavior definition, you must explicitly specify the READ operation in one
of the groups. For more information, see Using Groups in Large Development Projects [page 212].

Develop PUBLIC 531
Defining the signature of the <method> FOR READ
In the definition part of the handler class for travel, define the method read_travel for READ with an
importing parameter and a result parameter.
Signature of the <method> for READ

PRIVATE SECTION.
METHODS:
...
IMPORTING keys FOR READ travel RESULT result.
... .
ENDCLASS.

For more information, see <method> FOR READ [page 145].
Implementing the <method> FOR READ

To return the actual data from the application buffer, the travel ID that is imported is passed to the
reading function module /DMO/FLIGHT_TRAVEL_READ. The function module returns the entity instance
corresponding to the travel ID and messages if an error occurs. The result parameter result is then filled
with the keys and the values of the fields that the consumer has requested. These fields are flagged in the
control structure of the importing parameter keys.
With the changing parameter failed, you specify the fail cause if something goes wrong. If, for example, the
used function module returns the message number 16, the travel ID was not found. In this case, you can return
the fail cause not_found. For all other errors, return fail cause unspecific.
Reading travel instances from the application buffer

...
METHOD read.
DATA: travel_out TYPE /dmo/travel,
messages TYPE /dmo/t_message.
LOOP AT keys ASSIGNING FIELD-SYMBOL(<travel_to_read>) GROUP BY
<travel_to_read>-%tky.
CALL FUNCTION '/DMO/FLIGHT_TRAVEL_READ'
EXPORTING
iv_travel_id = <travel_to_read>-travelid
IMPORTING
map_messages(
EXPORTING
travel_id = <travel_to_read>-TravelID
messages = messages
IMPORTING
CHANGING
).
INSERT CORRESPONDING #( travel_out MAPPING TO ENTITY ) INTO TABLE result.
ENDIF.
ENDLOOP.
ENDMETHOD.
...

532 PUBLIC Develop

Testing the READ
In contrast to the CREATE, UPDATE and DELETE operation, the READ cannot be easily tested using a Fiori UI, as
there is no direct execution trigger for reading the data from the application buffer. Nevertheless, you can test
your READ implementation by using EML.
 Example
READ ENTITY /DMO/I_Travel_U FIELDS ( TravelID

AgencyID
CustomerID
BeginDate
EndDate
BookingFee
TotalPrice
CurrencyCode
Memo
Status
LastChangedAt )
WITH VALUE #( ( %key-TravelID = lv_travel_id ) )
RESULT DATA(lt_received_travel_data)

FAILED DATA(ls_failed).
To retrieve the complete entity instance for the respective travel ID, you have to flag every element
explicitly. For more information about EML, see Entity Manipulation Language (EML) [page 235].
4.2.3.3.2.2.4 Implementing the DELETE Operation for Travel

Instances
This topic guides you through the implementation steps required to delete an existing travel instance.
Preview
In our scenario, the appropriate travel instance should be deleted when, for example, the user clicks the Delete
button on the Fiori UI.
Selecting a Travel Entry and Clicking the Delete Button

Develop PUBLIC 533
Expected Behavior
Defining the Handler Class for Deletion of Travel Instances

Corresponding to the template [page 517] for the root node behavior implementation, a local handler class is
defined to implement each changing operation. In this case, the delete FOR MODIFY is used to implement
the delete operation for root instances. As given in the listing below, the signature of the <method> FOR
MODIFY includes only one import parameter keys for referring to the travel (root) instances to be deleted.
Signature of the delete FOR MODIFY (excerpt from template)

PRIVATE SECTION.
METHODS:
...
IMPORTING keys FOR DELETE travel.
... .
ENDCLASS.

Implementing the Deletion of Travel Instances

To delete travel instances, the function module /DMO/FLIGHT_TRAVEL_DELETE of the legacy business logic is
called.
Each delete operation call can produce failed keys and messages (lt_messages). Failed keys are addressed
by the content ID (<travel_delete>-%cid_ref [page 154]) and the key value <travel_delete>-
travel_id). In case of failure, failed keys are saved in the failed-travel table, whereas the reported-
travel table includes all instance-specific messages.
Deleting travel instances

...
METHOD delete.
DATA: messages TYPE /dmo/t_message.
LOOP AT keys ASSIGNING FIELD-SYMBOL(<travel_delete>).
CALL FUNCTION '/DMO/FLIGHT_TRAVEL_DELETE'
EXPORTING
iv_travel_id = <travel_delete>-travelid
IMPORTING
map_messages(
EXPORTING
cid = <travel_delete>-%cid_ref
travel_id = <travel_delete>-travelid
messages = messages

534 PUBLIC Develop
CHANGING
).
ENDLOOP.
ENDMETHOD.
...
ENDCLASS.

Related Information

4.2.3.3.2.2.5 Implementing the CREATE Operation for

Associated Bookings
In this topic, you will be guided through all implementation steps required for creation of new bookings.
In our demo application, we assume that new bookings cannot be created separately but can only in
conjunction with a given travel instance.
The fact that new instances of the bookings can only be created for a specific travel instance is considered in
the behavior definition by the _Booking association:

...
{
...
}

The keyword { create; } declares that this association is create-enabled what exactly means that instances
of the associated bookings are created by a travel instance.
Preview
To add a new booking to a selected travel instance, the end user must click the + icon and edit some fields to
specify the required information for a new booking.

Develop PUBLIC 535
Object Page for Editing Individual Booking Values
As soon as the user clicks the Save button on the Fiori object page, a booking data set with a new booking
number is created.
New Booking Data Set
Defining Method for Creation of Associated Bookings
Corresponding to the template [page 517] for the root entity, the local handler class lhc_travel is defined to
implement each changing operation in one individual <method> FOR MODIFY. In this case, the cba_booking
FOR MODIFY method should only be used to implement the create operation for booking instances by means
of an association. The signature of the cba_Booking FOR MODIFY includes only one import parameter
entities_cba to refer to the associated booking instances to be created.
To identify the associated bookings, the aliases for the root entity and the child entity are used - according to
the aliases specified in the behavior definition. The association is expressed in the form:
… FOR CREATE root\_child_entity.

536 PUBLIC Develop
Signature of the cba_booking FOR MODIFY method (excerpt from template)

PRIVATE SECTION.
METHODS:
...
METHODS cba_Booking FOR MODIFY
IMPORTING entities_cba FOR CREATE travel\_Booking.
ENDCLASS.

Implementing a FOR MODIFY Method for Creation of New Booking Instances

As reproduced in the listing below, the implementation of the FOR MODIFY method is initiated by a loop
across all selected travel instances for which associated bookings are to be created. Each selected travel (root)
instance is represented by the travel ID as a primary key (travelid).
Even in a case like this, it can happen that a consumer works with data that is not yet persisted and might not
have a primary key yet (for example, if the primary key is going to be created later in the save sequence (late
numbering)). In such cases, a temporary primary key, the content ID (%CID) for the travel instance is used as
long as no primary key was created by BO runtime. The content ID is then written to the mapped-travel table.
Before a new booking data set is created, we first need to retrieve all bookings (booking_old) that already
exist for the selected travel instance. This is done by calling the /DMO/FLIGHT_TRAVEL_READ function module.
In case of failure, the message is handled by means of the map_messages method, as we know from the
implementation of FOR MODIFY in the previous topics.
In case of success, the maximum booking number has to be determined. The last given booking number
last_booking_id is increased by 1 for the new booking instance.
The creation of new bookings for a given travel instance takes place in a further loop across the booking
instances to be created, which are addressed by the association <travel>-%target. This association
includes the predefined component %target, which is used to address the target of composition.
To provide the incoming structure for bookings with data, the mapping between the element in CDS views
and the original table fields is required. This mapping is implemented by the operator MAPPING FROM
ENTITY USING CONTROL, which maps the CDS view fields to the database table fields based on the mapping
specification in the behavior definition and the control structure.
Before the new booking data sets are created by calling the function module /DMO/FLIGHT_TRAVEL_UPDATE,
the booking ID for the booking instance to be created is easily determined by the statement booking-
booking_id += 1.
In case of success, the values with the content ID %CID and the key values travelid, and bookingid are
written to the mapped-booking table.
The function call can produce failed keys (<bbooking_create>-%cid) and messages (messages). Any failed
keys are stored in the table failed-booking whereas the reported-booking table includes all messages
that are specific for the failed booking instance
 Expand the following code sample to view the source code of method cba_Booking.
 Sample Code

...

Develop PUBLIC 537
METHOD cba_Booking.
booking_old TYPE /dmo/t_booking,
booking TYPE /dmo/booking,
last_booking_id TYPE /dmo/booking_id VALUE '0'.
LOOP AT entities_cba ASSIGNING FIELD-SYMBOL(<travel>).
DATA(travelid) = <travel>-travelid.
EXPORTING
iv_travel_id = travelid
IMPORTING
et_booking = booking_old
map_messages(
EXPORTING
cid = <travel>-%cid_ref
travel_id = <travel>-TravelID
messages = messages
IMPORTING
CHANGING
).
IF failed_added = abap_true.
LOOP AT <travel>-%target ASSIGNING FIELD-SYMBOL(<booking>).
map_messages_assoc_to_booking(
EXPORTING
cid = <booking>-%cid
booking_id = <booking>-BookingID
is_dependend = abap_true
messages = messages
CHANGING
failed = failed-booking
reported = reported-booking
).
ENDLOOP.
ELSE.
" Set the last_booking_id to the highest value of booking_old
booking_id or initial value if none exist
last_booking_id = VALUE #( booking_old[ lines( booking_old ) ]-
booking_id OPTIONAL ).
LOOP AT <travel>-%target ASSIGNING FIELD-SYMBOL(<booking_create>).
booking = CORRESPONDING #( <booking_create> MAPPING FROM ENTITY
USING CONTROL ) .
last_booking_id += 1.
booking-booking_id = last_booking_id.
EXPORTING
is_travel = VALUE /dmo/s_travel_in( travel_id = travelid )
is_travelx = VALUE /dmo/s_travel_inx( travel_id = travelid )
it_booking = VALUE /dmo/t_booking_in( ( CORRESPONDING
#( booking ) ) )
it_bookingx = VALUE /dmo/t_booking_inx(
(
booking_id = booking-booking_id
action_code = /dmo/if_flight_legacy=>action_code-create
)
)
IMPORTING
map_messages_assoc_to_booking(
EXPORTING
travel_id = <booking_create>-TravelID
booking_id = <booking_create>-bookingID
messages = messages
IMPORTING

538 PUBLIC Develop
failed_added = failed_added
CHANGING
reported = reported-booking
).
INSERT
VALUE #(
%cid = <booking_create>-%cid
travelid = travelid
bookingid = booking-booking_id
) INTO TABLE mapped-booking.
ENDIF.
ENDLOOP.
ENDIF.
ENDLOOP.
ENDMETHOD.

Related Information

4.2.3.3.2.2.5.1 Implementing Dynamic Operation Control for

Create By Association
This topic guides you through the required implementation steps to dynamically enable and disable the create
by association operation for bookings.
Context
Depending on the value of the Status field of the travel instance, the create by association operation is
enabled or disabled on the corresponding travel instance.
The Fiori Elements app preview displays the create button for the associated bookings on the object page only
if the operation is enabled.

Develop PUBLIC 539
Defining dynamic feature control in the behavior definition
In the behavior definition, the feature control for the create by association is defined as follows:
implementation unmanaged;

...
{
...
association _Booking { create (features: instance); }
...

}
Implementing dynamic feature control in the behavior pool
The <method> FOR FEATURES must be declared. For more information, see <method> FOR FEATURES [page
148].
The travel instance is read and, depending on the value of the Status field, the create by association is
enabled or disabled.
 Expand the following code sample to view the source code of the CLASS lhc_travel DEFINITION
INHERITING FROM cl_abap_behavior_handler.
 Sample Code

PRIVATE SECTION.
METHODS:
...
ENDCLASS.
...
READ ENTITIES OF /DMO/I_Travel_U IN LOCAL MODE
ENTITY Travel
FIELDS ( TravelID Status )
RESULT DATA(travel_read_results)
FAILED failed.
result = VALUE #(
FOR travel_read_result IN travel_read_results (
%tky = travel_read_result-%tky
%features-%action-set_status_booked = COND #( WHEN travel_read_result-
Status = 'B'
THEN if_abap_behv=>fc-o-
disabled ELSE if_abap_behv=>fc-o-enabled )
%assoc-_Booking = COND #( WHEN travel_read_result-
Status = 'B' OR travel_read_result-Status = 'X'
) ).
ENDMETHOD.

ENDCLASS.

540 PUBLIC Develop
Related Information
Feature Control [page 128]
4.2.3.3.2.2.6 Implementing the READ Operation for

Associated Bookings
This topic guides you through the implementation steps required to read booking instances associated to a
travel instance from the buffer.
Context
Just like the READ for travel data, the READ by association does not have an explicit trigger on the UI.
Nevertheless, the BO must be fully consumable by EML and therefore it is necessary to implement a method
that reads the bookings that are associated to a specific travel ID in our travel scenario.
The READ by association operation provides read access to the application buffer by reading child entity
instances of a parent entity. It is used to retrieve data for further processing during the interaction phase.
The READ by association operation does not have to be declared in the behavior definition as it always
implicitly assumed that READ by association is implemented. However, you can specify it explicitly:

{
...
association _Booking;

}
 Note
 Cloud If you use groups in your behavior definition, you must explicitly specify the READ by
association operation in one of the groups. If CREATE by association is also enabled for the BO,
the READ and the CREATE by association must be assigned to the same group due to its syntactical
relation. For more information, see Using Groups in Large Development Projects [page 212].
1. Defining the signature of the <method> FOR READ by association

In the definition part of the handler class for travel, define the method read_booking_ba for READ
travel\_Booking with the entity input parameters IMPORTING and FULL, and the output parameters ,
RESULT and LINK.

Develop PUBLIC 541
The boolean parameter FULL indicates whether the consumer requests complete entity instances or only the
keys which are returned with the parameter LINK.
The parameter RESULT returns the complete set of associated entity instances based on the control structure
of the importing parameter.
The parameter LINK returns the key of the source entity and of the associated target entities.
Signature of the <method> FOR READ by association

PRIVATE SECTION.
METHODS:
...
METHODS rba_Booking FOR READ
IMPORTING keys_rba FOR READ travel\_Booking FULL result_requested RESULT
... .
ENDCLASS.

Implementing the <method> FOR READ by association

To return the actual data from the application buffer, the imported travel ID is passed to the reading function
module /DMO/FLIGHT_TRAVEL_READ. The function module returns the entity instances of the associated
bookings corresponding to the travel ID and possible messages if an error occurs. If no message is returned, for
each associated booking, fill the output parameter association_links with the corresponding source key
for the travel instance and the target key for the booking instance.
In the changing parameter failed, you specify the fail cause if something goes wrong. If, for example, the used
function module returns the message number 16, the travel ID was not found. In this case, you can return the
fail cause not_found. For all other error, return fail cause unspecific.
Reading associated booking instances from the application buffer

METHOD rba_Booking.
booking_out TYPE /dmo/t_booking,
booking LIKE LINE OF result,
LOOP AT keys_rba ASSIGNING FIELD-SYMBOL(<travel_rba>) GROUP BY <travel_rba>-
TravelID.
EXPORTING
iv_travel_id = <travel_rba>-travelid
IMPORTING
et_booking = booking_out
map_messages(
EXPORTING
travel_id = <travel_rba>-TravelID
messages = messages
IMPORTING
CHANGING
).

542 PUBLIC Develop
LOOP AT booking_out ASSIGNING FIELD-SYMBOL(<booking>).
"fill link table with key fields
INSERT
VALUE #(
source-%tky = <travel_rba>-%tky
target-%tky = VALUE #(
TravelID = <booking>-travel_id
BookingID = <booking>-booking_id
) )
INTO TABLE association_links.
IF result_requested = abap_true.
booking = CORRESPONDING #( <booking> MAPPING TO ENTITY ).
INSERT booking INTO TABLE result.
ENDIF.
ENDLOOP.
ENDIF.
ENDLOOP.
SORT association_links BY target ASCENDING.
DELETE ADJACENT DUPLICATES FROM association_links COMPARING ALL FIELDS.
SORT result BY %tky ASCENDING.
DELETE ADJACENT DUPLICATES FROM result COMPARING ALL FIELDS.
ENDMETHOD.

Testing
Just like the READ operation, the READ by association cannot be easily tested using a Fiori UI, as there is
no direct execution trigger for reading the associated booking from the application buffer. Nevertheless, you
can test your READ by association implementation by using EML.
 Example
READ ENTITY /dmo/i_travel_u

BY \_Booking FIELDS ( AirlineID
BookingDate
BookingID
CustomerID
CurrencyCode
LastChangedAt )
WITH VALUE #( ( %key-TravelID = travelID ) )
RESULT DATA(lt_read_bookings_ba)
LINK DATA(lt_link_table)

FAILED DATA(ls_failed_rba).
If you request the RESULT parameter, the importing parameter FULL is set and you retrieve the values
based on the control flags. The parameter LINK is independent on the control flags, it always retrieves the
keys of the source and target entity.

Develop PUBLIC 543
4.2.3.3.2.2.7 Implementing the LOCK Operation
This topic guides you through the implementation steps required to lock instances on the database.
Context
Locking prevents simultaneous changes on the database.
The lock operation is executed before modify operations. It locks the entity instance during the time of the
modify operation and disables other clients to modify the specific instance and all its locking related instances.
As soon as the modify operation is finished, the lock is released.
For more information, see Pessimistic Concurrency Control (Locking) [page 38].
In our unmanaged scenario, the travel entity was defined as lock master and the booking entity as lock
dependent. That means, the locking mechanism always locks the lock master instances and all its dependents.
For example, if the lock operation is executed because a booking instance is updated, the parent travel instance
and all its booking instances are also being locked.
To enable locking, the method FOR LOCK must be implemented. The legacy code of the unmanaged scenario
includes a lock object, which must be called in the method FOR LOCK to lock the relevant entity instances.
Preview
In our scenario, it should not be possible to save changes on the database, while another entity instance of the
same lock master entity instance is being changed at the same moment. In this case, the end user on the UI
gets an error message:
Concurrent Changes of Entity Instances of the Same Lock Master Instance

544 PUBLIC Develop
The legacy code of the unmanaged scenario includes a lock object, which must be called in the method FOR
LOCK to lock the relevant entity instances.
Defining the Handler Class for Locking Travel Instances

Corresponding to the template [page 517] for the root node behavior implementation, a local handler class is
defined to implement each operation. In this case, the method lock FOR LOCK is used to implement the lock
operation for the travel business object. As you can see in the listing below, the signature of <method> FOR
LOCK includes only one importing parameter keys for referring to the lock master's key.
Signature of the lock FOR LOCK (excerpt from template)

PRIVATE SECTION.
METHODS:
...
METHODS lock FOR LOCK
IMPORTING keys FOR LOCK travel.
... .
ENDCLASS.

Implementing Locking of Travel Instances

To lock a travel instance and its lock dependents, instantiate the lock object /DMO/ETRAVEL
of the legacy business logic. This is done by calling the factory method get_instance of
cl_abap_lock_object_factory. This instantiation must not fail, except for technical errors. You can raise a
short dump if this happens.
Call the enqueue method of the lock object and pass the imported travel ID to execute locking. If the instance
is already locked, you will get an exception. This exception can be handled by the handle_travel_messages
of the auxiliary class to fill failed and reported table. If the lock fails for technical reasons, raise a short
dump.
Locking travel instances

...
METHOD lock.
TRY.
"Instantiate lock object
DATA(lock) = cl_abap_lock_object_factory=>get_instance( iv_name = '/DMO/
ETRAVEL' ).
CATCH cx_abap_lock_failure INTO DATA(exception).
RAISE SHORTDUMP exception.
ENDTRY.
LOOP AT keys ASSIGNING FIELD-SYMBOL(<travel>).
TRY.
"enqueue travel instance
lock->enqueue(
it_parameter = VALUE #( ( name = 'TRAVEL_ID' value = REF
#( <travel>-travelid ) ) )
).
"if foreign lock exists
CATCH cx_abap_foreign_lock INTO DATA(foreign_lock).
map_messages(

Develop PUBLIC 545
EXPORTING
messages = VALUE #( (
msgid = '/DMO/CM_FLIGHT_LEGAC'
msgty = 'E'
msgno = '032'
msgv1 = <travel>-travelid
msgv2 = foreign_lock->user_name )
)
CHANGING
).
CATCH cx_abap_lock_failure INTO exception.
RAISE SHORTDUMP exception.
ENDTRY.
ENDLOOP.
ENDMETHOD.
...
ENDCLASS.

Testing
To test if the locking mechanism works properly, open the preview twice and set a breakpoint after the method
enqueue.
In the first preview application, delete or update any entity instance. The ADT debugger stops at the
breakpoint. At this point, the enqueue lock is already set on the chosen entity instance's lock master and
its dependents. Try to do a modify operation with the other preview application on the same entity instance
or any of its lock master's dependents. Do not stop at the breakpoint this time. You will see that the modify
operation is rejected because the entity instance is locked by the client of the first preview application.
Related Information


546 PUBLIC Develop
4.2.3.3.2.2.8 Implementing the SET_STATUS_BOOKED
Action
This topic describes the implementation of an action related to the travel instances. Using this action, the end
user should be able to change the status of travel processing.
Preview
Again, we use the option of running the resulting app based on Fiori Elements to check the action execution.
When we run the app, the UI screen provides the button Set to Booked for the action as shown in the figure
below.
Original Status is P (= In Process)
Changed Status After Action Execution (B = Booked)
Once an action is defined in the behavior definition, it must be implemented in the behavior pool of the
business object.
Defining the Method for Action
As described in Action Implementation [page 106] the method FOR ACTION must be declared in the private
section of the behavior pool.
The beginning of the source code excerpt in the following listing shows the declaration of two table types, one
for ACTION IMPORT (the importing parameter) and the other for ACTION RESULT (the exporting parameter).
The importing parameter is a freely selected name . The action name set_status_booked refers to the name
of the action defined in the behavior definition and the entity travel, on which the action is assigned. The
result parameter is also a freely selected name.

Develop PUBLIC 547
Defining the signature of set_travel_status FOR MODIFY

PRIVATE SECTION.
METHODS:
...
METHODS set_status_booked FOR MODIFY
IMPORTING keys FOR ACTION travel~set_status_booked RESULT result.
...
ENDCLASS.

Implementing set_travel_status FOR MODIFY
To execute the actual action, the function module /DMO/FLIGHT_TRAVEL_SET_BOOKING of the legacy
business logic is called.
The main implementation steps are the same as in the implementation of the CUD operations.
To fill the action result parameter accordingly to the action definition, a read must be executed.
LISTING 2: Implementing the action set_travel_status

...
METHOD set_status_booked.
travel_out TYPE /dmo/travel,
travel_set_status_booked LIKE LINE OF result.
CLEAR result.
LOOP AT keys ASSIGNING FIELD-SYMBOL(<travel_set_status_booked>).
DATA(travelid) = <travel_set_status_booked>-travelid.
CALL FUNCTION '/DMO/FLIGHT_TRAVEL_SET_BOOKING'
EXPORTING
IMPORTING
map_messages(
EXPORTING
travel_id = <travel_set_status_booked>-TravelID
messages = messages
IMPORTING
CHANGING
).
EXPORTING
IMPORTING
es_travel = travel_out.
travel_set_status_booked-travelid = travelid.
travel_set_status_booked-%param = CORRESPONDING #( travel_out
MAPPING TO ENTITY ).
travel_set_status_booked-%param-travelid = travelid.
APPEND travel_set_status_booked TO result.
ENDIF.
ENDLOOP.

ENDMETHOD.

548 PUBLIC Develop
Implementing Dynamic Action Control
For dynamic control of actions acting on individual entity instances, the option (features: instance) must
be added to the action set_status_booked in the behavior definition. The required implementation must
be provided in the referenced class pool. In the implementation handler of the class pool you can specify the
condition on which the action is enabled or disabled.
More on this: FOR INSTANCE FEATURES, FEATURES (ABAP- Keyword Documentation)
Related Information

4.2.3.3.2.2.8.1 Implementing Dynamic Action Control
This topic guides you through the required implementation steps to dynamically enable and disable actions.
Preview
The following figure shows the effect of dynamic control on the action button Set to Booked: Since the selected
travel instance has a status of B (Booked), the action button is disabled.
Dynamic Feature Control for an Action
1. Defining dynamic feature control in the behavior definition

In the behavior definition, the feature control for the action set_status_booked is defined as follows:


Develop PUBLIC 549
...
{
...
action ( features : instance ) set_status_booked result [1] $self;
...
}

2. Adding dynamic feature control for actions to the method get_features in the behavior
pool
The feature control for actions must be added to the method get_features in the behavior pool. You can
implement feature control for different actions or operations in the same method.
Depending on the value of Status field, the action set_status_booked is enabled or disabled.
 Expand the following code sample to view the source code of the method get_features.
 Sample Code

PRIVATE SECTION.
METHODS:
...
get_features FOR FEATURES
IMPORTING keys REQUEST requested_features FOR
travel
RESULT result.
ENDCLASS.
...
******************************************************************************
**
*
* Implements the dynamic action handling for travel instances
*
******************************************************************************
**
METHOD get_features.
READ ENTITIES OF /DMO/I_Travel_U IN LOCAL MODE
ENTITY Travel
FIELDS ( TravelID Status )
RESULT DATA(lt_travel_result)
FAILED failed.
result = VALUE #(
FOR ls_travel IN lt_travel_result (
%key = ls_travel-%key
%features-%action-set_status_booked = COND #( WHEN ls_travel-Status =
'B'
%assoc-_Booking = COND #( WHEN ls_travel-Status =
'B' OR ls_travel-Status = 'X'
) ).
ENDMETHOD.
ENDCLASS.


550 PUBLIC Develop
Related Information
Feature Control [page 128]
4.2.3.3.2.3 Creating the Behavior Pool for the Booking Child

Entity
Procedure 1: Create a Behavior Pool /DMO/BP_BOOKING_U
To launch the wizard tool for creating a behavior implementation, do the following:
implementation in class /dmo/bp_booking_u unique

2. The behavior definition offers a quick to create a behavior pool corresponding to the behavior described in
the behavior definition. Follow the quick fix to start the wizard for creating an ABAP class.
For a more detailed description, see .:
Results: Behavior Pool for the Booking Child Entity

The generated behavior pool (in our case /DMO/CL_BOOKING_U) provides you with an extension FOR
BEHAVIOR OF.
New Behavior Pool

Develop PUBLIC 551
Procedure 2: Define a Skeleton of Local Classes Corresponding to the
Behavior Model
Based on the declarations in the behavior definition /DMO/I_TRAVEL_U, the behavior implementation offers a
skeleton of the local classes for the booking entity:
Listing: Template for local classes of /DMO/BP_BOOKING_U

CLASS lhc_booking DEFINITION INHERITING FROM cl_abap_behavior_handler.
PRIVATE SECTION.
TYPES tt_booking_failed TYPE TABLE FOR FAILED /dmo/i_booking_u.
TYPES tt_booking_reported TYPE TABLE FOR REPORTED /dmo/i_booking_u.
TYPES tt_bookingsupplement_failed TYPE TABLE FOR FAILED /dmo/
i_bookingsupplement_u.
TYPES tt_bookingsupplement_reported TYPE TABLE FOR REPORTED /dmo/
IMPORTING entities FOR UPDATE booking.
IMPORTING keys FOR DELETE booking.
IMPORTING keys FOR READ booking RESULT result.
METHODS rba_Booksupplement FOR READ
IMPORTING keys_rba FOR READ booking\_Booksupplement FULL result_requested
RESULT result LINK association_links.
METHODS rba_Travel FOR READ
IMPORTING keys_rba FOR READ booking\_Travel FULL result_requested RESULT
METHODS cba_Booksupplement FOR MODIFY
IMPORTING entities_cba FOR CREATE booking\_Booksupplement.
METHODS map_messages
IMPORTING
booking_id TYPE /dmo/booking_id OPTIONAL
EXPORTING
CHANGING
METHODS map_messages_assoc_to_booksupp
IMPORTING
booking_supplement_id TYPE /dmo/booking_supplement_id OPTIONAL
EXPORTING
CHANGING
failed TYPE tt_bookingsupplement_failed
reported TYPE tt_bookingsupplement_reported.
ENDCLASS.
ENDCLASS.
CLASS lhc_booking IMPLEMENTATION.
...
ENDCLASS.


552 PUBLIC Develop
4.2.3.3.2.3.1 Implementing the UPDATE, DELETE, and READ
Operations for Booking Instances
This topic guides you through all implementation steps required for data updates and deletion of booking data
sets.
The behavior definition in our demo application scenario requires the standard operations update,
and delete for the booking child entity. Note that the read operation is not explicitly declared in
the behavior definition, but implicitly expected. The create is handled in the travel behavior by a
create_by_association. In addition, since we use different CDS view field names than in the database
table, we need a mapping specification from CDS names to database fields names.
define behavior for /DMO/I_Booking_U alias Booking

implementation in class /DMO/BP_BOOKING_U unique
{
field ( readonly ) TravelID, BookingID;
field ( mandatory ) BookingDate, CustomerID, AirlineID, ConnectionID,
FlightDate;
update;
delete;
mapping for /dmo/booking control /dmo/s_booking_intx
{
AirlineID = carrier_id;
}

}
The create operation is already implemented by using the association relation between the travel root
entity and the booking child entity. Further information: Implementing the CREATE Operation for Associated
Bookings [page 535]
Preview (Update of Booking Data Sets)
In our application scenario, the appropriate booking data sets should be modifiable for all required fields of the
booking instance when, for example, the user clicks the Edit button on the object page of the Fiori UI.

Develop PUBLIC 553
Edit and Delete Buttons are Available for Each Booking Data Set
In change mode, the end user is able to change the relevant travel fields as shown in the figure below. As soon
as the user chooses the Save button on the object page, the changed booking data is persisted on the database
and a new version of the related booking instance is created.
Object Page for Editing Individual Booking Values

554 PUBLIC Develop
Defining and Implementing UPDATE for Booking Data

Corresponding to the template [page 552] for behavior implementation of the booking child entity, one local
handler class lhc_booking is defined to implement each changing operation in one individual <method> FOR
MODIFY, one for updating booking data sets and another one for deleting bookings.
The update_booking FOR MODIFY method of the handler lhc_booking implements the update operation
for bookings. The signature of this method includes only one import table parameter entities for referring to
the booking instances to be updated.
To update data of bookings, the function module /DMO/FLIGHT_TRAVEL_UPDATE is called. In addition to the
incoming parameters is_travel and it_booking, the corresponding flag structure is_travelx as well as
the flag table type it_bookingx are used.
When updating booking data sets, we must first check which individual data was changed by the end user. This
check is done by mapping the control structure of the importing parameter on a local structure that can be
passed to the update function module.
Message handling for processing instance-specific messages in case of failure is implemented by the
handle_booking_messages method. Failed keys are addressed by the booking content ID (<booking>-
%cid_ref) and the values for the travel ID <booking>-travelid) and the booking ID <booking>-
bookingid. In case of failure, failed keys are saved in the failed-booking table, whereas the reported-
booking table contains all instance-specific messages.
 Expand the following code sample to view the source code of the method update.
 Sample Code
**********************************************************************

*
* Handler class for managing bookings
*
**********************************************************************
PRIVATE SECTION.
METHODS:
update FOR MODIFY
IMPORTING entities FOR UPDATE booking,
...
ENDCLASS.
**********************************************************************
*
* Implements the UPDATE operation for a set of booking instances
*
**********************************************************************
METHOD update.
DATA messages TYPE /dmo/t_message.
DATA booking TYPE /dmo/booking.
DATA bookingx TYPE /dmo/s_booking_inx.
LOOP AT entities ASSIGNING FIELD-SYMBOL(<booking>).
booking = CORRESPONDING #( <booking> MAPPING FROM ENTITY ).
bookingx-booking_id = <booking>-BookingID.
bookingx-_intx = CORRESPONDING #( <booking> MAPPING FROM ENTITY ).
bookingx-action_code = /dmo/if_flight_legacy=>action_code-update.
EXPORTING
is_travel = VALUE /dmo/s_travel_in( travel_id = <booking>-
travelid )

Develop PUBLIC 555
is_travelx = VALUE /dmo/s_travel_inx( travel_id = <booking>-
travelid )
it_booking = VALUE /dmo/t_booking_in( ( CORRESPONDING
#( booking ) ) )
it_bookingx = VALUE /dmo/t_booking_inx( ( bookingx ) )
IMPORTING
/dmo/cl_travel_auxiliary=>handle_booking_messages(
EXPORTING
cid = <booking>-%cid_ref
travel_id = <booking>-travelid
booking_id = <booking>-bookingid
messages = messages
CHANGING
reported = reported-booking ).
ENDLOOP.

ENDMETHOD.
Adding Data Type Declarations for the Booking Entity in the Auxiliary Class
To use the required import, export, or changing parameters in the signature of methods to be defined for
handling booking operations (later on, in the booking behavior pool’s FOR MODIFY methods), we must first add
the appropriate type declarations to the PUBLIC section in the definition part of our auxiliary class.
 Expand the following code sample to view the source code of the auxiliary class /dmo/
cl_travel_auxiliary.
 Sample Code

PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
* Type definition for import parameters --------------------------

TYPES tt_booking_failed TYPE TABLE FOR FAILED /dmo/i_booking_u.
TYPES tt_booking_reported TYPE TABLE FOR REPORTED /dmo/i_booking_u.
...
ENDCLASS.

Implementing Message Handling

When handling changing operations for booking instances, fault events may occur. For the processing of
instance-specific messages in such a case, the method handle_booking_messages is used.
To refer to an individual data set where an error (msgty = 'E' ) or an abort (msgty = 'A') occurred, the
FAILED table is used, whereas the instance-specific messages are stored in the REPORTED table.
However, messages that originate from the legacy code must be mapped to the messages of the class-based
BO framework. To be reused in different behavior pools, the corresponding message handler method is defined
and implemented in the helper class /dmo/cl_travel_auxiliary.
 Expand the following code sample to view the source codeof the method handle_booking_messages.

556 PUBLIC Develop
 Sample Code

PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
...
CLASS-METHODS handle_booking_messages
IMPORTING
CHANGING
ENDCLASS.
CLASS /dmo/cl_travel_auxiliary IMPLEMENTATION.
...
METHOD handle_booking_messages.
LOOP AT messages INTO DATA(message) WHERE msgty = 'E' OR msgty = 'A'.
APPEND VALUE #( %cid = cid
travelid = travel_id
bookingid = booking_id
%fail-cause = get_cause_from_message(
iv_msgid = message-msgid
iv_msgno = message-msgno
) ) TO failed.
APPEND VALUE #( %msg = get_message_object( )->new_message(
id = message-msgid
number = message-msgno
severity =
v1 = message-msgv1
v2 = message-msgv2
v3 = message-msgv3
v4 = message-msgv4 )
%key-TravelID = travel_id
%cid = cid
TravelID = travel_id
BookingID = booking_id ) TO reported.
ENDLOOP.
ENDMETHOD.
...
ENDCLASS.

Defining and Implementing the DELETE operation for Booking Instances

In this case, the FOR MODIFY method is used to implement the delete operation for booking data sets.
Therefore, the signature of the <method> FOR MODIFY includes only one import parameter keys for referring
to the booking instance to be deleted. To identify the child entity for bookings, the alias booking is used -
according to the alias specified in the behavior definition.
The basic steps within the method implementation are similar to those we got to know in the previous method
update. The function module /DMO/FLIGHT_TRAVEL_UPDATE is also called for the delete operation. Here, as
in the previous case, the same incoming parameters are used, including the flag structure is_travelx as well
as the flag table it_bookingx). The appropriate action code for deleting bookings is defined by the statement
action_code = /dmo/if_flight_legacy=>action_code-delete.
 Expand the following code sample to view the source codeof the method delete.

Develop PUBLIC 557
 Sample Code
**********************************************************************

*
*
**********************************************************************
PRIVATE SECTION.
METHODS:
...
delete FOR MODIFY
IMPORTING keys FOR DELETE booking,
...
ENDCLASS.
**********************************************************************
*
* Implements the DELETE operation for a set of booking instances
*
**********************************************************************
METHOD delete.
DATA messages TYPE /dmo/t_message.
LOOP AT keys ASSIGNING FIELD-SYMBOL(<booking>).
EXPORTING
is_travel = VALUE /dmo/s_travel_in( travel_id = <booking>-
travelid )
is_travelx = VALUE /dmo/s_travel_inx( travel_id = <booking>-
travelid )
it_booking = VALUE /dmo/t_booking_in( ( booking_id = <booking>-
bookingid ) )
it_bookingx = VALUE /dmo/t_booking_inx( ( booking_id = <booking>-
bookingid
action_code = /dmo/
if_flight_legacy=>action_code-delete ) )
IMPORTING
map_messages(
EXPORTING
cid = <booking>-%cid_ref
travel_id = <booking>-travelid
booking_id = <booking>-bookingid
messages = messages
CHANGING
ENDLOOP.

ENDMETHOD.
Defining and Implementing the READ operation for Booking Instances
The READ operation is not specified in the behavior definition. To complete the BO, it is expected that the READ
for all entities is available to consume the BO via EML.
 Note
If you use groups in your behavior definition, you must explicitly specify the READ operation in one of the
groups. For more information, see Using Groups in Large Development Projects [page 212].
In the handler class for booking entities add the declaration of the method read_booking FOR READ with
importing parameter keys and the result parameter result.

558 PUBLIC Develop
For more information, see <method> FOR READ [page 145].
The implementation steps for reading booking entities are similar to those for reading travel entities, see
Implementing the READ Operation for Travel Data [page 531]. The same function module is used. It reads the
booking instances based on the travel ID that is passed to the function module. For performance reasons,
we only call the function module once for all bookings with the same travel ID. That is why, the loop at the
importing parameter is grouped by the travel ID. As the function module retrieves all available bookings for the
travel ID, the output table must be read for the bookings that match the importing parameter keys. The read
results are then be passed to the result parameter result for those fields that are requested by the consumer.
The key values are always passed to the result.
The error handling is separated for booking IDs that are not found for the respective travel IDs, for travel IDs
that are not found by the function module, and for other fail causes that cannot be specified.
 Expand the following code sample to view the source codeof the method read.
 Sample Code
**********************************************************************

*
*
**********************************************************************
PRIVATE SECTION.
...
IMPORTING keys FOR READ booking RESULT result.
ENDCLASS.
**********************************************************************
* Implements the READ operation for a set of booking instances
**********************************************************************
METHOD read.
bookings_out TYPE /dmo/t_booking,
"Only one function call for each requested travelid
LOOP AT keys ASSIGNING FIELD-SYMBOL(<booking_by_travel>)
GROUP BY <booking_by_travel>-travelid .
EXPORTING
iv_travel_id = <booking_by_travel>-travelid
IMPORTING
et_booking = bookings_out
map_messages(
EXPORTING
travel_id = <booking_by_travel>-travelid
booking_id = <booking_by_travel>-bookingid
messages = messages
IMPORTING
CHANGING
"For each travelID find the requested bookings
LOOP AT GROUP <booking_by_travel> ASSIGNING FIELD-SYMBOL(<booking>)
GROUP BY <booking>-%tky.
READ TABLE bookings_out INTO DATA(booking_out) WITH KEY travel_id
= <booking>-%key-TravelID

Develop PUBLIC 559
booking_id
= <booking>-%key-BookingID .
"if read was successful
IF sy-subrc = 0.
INSERT CORRESPONDING #( booking_out MAPPING TO ENTITY ) INTO
TABLE result.
ELSE.
"BookingID not found
INSERT VALUE #( travelid = <booking>-TravelID
bookingid = <booking>-BookingID
%fail-cause = if_abap_behv=>cause-not_found )
INTO TABLE failed-booking.
ENDIF.
ENDLOOP.
ENDIF.
ENDLOOP.

ENDMETHOD.
Defining and Implementing the READ Operation for the Associated Travel Instance
The read-by-association from booking instances to their parent travel instance is used to read the ETag master
of the booking instances. That is why, it is essential to support complete ETag handling for the travel BO. In
addition, the read-by-association must be implemented to complete the transactional handling for the BO, so
that it is consumable via EML.
In order to use the association transactionally, in this case, via a transactional read, the association must be
specified in the behavior definition for the booking instance:

{
...
...

}
In the handler class for booking entities, add the declaration of the method rba_travel FOR READ
booking\_travel with importing parameter keys_rba, and result_requested for full consumption and
declare, RESULT result and LINK association_links as changing parameters.
For more information, see <method> FOR READ By Association [page 147].
In the implementation for reading travel instances by association from booking entities, loop at the incoming
booking and group by the incoming TravelID. This grouping optimizes the performance as the function call
is only executed once for each travel ID. If the function call to read the associated travel instance is successful,
group at the group <travel> to fill the link table for each requested booking. If all fields of the travel instance
are requested, fill the result parameter result with the values that are read by the function module. To ensure
that only those fields are filled that were requested (indicated by the %control structure of the importing
parameter), the corresponding operator with the addition MAPPING TO ENTITY is used.
To avoid duplicate result keys, delete duplicates from the link table and result.
If the function modules returns messages, fill the failed table with the corresponding entries. The error
handling is separated for booking IDs that are not found for the respective travel IDs, for travel IDs that are not
found by the function module, and for other fail causes that cannot be specified.
 Expand the following code sample to view the source codeof the method rba_travel.

560 PUBLIC Develop
 Sample Code
**********************************************************************

*
*
**********************************************************************
PRIVATE SECTION.
...
METHODS rba_Travel FOR READ
IMPORTING keys_rba FOR READ booking\_Travel FULL result_requested
ENDCLASS.
...
**********************************************************************
*
* Read travel by association
*
**********************************************************************
METHOD rba_Travel.
DATA: travel TYPE /dmo/travel,
"Only one function call for each requested travelid
LOOP AT keys_rba ASSIGNING FIELD-SYMBOL(<booking_by_travel>)
GROUP BY <booking_by_travel>-travelid .
EXPORTING
iv_travel_id = <booking_by_travel>-travelid
IMPORTING
es_travel = travel
map_messages(
EXPORTING
travel_id = <booking_by_travel>-travelid
booking_id = <booking_by_travel>-bookingid
messages = messages
IMPORTING
CHANGING
LOOP AT keys_rba ASSIGNING FIELD-SYMBOL(<travel>) USING KEY entity
WHERE TravelID = <booking_by_travel>-TravelID.
INSERT VALUE #(
source-%tky = <travel>-%tky
target-travelid = <travel>-TravelID
) INTO TABLE association_links.
IF result_requested = abap_true.
APPEND CORRESPONDING #( travel MAPPING TO ENTITY ) TO result.
ENDIF.
ENDLOOP.
ENDIF.
ENDLOOP.
SORT association_links BY source ASCENDING.
DELETE ADJACENT DUPLICATES FROM association_links COMPARING ALL FIELDS.
SORT result BY %tky ASCENDING.
DELETE ADJACENT DUPLICATES FROM result COMPARING ALL FIELDS.

ENDMETHOD.

Develop PUBLIC 561
Checking Results
At this point, you have the opportunity to check how the resulting app works for the CREATE and the
UPDATE. For this to happen, however, a suitable business service for UI consumption must first be defined
and published.
For more information, see: Defining Business Service for Fiori UI [page 563]
The READ cannot be easily tested using a Fiori UI, as there is no direct execution trigger for reading the data
from the application buffer. Nevertheless, you can test your READ implementation by using EML.
 Example
READ ENTITY /dmo/i_booking_U

FIELDS ( TravelID
BookingID
CustomerID
BookingDate )
WITH VALUE #( ( %key = VALUE #( TravelID = travelid
BookingID = bookingid ) ) )
RESULT DATA(read_result_travels)

FAILED DATA(failed_rba).
To retrieve the complete entity instance for the respective travel ID, you have to set every element explicitly.
For more information about EML, see Examples for Accessing Business Objects with EML [page 240].
4.2.3.3.3 Projecting the Behavior
You project the behavior to define the behavior for the specific business service.
Whereas the general business object defines and implements the behavior of what can be done in general
with the data provided by the data model, the BO projection defines only the behavior that is relevant for the
specific service. In this travel scenario, the BO projection does not define a specific role of the end user, but
projects the entire behavior for the UI service.
In the behavior projection, you only define the behavior that is relevant for the specific service. The
implementation of the individual characteristics is only done in the general BO. The projection behavior
definition delegates to the underlying layer for the behavior that is defined in the projection layer.
For more information, see Business Object Projection [page 198].
Creating the Projection Behavior Definition for the Travel BO
To create a projection behavior definition, do the following:
1. Open the context menu of the root projection view /DMO/C_Travel_U.

2. Choose New Behavior Definition.
3. In the wizard to create a new behavior definition, choose the implementation type Projection to get the
template for projection.

562 PUBLIC Develop
A new projection behavior definition is created that defines the behavior for the specific UI service. The
behavior definition uses the same name as the root projection view.
For the UI service, the entire behavior that is defined in the underlying BO is exposed. This includes:
• the etag to prevent overwriting on simultaneous editing

• the standard operations create, update, delete for the root entity,
• the standard operations update and delete for the child entity,
• the operation create by association for the child entity,
• the action set_status_booked on the root entity.
The following listing displays the source code of the projection behavior definition.
Listing 1: Source Code of the Projection Behavior Definition /DMO/C_Travel_U
projection;

strict;
define behavior for /DMO/C_Travel_U alias travel
use etag
{
use create;
use update;
use delete;
use action set_status_booked;
}
define behavior for /DMO/C_Booking_U alias booking
use etag
{
use update;
use delete;
use association _Travel;
}
define behavior for /DMO/C_BookingSupplement_U alias bookingsupplement
use etag
{
use update;
use delete;
use association _Booking;

}
For more information, see Projection Behavior Definition [page 203].
4.2.3.4 Defining Business Service for Fiori UI
This section explains how you can model an OData service based on the data model and the related behavior
model. A service like this consists of two artifacts, a service definition and a service binding.
The service definition is a projection of the data model and the related behavior to be exposed, whereas the
service binding implements a specific protocol and the kind of service offered to a consumer.
Further information: Business Service [page 196]

Develop PUBLIC 563
Steps Relevant to Developers
1. Create the service definition

2. Specify which CDS entities are exposed as a UI service
3. Create a service binding
4. Publish the UI service locally
5. [Optional] Run the resulting app
4.2.3.4.1 Exposing the Relevant CDS Views as a Service
To describe the consumer-specific perspective as a data model, you need to create a business service
definition (service definition for short) as an ABAP Repository object. A service definition represents the
service model that is derived from the underlying CDS-based data model.
Further information: Service Definition [page 204]
Create and Define the Service Definition
Create a service definition, as described in .
Add all relevant data model artifacts tot be exposed by the service.
 Expand the following code sample to view the source code of the service definition /DMO/TRAVEL_U.
 Sample Code

@EndUserText.label: 'Service Definition for Managing Travels'
@ObjectModel.leadingEntity.name: '/DMO/I_Travel_U'
define service /DMO/TRAVEL_U {
expose /DMO/C_Travel_U as Travel;
expose /DMO/C_Booking_U as Booking;
expose /DMO/C_BookingSupplement_U as BookingSupplement;
expose /DMO/I_Supplement as Supplement;
expose /DMO/I_SupplementText as SupplementText;
expose /DMO/I_Carrier as Airline;
expose /DMO/I_Connection as FlightConnection;
expose /DMO/I_Flight as Flight;
expose /DMO/I_Airport as Airport;
expose /DMO/I_Travel_Status_VH as TravelStatusVH;

}
The entire source code of a service definition for managing travels is included within the single bracket
{ ... }. It groups all the related CDS entities which are to be exposed as part of the UI service - including
their compositions and associations with the relevant entities. Note that the value help provider or text provider
views must also be exposed for the OData service to make use of the value help and text associations.

564 PUBLIC Develop
Further information: Syntax for Defining a Service [page 205]
4.2.3.4.2 Creating a Service Binding
Using the business service binding (service binding for short), you can bind a service definition to a client-
server communication protocol.
Further information: Service Binding [page 207] (Concept Information)
Procedure: Creating a Service Binding
To launch the wizard tool for creating a service binding, do the following:

2. In your ABAP project (or ABAP Cloud Project), select the relevant package node in Project Explorer.
3. Open the context menu and choose New Service Binding to launch the creation wizard.
Creating a Service Binding – Wizard

Develop PUBLIC 565
Procedure: Activating the New Service
After successful activation, the editor provides additional information about the entire entity set as well as
about the navigation path of the respective entity.
Service Binding Editor
[Optional] Procedure: Running the Resulting UI Service
As soon as the service is activated, it is ready for consumption through an OData client such as an SAP Fiori
app.
In the course of the UI development in the SAP Web IDE, you have the option of testing the resulting app within
the SAP Fiori launchpad environment.
 Tip
Alternatively, you can use the preview function in the service binding to check how the UI of a Fiori
application looks like. More on this: Previewing the Resulting UI Service [page 330]

566 PUBLIC Develop
4.2.3.5 Adding Another Layer to the Transactional Data
Model
In this section, you get a brief overview on how you can proceed when going to add a further layer to the flight
demo scenario. Specifically, a booking supplement entity is now to be added to the previous 2-tier layer of the
travel business object.

consists of the following editable entities, with a 1: n cardinality on each level:
• Travel
• Booking
That is, each travel instance has 0..n bookings and each booking has 0..n booking supplements.
Additional Entities for Master Data

To populate the booking supplement instances with business data, you also need to extend the data model for
master data by the following entities:
• Supplement
• SupplementText

Develop PUBLIC 567
Data Model for 3-tier Entity Hierarchy
 Note
With the knowledge so far, you can easily reproduce the concrete steps of this extension. Therefore, in this
topic, we will only outline the implementation steps in a nutshell and refer to the full implementation as it is
available in the demo ABAP package /DMO/FLIGHT/UNMANAGED.

568 PUBLIC Develop
1. Extending the Data Model
Adding the CDS Entities to Extend the Data Model

Extended Data Model
BookingSupplement This entity is used to add additional products to a travel booking. The booking Yes
supplement data is stored in the database table /DMO/BOOK_SUPPL. The flight
data model defines an n:1 cardinality between a Booking Supplement
entity and a Booking entity.
Supplement A Supplement entity defines product data that the customer can book to- No
gether with a flight, for example a drink or a meal.
The supplement data is stored in the database table /DMO/SUPPLEMENT. The

flight data model defines a 1:1 cardinality between a Supplement entity and
the Booking Supplement entity.
This entity mainly serves a text provider for the associated elements in the target NO
SupplementText
entity BookingSupplement. By using a text association, you define the rela-
tionship between an element of the target entity and its corresponding texts or
descriptions.
More on this: Getting Text Through Text Associations [page 893]
The BookingSupplement entity is part of the compositional hierarchy of the travel business object. This
composition relationship requires an association to their compositional parent entity. This relationship
is expressed by the keyword ASSOCIATION TO PARENT. Using this syntax, you define the CDS entity
BookingSupplement as a sub node in the compositional hierarchy of the travel business object structure.
For etag and lock master handling, the entity contains the association _Travel to the root entity. To access
master data from other entities, additional associations _Product and _SupplementText are defined in the
CDS source code. The associated views are primarily used as a text view for retrieving text information and as
value help provider for specific product fields.
 Expand the following code sample to view the source code of the CDS View /DMO/I_BookingSupplement_U.
 Sample Code

@EndUserText.label: 'Booking Supplement view - CDS data model'
define view entity /DMO/I_BookingSupplement_U
as select from /dmo/book_suppl as BookingSupplement
association to parent /DMO/I_Booking_U as _Booking on
$projection.TravelID = _Booking.TravelID
and
$projection.BookingID = _Booking.BookingID
association [1..1] to /DMO/I_Travel_U as _Travel on
$projection.TravelID =
_Travel.TravelID

$projection.SupplementID = _Product.SupplementID
$projection.SupplementID = _SupplementText.SupplementID
{

Develop PUBLIC 569
key BookingSupplement.travel_id as TravelID,
key BookingSupplement.booking_id as BookingID,
key BookingSupplement.booking_supplement_id as BookingSupplementID,
BookingSupplement.supplement_id as SupplementID,
BookingSupplement.price as Price,
BookingSupplement.currency_code as CurrencyCode,
// _Booking.LastChangedAt as LastChangedAt,
/* Associations */
_Booking,
_Travel,
_Product,
_SupplementText
}

Since the BookingSupplement entity is part of the compositional hierarchy of the business object, it is
projected in a projection view. In the projection view, the text relationships, the search and value helps are
defined via CDS annotations. In addition, the associations to parent and root must be redirected respectively.
 Expand the following code sample to view the source code CDS Projection View /DMO/
C_BookingSupplement_U.
 Sample Code
@EndUserText.label: 'Booking Supplement Projection View'

define view entity /DMO/C_BookingSupplement_U
as projection on /DMO/I_BookingSupplement_U
{ ///DMO/I_BookingSupplement_U
key TravelID,
key BookingID,
key BookingSupplementID,
@Consumption.valueHelpDefinition: [ {entity: { name: '/DMO/
I_SUPPLEMENT',
element:
'SupplementID' },
additionalBinding:
[ { localElement: 'Price', element: 'Price'},

@ObjectModel.text.element: ['SupplementText']
SupplementID,
_SupplementText.Description as SupplementText : localized,
Price,
@Consumption.valueHelpDefinition: [ { entity: { name: 'I_Currency',
element:
'Currency' } } ]
CurrencyCode,
// LastChangedAt,
/* Associations */
///DMO/I_BookingSupplement_U
_Booking : redirected to parent /DMO/C_Booking_U,
_Travel : redirected to /DMO/C_Travel_U ,
_Product,
_SupplementText
}


570 PUBLIC Develop
The BookingSupplement Entity also has a representation in the UI. It must therefore be equipped with UI
annotations, which are outsourced to metadata extension as done with the other BO entities.
 Expand the following code sample to view the source code of the Metadata Extension /DMO/
C_BookingSupplement_U.
 Sample Code

title: { type: #STANDARD, label: 'Booking Supplement',
annotate view /DMO/C_BookingSupplement_U with
{
purpose: #STANDARD,
position: 10 } ,
{ id: 'PriceHeader',
type: #DATAPOINT_REFERENCE,
purpose: #HEADER,
targetQualifier: 'Price',
label: 'Price',
position: 20 } ]

BookingSupplementID;

SupplementID;
dataPoint: { title: 'Price' }
}
Price;

}
 Note
To complete the compositional hierarchy of the business object, you need to add the composition to
child in the Booking entity /DMO/I_Booking_U, as well as the redirected composition in the projection
view /DMO/C_Booking_U.
In order to display and change booking supplement data on Fiori UI, you must add the corresponding UI
facet in the booking metadata extension /DMO/C_Booking_U.
Adding a CDS View for Supplements

Listing 4 (below) provides you with a data definition for additional products that a customer can book together
with a flight booking.
Listing 4: CDS View /DMO/I_Supplement

@EndUserText.label: 'supplement view - cds data model'

Develop PUBLIC 571
define root view entity /DMO/I_Supplement
as select from /dmo/supplement as supplement
composition [0..*] of /DMO/I_SupplementText as _SupplementText
association [0..1] to /DMO/I_SupplementCategory_VH as _SupplementCategory on
$projection.SupplementCategory = _SupplementCategory.SupplementCategory
{
key supplement.supplement_id as SupplementID,
supplement.supplement_category as SupplementCategory,
@Semantics.amount.currencyCode: 'currencycode'
supplement.price as Price,
supplement.currency_code as CurrencyCode,
supplement.local_created_by as LocalCreatedBy,
supplement.local_created_at as LocalCreatedAt,
supplement.local_last_changed_by as LocalLastChangedBy,
//local etag field --> odata etag
supplement.local_last_changed_at as LocalLastChangedAt,
//total etag field
@Semantics.systemDateTime.lastChangedAt: true
supplement.last_changed_at as LastChangedAt,
/* associations */
_SupplementText,
_SupplementCategory,
_Currency
}

Adding a Text Provider View for Supplements
Listing 5 (below) provides you with a data definition that serves as text provider. It provides text data through
text associations as defined in the booking supplement view .
 Expand the following code sample to view the source code of Action ReCalCTotalPrice.
 Sample Code

@EndUserText.label: 'Supplement View - CDS Data Model'
define view entity /DMO/I_Supplement
as select from /dmo/supplement as Supplement
association [0..*] to /DMO/I_SupplementText as _SupplText on
$projection.SupplementID = _SupplText.SupplementID
{
@ObjectModel.text.association: '_SupplText'
key Supplement.supplement_id as SupplementID,
Supplement.price as Price,
Supplement.currency_code as CurrencyCode,
/* Associations */
_SupplText,
_Currency
}


572 PUBLIC Develop
2. Extending the Behavior Definition for the BookingSupplement Entity
The fact that in our scenario new instances of the booking supplement entity can only be created for a
specific travel and booking instance is considered by the addition of the _BookSupplement association. The
keyword {create;} declares that this association is create-enabled what exactly means that instances of the
associated booking supplements can be created by an individual booking instance.
The sub node of travel business object refers to the corresponding data model for booking supplements
that is represented by the child entity for /DMO/I_BookingSupplement_U. The transactional behavior of
the booking supplement sub node is determined by the standard operations create, update, and delete.
In addition, since we use different CDS view field names than in the database table, we need a mapping
specification from CDS names to database fields names.
Extended Behavior Definition /DMO/I_TRAVEL_U
 Expand the following code sample to view the source code of Extending the Behavior Definition /DMO/
I_TRAVEL_U.
 Sample Code

{...
}
{
...
}
define behavior for /DMO/I_BOOKINGSUPPLEMENT_U alias bookingsupplement
implementation in class /DMO/BP_BOOKINGSUPPLEMENT_U unique
{
field (read only) TravelID, BookingID, BookingSupplementID;
field (mandatory) SupplementID, Price;
create;
update;
delete;
mapping for /dmo/book_suppl control /dmo/s_booking_supplement_intx
{
BookingSupplementID = booking_supplement_id;
Price = price;
SupplementID = supplement_id;
}

}

Develop PUBLIC 573
3. Creating and Implementing the Behavior Pool for BookingSupplement
Creating a Behavior Pool for BookingSupplement Entity

Behavior Pool for BookingSupplement Child Entity

CLASS /dmo/bp_bookingsupplement_u DEFINITION
PUBLIC
ABSTRACT
FINAL
FOR BEHAVIOR OF /dmo/i_travel_u.
PUBLIC SECTION.
PROTECTED SECTION.
PRIVATE SECTION.
ENDCLASS.
CLASS /dmo/bp_bookingsupplement_u IMPLEMENTATION.

ENDCLASS.
Implementing the Handler for UPDATE, DELETE, READ and READ BY ASSOCIATION
You will find the same basic structure when implementing the handler methods for update and delete:
• A loop on booking supplement instances to be updated or deleted.

• Call of the business logic function module.
• Error handling for processing messages in case of failure.
Updating data of booking supplements in lhc_supplement

CLASS lhc_supplement DEFINITION INHERITING FROM cl_abap_behavior_handler.
PRIVATE SECTION.
TYPES:
tt_bookingsupplement_update TYPE TABLE FOR UPDATE /dmo/
update FOR MODIFY
IMPORTING entities FOR UPDATE bookingsupplement,
...
ENDCLASS.
CLASS lhc_supplement IMPLEMENTATION.
METHOD update.
...
ENDMETHOD.

ENDCLASS.
Deleting booking supplements in lhc_supplement

PRIVATE SECTION.
...
delete FOR MODIFY
IMPORTING entities FOR DELETE bookingsupplement,
ENDCLASS.
...
METHOD delete.
...
ENDMETHOD.

ENDCLASS.
Listing 10: Reading booking supplements in lhc_supplement

PRIVATE SECTION.

574 PUBLIC Develop
...
METHODS:
read FOR READ
IMPORTING keys FOR READ bookingsupplement
RESULT result,
ENDCLASS.
...
METHOD read.
...
ENDMETHOD.

ENDCLASS.
Listing 11: Reading travel by association in lhc_supplement

PRIVATE SECTION.
...
METHODS:
rba_travel FOR READ
IMPORTING keys_rba FOR READ bookingsupplement\_travel FULL
result_requested
ENDCLASS.
...
METHOD rba_travel.
...
ENDMETHOD.
ENDCLASS.

Implementing the CREATE Handler for Associated Booking Supplements

In our demo scenario, we assume that new booking supplements cannot be created separately but only in
conjunction with a given booking that, in turn, belongs to an individual travel instance.
To identify the associated booking supplements, the aliases for the parent entity and the child entity are used
- according to the aliases specified in the behavior definition. The association is expressed in the signature of
the implementing method cba_supplement of the booking behavior pool /DMO/BP_BOOKING_U in the form: …
FOR CREATE parent\_child_entity.
Listing 12: Creating booking supplements in the cba_supplement method

PRIVATE SECTION.
METHODS:
cba_booksupplement FOR MODIFY
IMPORTING entities FOR CREATE booking\_booksupplement,
...
ENDCLASS.
...
METHOD cba_booksupplement
...
ENDMETHOD.
ENDCLASS.


Develop PUBLIC 575
Preview – Object Page when Creating Booking Supplements
Preview - Saved Data Displayed in the List of Items
Implementing the READ for Associated Booking Supplements
To complete the BO, you must implement a READ operation for associated bookings. The READ by
association is implicitly defined in the behavior definition in the behavior for bookings by the definition
of CREATE by association:

{
...

}
The declaration and the implementation of the method to read booking supplements by association is done
in the handler class for bookings /DMO/BP_BOOKING_U in the same manner as in Implementing the READ
Operation for Associated Bookings [page 541]:
• Group the imported booking keys by travel ID

576 PUBLIC Develop
• Call the function module /DMO/FLIGHT_TRAVEL_READ
• Filter for the requested booking keys
• Fill the link table with the respective source and target keys
• Fill the result parameter, if the full parameter is set
• Handle errors
Listing 13: Read booking supplements in the read_supplement_ba method

PRIVATE SECTION.
METHODS:
rba_booksupplement FOR READ
IMPORTING keys_rba FOR READ booking\_booksupplement FULL
result_requested
...
ENDCLASS.
...
METHOD rba_booksupplement
...
ENDMETHOD.
ENDCLASS.

The READ by association can be tested by using EML.
4. Projecting the Behavior for the Booking Supplement Entity
As described in Projecting the Behavior [page 562], the behavior of the travel BO must be projected in the
projection behavior definition /DMO/C_Travel_U.
The behavior that is relevant for the booking supplement entity is
• the standard operation update and delete on the behavior node /DMO/C_BookingSupplement_U and
• the create-by-association operation for booking supplements on the behavior node /DMO/C_Booking_U.
 Expand the following code sample to view the source code of Projection Behavior Definition /DMO/
C_Travel_U.
 Sample Code
projection;

define behavior for /DMO/C_Travel_U alias travel
use etag
{
use create;
use update;
use delete;
use action set_status_booked;
}
define behavior for /DMO/C_Booking_U alias booking
use etag
{
use update;
use delete;

Develop PUBLIC 577
}
define behavior for /DMO/C_BookingSupplement_U alias bookingsupplement
use etag
{
use update;
use delete;

}
5. Exposing New Entities in the Service Definition
Corresponding to the listing below, the following CDS entities are to be exposed with the UI service:
Listing 12: Added Entities in the Service Definition

define service /DMO/TRAVEL_U {
...
expose /DMO/C_BookingSupplement_U as BookingSupplement;
...
}

4.2.4 Developing Transactional Apps with Draft Capabilities
This chapter is a walk-through tutorial that guides you through the main implementation steps to develop an
application with draft support. Draft-enabled applications provide the end user with the highest flexibility when
working with the app.
From a technical perspective, the outcome of these chapters is a business service that is developed based
on the implementation type managed with draft of the ABAP RESTful Application Programming Model using
UUID keys. For more information about draft business objects, see Draft [page 46]. The business object (BO)
is exposed as a UI service. In this example scenario, the Fiori Elements App Preview is used to illustrate the
examples. Yet, the same business object can also be consumed as a Web API.
Introduction
The standard use case for creating a managed transactional app with draft capabilities is the following:
You want to create a completely new transactional app for a Fiori Elements UI following the greenfield
approach. That means, there is no legacy business application logic involved. You create everything from
scratch. Following from that, you can benefit from the lightweight BO standard implementation of the managed
implementation type, in which the RAP managed runtime framework assumes an extensive part of the
standard implementation with out-of-the-box support for create, update, and delete. In addition, you may
need to provide the end user with capabilities to store changed data in the backend at any time and proceed
at a later point in time, or to recover such data from a different device, even if the application client has
terminated unexpectedly. This use case is supported by the draft concept of the ABAP RESTful Application

578 PUBLIC Develop
Programming Model. Draft-enabled business objects persist the state of the transactional buffer after every
transaction on a designated draft database table. This allows the end user to stop and continue work processes
at any point in time, even with inconsistent data. For more detailed information about the draft concept, see
Draft [page 46].
The example scenario uses a data model with UUID-key layout. In managed scenarios, UUIDs are beneficial as
they can be drawn automatically by the RAP managed framework upon creating new instances. However, the
draft scenario can also be developed with semantic primary keys.
Prerequisites

 Restriction
Development Flow
The example development scenario is designed to support two approaches. On the one hand, it teaches you
how to build a managed business object with draft from scratch. On the other hand, if you just want to add
draft capabilities to your existing BO, you can leave out the first steps to create a managed business object and
start directly with Draft-Enabling the Managed Business Object [page 668].
The development of an application with draft capabilities based on a managed business object requires the
following activities:
1. Providing the CDS Data Model based on UUID keys

The first chapter provides you with information on how to create suitable database tables and CDS view
entities for the managed business object. The example scenario guides you to build a three-node business
object, which illustrates how root and child entities are handled in the draft scenario.
See Data Model and Business Object Structure [page 581].
2. Developing Transactional Behavior for the Managed Business Object
In this section, you will equip the data model with transactional behavior. The business object framework
for managed implementation type provides you with out-of-the-box support for standard implementation
tasks. Other business-specific logic must be implemented using actions, determinations, and validations.
See Developing Transactional Behavior [page 590].

Develop PUBLIC 579
3. Exposing the Managed Business Object for a UI service
Consuming the managed business object via a UI requires defining the projection layer, where you define
all service-specific features, like UI annotations for UI configuration, search capabilities or value helps. The
projected BO and all its related entities must then be defined in the service definition and then bound
to a protocol. This UI service remains stable even when you add draft capabilities later on. Whereas the
underlying BO changes, the BO projection filters only the non-draft features. The steps will be explained in
this section.
See Exposing the Managed Business Object for a UI Business Service [page 657].
4. Adding Draft Capabilities to the Managed Business Object
This section explains how you draft-enable the existing business object. On the one hand, draft-enabling
requires the revision of all existing business logic. Sometimes the BO provider needs to distinguish if draft
instances or active instances are processed. On the other hand, there are some draft features that you
need to implement to add draft qualities to the business service.
See Draft-Enabling the Managed Business Object [page 668].
5. Exposing the Draft-Enabled Business Object for a UI service
To enable the consumption of the draft-enabled BO via a Fiori Elements UI, the projection layer must be
defined. It reuses all the draft capabilities that are defined in the underlying layer. In addition, the service
must be defined and bound to a protocol.
See Exposing the Draft Business Object for a UI Business Service [page 681].
4.2.4.1 Building a Managed Business Object with UUID

Keys
The first part of the managed development scenario with draft describes setting up a managed business object
from scratch.
The assumption in this scenario is that you do not have any data or legacy coding that you want to include in
the new business object. Everything is created from scratch. Therefore the first step is to create database table
to store the data that the business object consumes. We use a simplified approach to have one database table
for each business object entity. In real-world scenario, this might rarely be the case, but this demo scenario
mainly demonstrates how you handle the transactional behavior with draft for the business object and does
not focus on database structures for business objects.
The key structure of the data model in this scenario is based on UUID keys. That means, every BO entity
instance is uniquely identifiable by one single unique key.
Based on these database tables, the data model and structure for the business object is defined via CDS view
entities. For more information about the basic structure of a business object, see Data Modeling and Behavior
[page 12].
In a second step, the second component of a business object, the behavior, is defined and implemented for the
business object. For more information about the business object behavior, see Business Object [page 15]
1. Data Model and Business Object Structure [page 581]

2. Developing Transactional Behavior [page 590]

580 PUBLIC Develop
4.2.4.1.1 Data Model and Business Object Structure
The draft scenario uses the same data model as the other development scenarios. The final app processes
travel data, primarily flight data, to create, update, and delete travel instances.
The travel business object consists of three entities that are structured in a hierarchy tree. Every entity in the
BO-composition tree is modeled with a CDS view entity. The following entities are used for the transactional
data model:
• Travel: The root entity comprises general travel data, like a trip's start and end dates, and the relevant
customer and agency data.
• Booking: The booking entity depicts which bookings are relevant for a certain travel. In the current data
model, only flights are available as bookings.
• BookingSupplement: The booking supplement entity presents additional bookable supplement for a
certain booking. These are meals and beverages for the flights.
The BO-entities are related to each other in a composition structure. They maintain a dependency relationship,
which means that a child entity cannot exist without its parent entity. In addition, a parent entity can have one
to many child entities. The following diagram illustrates this relationship.
Editable Entities of the Business Object
The root entity is the head of the business object. You address a BO with the name of the root entity. It is also
the root entity that receives special capabilities during runtime. In managed scenarios, only root entities can
be lock masters. That means, if one of the entities that are part of the composition tree is requested for lock,
it is the lock master instance and its child instances that are locked for the request. In addition, in the draft
scenario, the lock master, in this case the root entity, receives an additional field for optimistic concurrency
control in the transition from draft to active data. This field is called total ETag. For more information about
the locking mechanism and the total ETag, see Concurrency Control [page 33].
The composition tree includes child entities that are also part of the business object. They are connected via
compositions, bidirectional connections by which the relationship to the root entity is defined.

Develop PUBLIC 581
Whereas the BO-entities are built up from scratch, as you create both, the database table and the related CDS
entity, there are additional entities for master data that are reused from the demo content of the ABAP Flight
Reference Scenario. These entities are not part of the transactional BO-structure. Most of these entities are
used primarily as value help provider views for individual input fields on the UI.
Additional entities for currencies and countries are generally available in your system and are included in out
data model using associations. These are I_Currency and I_Country.
Tasks for the Developer
1. Creating Persistent Database Tables [page 582]

2. Creating CDS View Entities [page 585]
4.2.4.1.1.1 Creating Persistent Database Tables
For the managed scenario with draft, create new database tables for the business object data model that
match the transactional data structure of travel, booking and booking supplement.
In scenarios without existing legacy code, the first step is to create persistent database tables that store data.
Create these tables by using the creation wizard for creating database tables in ADT. For a detailed step-by-step
description, see .

582 PUBLIC Develop
 Note
The draft scenario in the ABAP Flight Reference Scenario uses the suffix _D. For the persistent database
tables, we use the prefix A_ to indicate the active persistence. For detailed information, see Naming
Conventions for Development Objects [page 306].
When creating database tables for a managed business object with draft that use UUID key layout, the
following considerations are relevant:
• The RAP managed runtime engine requires administrative data fields for internal processing of the
BO entities. Especially, a field that denotes the timestamp when the instance was last changed
is important for the ETag master handling on each entity. The RAP framework offers reuse data
elements to define administrative fields on the database, see RAP Reuse Data Elements [page
210]. If the administrative fields on local instances are annotated in CDS with the annotation
@Semantics.systemDateTime.localInstanceLastChangedAt: true, they are automatically filled
by the RAP managed runtime engine. For more information, see Optimistic Concurrency Control [page 33].
• In a UUID scenario, every entity needs a field for the UUID key. In addition, child entities must have a
field for their parent's UUID. Otherwise, you cannot define associations for the composition relationship. In
addition, any child entity that has no parent-child relationship with the lock master entity must have a field
with the lock master's UUID. Otherwise you cannot define associations to the lock master entity, which is
important for lock and ETag handling.
• Apart from the UUID key, each database table also has a semantic ID field. These fields are no technical
keys, but are used to semantically distinguish the entity instance in the business object.
Table /DMO/A_TRAVEL_D: Persistent Table for Managing Travel Data
This tables defines general travel data, data that describe the basic information of a trip, such as the travel ID,
customer and agency ID, and dates. Since this scenario is based on a UUID key layout, the table also entails
a field with a UUID data type. In addition, the fields for standard administration data, such as the respective
user or the time of creation are added to the table. In managed business objects, these fields can be filled
automatically by the RAP managed runtime framework if the corresponding @Semantics annotations are
added to the fields in the CDS view entity. Administrative fields, in particular the field that determines when
instance data is changed, are important for concurrency control.
 Expand the following code sample to view the source code of /DMO/A_TRAVEL_D.
 Sample Code
@EndUserText.label : 'Active Travel Persistence for Draft Reference Scenario'


define table /DMO/A_TRAVEL_D{

key travel_uuid : sysuuid_x16 not null;
@Semantics.amount.currencyCode : '/dmo/a_travel_d.currency_code'

Develop PUBLIC 583
@Semantics.amount.currencyCode : '/dmo/a_travel_d.currency_code'

}
Table /DMO/A_BOOKING_D: Persistent Table for Managing Booking Data
This table defines the booking data for a specific travel instance. It contains general booking data, such as
the booking ID, booking date, and general flight data. To identify a booking instance uniquely, the table must
contain a UUID field for the booking. In UUID scenarios, the parent UUID must be used as a foreign-key field in
the database for the child entity. For the ETag master handling, the booking database table receives a field to
store the timestamp when the instance was updated.
 Expand the following code sample to view the source code of /DMO/A_BOOKING_D.
 Sample Code
@EndUserText.label : 'Active Booking Persistence for Draft Reference Scenario'


define table /DMO/A_BOOKING_D{

key booking_uuid : sysuuid_x16 not null;
parent_uuid : sysuuid_x16;
booking_id : /dmo/booking_id not null;
booking_date : /dmo/booking_date;
carrier_id : /dmo/carrier_id;
connection_id : /dmo/connection_id;
flight_date : /dmo/flight_date;
@Semantics.amount.currencyCode : '/dmo/a_booking_d.currency_code'
flight_price : /dmo/flight_price;
booking_status : /dmo/booking_status;

}
Table /DMO/A_BKSUPPL_D: Persistent Table for Managing Booking Supplement

Data
This table defines the supplement for a specific booking instance. It contains general booking supplement
data, such as the booking supplement ID and price information. To identify a booking supplement instance

584 PUBLIC Develop
uniquely, the table must contain a UUID field for the booking supplement. In UUID scenarios, the parent UUID
and the lock master UUID (in our case the root UUID) must be used as a foreign-key field in the database. For
the ETag master handling, the booking supplement database table receives a field to store the timestamp when
the instance was updated.
 Expand the following code sample to view the source code of /DMO/A_BKSUPPL_D.
 Sample Code
@EndUserText.label : 'Active BookingSupplement Persistence for Draft Ref.

Scenario'


define table /DMO/A_BKSUPPL_D{

key booksuppl_uuid : sysuuid_x16 not null;
root_uuid : sysuuid_x16;
parent_uuid : sysuuid_x16;
booking_supplement_id : /dmo/booking_supplement_id not null;
supplement_id : /dmo/supplement_id;
@Semantics.amount.currencyCode : '/dmo/a_bksuppl_d.currency_code'
price : /dmo/supplement_price;

}
4.2.4.1.1.2 Creating CDS View Entities
For the managed scenario with draft, create data definitions for CDS view entities to build the structure for the
business object.
Previously, you have created persistent database table for the travel business object. The structure of the
managed business object must now be defined by CDS data modeling.
Create data definitions for CDS view entities that represent the three transactional entities of the business
object: Travel, Booking, and Booking Supplement.
 Note
CDS view entities are the successor DDIC-based CDS views. CDS view entities offer many advantages, such
as optimization and simplification of syntax checks, and improved performance during view activations.
In ADT, use the wizard for creating CDS data definitions. For a detailed step-by-step description, see .
Select the template Define Root View Entity for the travel entity.
Select the template Define View Entity with To-Parent Association for the booking and the booking supplement
entity.

Develop PUBLIC 585
 Note
The draft scenario in the ABAP Flight Reference Scenario uses the suffix _D.Since CDS view entities
are interface views, they are prefixed with R_ accordance with the VDM (virtual data model) naming
convention. For detailed information, see Naming Conventions for Development Objects [page 306].
When using CDS view entities for a managed business object with draft that use UUID key layout, the following
considerations are relevant:
• For a business object, you must define a root entity that represents the head of the business object and
provides the name with which the BO is addressed.
• The composition structure of the managed business object must be defined in the CDS view entities by
compositions to the child entity and associations to the parent entity. In addition, an association to the lock
and authorization master entity (in our scenario, the root entity) must be available from all entities in the
business object.
• The RAP managed runtime framework fills the administrative fields automatically if they are
annotated with the corresponding @Semantics annotation. These fields are only necessary
on the root entity of the business object. In particular, the field that is annotated with
@Semantics.systemDateTime.localInstanceLastChangedAt: true is updated whenever the
instance is changed. In our scenario, this field is used for ETag comparison.
Data Definition /DMO/R_Travel_D: Travel Root View
The data source for the travel root view is the database table /DMO/A_TRAVEL_D. All fields from the database
table are used for the data model.
To retrieve master data for value helps from other entities, define the association to the CDS entities /DMO/
I_Agency,/DMO/I_Customer, I_Currency, /DMO/I_Overall_Status_VH and I_Currency. The former
are part of the ABAP Flight Reference Scenario, which you can download. The CDS view I_Currency is
generally available in your development system.
Annotate the price fields with the annotations @Semantics.amount.currencyCode to define which field is
used as currency.
 Note
In contrast to DDIC-based CDS views, in CDS view entities, you do not need to specify the currency code
field as a currency code if the field is already specified in the database table.
Use semantics annotations for the administrative fields. The ETag field local_instance_last_changed_at
receives the annotation @Semantics.systemDateTime.localInstanceLastChangedAt: true.
As soon as the entity of the composition structure exists, define the compositional relationship to the child
entity /DMO/R_Booking_D with the keyword composition.
 Expand the following code sample to view the source code of /DMO/R_Travel_D.
 Sample Code
@EndUserText.label: 'Travel View Entity for Draft RefScen'

586 PUBLIC Develop


define root view entity /DMO/R_Travel_D

as select from /DMO/A_TRAVEL_D

composition [0..*] of /DMO/R_Booking_D as _Booking

$projection.AgencyID = _Agency.AgencyID


association [1..1] to /DMO/I_Overall_Status_VH as _OverallStatus on
$projection.OverallStatus = _OverallStatus.OverallStatus


{ ///DMO/A_TRAVEL_D

key travel_uuid as TravelUUID,
travel_id as TravelID,
local_created_by as LocalCreatedBy,
local_created_at as LocalCreatedAt,
local_last_changed_by as LocalLastChangedBy,
local_last_changed_at as LocalLastChangedAt,
//total ETag field
//Associations
_Booking,
_Agency,
_Customer,
_OverallStatus,
_Currency

}
Data Definition /DMO/R_Booking_D: Booking View
The data source for the booking view is the database table /DMO/A_BOOKING_D. All fields from the database
To retrieve master data for value helps from other entities, define the association to the CDS entities /DMO/
I_Customer, /DMO/I_Carrier, /DMO/I_Connection and /DMO/I_Booking_Status_VH. These CDS
views are part of the ABAP Flight Reference Scenario, which you can download.
used as currency.

Develop PUBLIC 587
 Note
In contrast to CDS views, in CDS view entities, you do not need to specify the currency code field as a
currency code if the field is already specified in the database table.
Use semantics annotations for the administrative field. The local

ETag field local_instance_last_changed_at receives the annotation
@Semantics.systemDateTime.localInstanceLastChangedAt: true.
As soon as the entities of the composition structure exist, define the compositional relationship to the
child entity /DMO/R_BookingSupplement_D with the keyword composition, and define the compositional
relationship to the parent entity /DMO/R_Travel_D with the keyword association to parent.
 Expand the following code sample to view the source code of /DMO/R_Booking_D.
 Sample Code
@EndUserText.label: 'Booking View Entity for Draft RefScen'


define view entity /DMO/R_Booking_D as select from /DMO/A_BOOKING_D

association to parent /DMO/R_Travel_D as _Travel on
$projection.TravelUUID = _Travel.TravelUUID

composition [0..*] of /DMO/R_BookingSupplement_D as _BookingSupplement




and

association [1..1] to /DMO/I_Booking_Status_VH as _BookingStatus on
$projection.BookingStatus = _BookingStatus.BookingStatus

{ ///DMO/A_BOOKING_D

key booking_uuid as BookingUUID,
parent_uuid as TravelUUID,
booking_id as BookingID,
carrier_id as AirlineID,
//Associations
_Travel,
_BookingSupplement,
_Customer,
_Carrier,
_Connection,
_BookingStatus

}

588 PUBLIC Develop
Data Definition /DMO/R_BookingSupplement_D: Booking Supplement View
The data source for the booking view is the database table /DMO/A_BKSUPPL_D. All fields from the database
To retrieve master data for value helps and texts from other entities, define the association to the CDS
entities /DMO/I_Supplement and /DMO/I_SupplementText. These CDS views are part of the ABAP Flight
Reference Scenario, which you can download.
used as currency.
 Note
In contrast to CDS views, in CDS view entities, you do not need to specify the currency code field as a
currency code if the field is already specified in the database table.
Use semantics annotations for the administrative field. The local

ETag field local_instance_last_changed_at receives the annotation
@Semantics.systemDateTime.localInstanceLastChangedAt: true.
As soon as the entities of the composition structure exist, define the compositional relationship to the
parent entity /DMO/R_Booking_D with the keyword association to parent, and define the compositional
relationship to the root entity /DMO/R_Travel_D.
 Expand the following code sample to view the source code of /DMO/R_BookingSupplement_D.
 Sample Code
@EndUserText.label: 'BookSuppl View Entity fro Draft RefScen'


define view entity /DMO/R_BookingSupplement_D

as select from /DMO/A_BKSUPPL_D

association to parent /DMO/R_Booking_D as _Booking on
$projection.BookingUUID = _Booking.BookingUUID

association [1..1] to /DMO/R_Travel_D as _Travel on
$projection.TravelUUID = _Travel.TravelUUID

$projection.SupplementID = _Product.SupplementID

$projection.SupplementID = _SupplementText.SupplementID

{ ///DMO/A_BKSUPPL_D

key booksuppl_uuid as BookSupplUUID,
root_uuid as TravelUUID,
parent_uuid as BookingUUID,
booking_supplement_id as BookingSupplementID,
price as BookSupplPrice,
//Associations
_Travel,
_Booking,
_Product,
_SupplementText

}

Develop PUBLIC 589
4.2.4.1.2 Developing Transactional Behavior
This topic describes the behavior that is used for the business object in the managed scenario with draft.
The managed business object comprises the following behavior. The keywords in brackets refer to the technical
features for this behavior.
1. Root Entity Travel:

1. You can create new instances of the travel entity.
On creating travel instances, the following behavior is implemented:
• The UUID key for new instances is automatically assigned (managed internal numbering).
• The travel UUID, the travel ID, the overall status, the total travel price, and administrative fields
can’t be provided by the consumer (read-only fields).
• The semantic travel ID is calculated (determination on save).
• The overall status for new travel instances is set to initial (determination on modify).
• The administrative fields are filled automatically (internal draft processing of the RAP runtime
framework).
• The total travel price is calculated based on the booking fee of new travels (determination on
modify, internal action).
• The customer ID, the agency ID, the begin and the end date must be provided on creating new
travel instances (mandatory fields).
• All modify operations are checked for authorization against the user profile (global authorization).
• The travel instance can only be modified depending on the country code of the agency that is used
for the respective travel. (instance authorization)
• The agency ID is checked for existence, validity, and authorization (validation on save).
• The customer ID is checked for existence and validity (validation on save).
• The travel dates are checked for consistency (validation on save).
2. You can update instances of the travel entity.
On updating travel instances, the following behavior is implemented:
• The travel ID, the overall status, the total travel price, and administrative fields cannot be modified
BO-externally (read-only fields).
• You can only update the booking fee if the overall status is not set to accepted ('A') (dynamic field
control).
• If the customer ID, the agency ID or the travel dates are changed, they are checked for existence
and consistency (validations on save).
• You can set the overall status to accepted ('A') by an action, if the travel does not already have this
status (dynamic action control).
• You can set the overall status to rejected ('X') by an action, if the travel does not already have this
status (dynamic action control).
• You can deduct a discount for the travel with a parameter action if the overall status is not already
accepted ('A') (action with parameter).
3. You can delete instances of the travel entity. Due to compositional relationship, all instances of child
entities are deleted as well.
2. Child Entity Booking
1. You can create new booking instances for travel instances.
On creating booking instances, the following behavior is implemented:

590 PUBLIC Develop
• The travel UUID, the booking ID, the booking date, and administrative fields cannot be provided by
the consumer (read-only fields).
• The semantic booking ID is calculated (determination on save).
• The booking date is set automatically (determination on save).
framework).
• The customer ID, the airline ID, the connection ID, and the flight date must be provided on creating
new booking instances (mandatory fields).
• The customer ID is checked for existence and validity (validation on save).
• The airline ID is checked for existence and compatibility with the connection ID and the flight date
(validation on save).
• The connection ID is checked for existence and compatibility with the airline ID and the flight date
(validation on save).
• The flight date is checked for compatibility with the airline ID and the connection ID (validation on
save).
2. You can update instances of the booking entity.
On updating booking instances, the following behavior is implemented:
• The booking UUID, travel UUID, the booking ID, the booking date, and administrative fields cannot
be modified BO-externally (read-only fields).
• If the customer ID, the airline ID, the connection ID, or the flight date are changed, they are
checked for existence and consistency (validations on save).
3. You can delete instances of the booking entity. Due to compositional relationship, all instances of the
child entity are deleted as well.
3. Child entity BookingSupplement
1. You can create new booking supplement instances for booking instances.
On creating booking supplement instances, the following behavior is implemented:
• The travel UUID, the booking UUID, the booking supplement UUID, the booking supplement ID, and
administrative fields cannot be provided by the consumer (read-only fields).
• The semantic booking supplement ID is calculated (determination on save).
framework).
• The supplement ID must be provided on creating new booking supplement instances (mandatory
field).
• The supplement ID is checked for existence and validity (validation on save).
2. You can update instances of the booking supplement entity.
On updating booking supplement instances, the following behavior is implemented:
• The travel UUID, the booking UUID, the booking supplement UUID, the booking supplement ID, and
administrative fields be modified BO-externally (read-only fields).
• If the supplement ID is changed, it is checked for existence and consistency (validation on save).
3. You can delete instances of the booking supplement entity.

Develop PUBLIC 591
4.2.4.1.2.1 Defining Standard Behavior
For the managed scenario with draft, create a behavior definition to define the behavior for the business object.
The behavior definition is the development object that defines the implementation type behavior for the
business object. When using the implementation type managed, for some features, you only need to define
behavior characteristics and standard operations in the behavior definition. The RAP managed runtime
framework provides a generic solution for
• strict mode
• create
• update
• delete
• create-by-association
• lock handling
• ETag handling.
For more information, see Defining Elementary Behavior for Ready-to-Run Business Object [page 390].
(/DMO/R_Travel_D), you can directly create a behavior definition for the travel data model. In the wizard,
choose the implementation Managed. For a detailed description, see .
For the demo scenario with a managed business object with draft, the following considerations are relevant.
• The behavior of each entity is implemented in a separate behavior class pool. Hence, the implementation
class must be created for each entity separately. For more information, see Best Practives for
Modularization and Performance [page 514].
• The managed implementation type requires the specification of lock master or lock dependent on
each entity. For more information, see Pessimistic Concurrency Control (Locking) [page 38].
• The strict mode ensures RAP best practices and up-to-date syntax for the behavior definition and
behavior implemenation. For conceptual background, see Strict Mode [page 184].
• It is recommended to use authorization control to protect your business object against unauthorized
access. Define authorization master or authorization dependent by _Assoc on each entity.
The authorization behavior must then be implemented in the corresponding methods in the behavior
pool. For conceptual background, see Authorization Control [page 80]. For detailed information about the
implemtation, see Developing Authorization [page 619].
• In managed business objects, it is best practice to define a local ETag master on each entity. With an ETag
master on every entity, you ensure that the ETag check is done for every entity independently. For more
information, see Optimistic Concurrency Control [page 33].
• The RAP managed runtime framework is able to automatically draw primary key values in UUID scenarios.
You use this functionality by defining early managed numbering in the behavior definition. Setting the
primary key field to read only defines strict internal numbering. An external BO consumer is not allowed
to provide the primary key values in this case. For more detailed information, see Automatically Drawing
Primary Key Values in Managed BOs [page 850].

592 PUBLIC Develop
• If different names are used on the database table and in the CDS data model, you need to define the
mapping for these fields. This is done via the mapping operator in the behavior definition.
Behavior Definition /DMO/R_Travel_D
The template for the managed implementation type provides the behavior definition for every entity
in the composition tree of the root entity. In addition, it specifies the data source of the respective
entities as persistent table. The behavior definition proposes to include the behavior characteristics
lock, authorization and etag. The standard operations create, update and delete, as well as the
association _Booking {create} are included in the template for each entity. The create operation in
child entities is not supported in RAP scenarios. Instances of child entities can only be created by create-by-
association operation.
Define the root entity as lock master. The current version of the ABAP RESTful Application Programming Model
only supports the specification of lock master on the root entity. Define the booking entity and the booking
supplement entity as lock dependent. Lock dependents require an association to the lock master entity. In
the CDS data model, you have specified the association to the travel entity _Travel. To use the association
for the lock dependent, define the association as transaction-enabled in the behavior definition. For more
information, see Lock Dependent [page 43].
As the TravelUUID is used for the lock dependent relationship, it must be set to readonly in the Booking
and BookingSupplement entity behavior.
Define the root entity as authorization master. The current version of the ABAP RESTful Application
Programming Model only supports the specification of authorization master on the root entity. Define the
booking entity and the booking supplement entity as authorization dependent. Just like lock dependents,
authorization dependents require an association to the authorization master entity. For more information, see
Authorization Dependent [page 84].
Define an ETag master field on each entity. Use the field LocalLastChangedAt that
is part of the entity's data model. Since this field is annotated with the annotation
@Semantics.systemDateTime.localInstanceLastChangedAt: true, it is updated automatically by the
RAP managed runtime framework.
Use early managed numbering for the primary key fields on every entity and set the fields to read only, so
that the UUID values are drawn strictly internally.
Map the field names in the CDS data definition to the fields on the database table.
For each entity, define an alias and an implementation class. The behavior definition editor provides a quickfix
to directly create the behavior class with the name that you specify in the behavior definition. The only behavior
that needs implementation is authorization control. The corresponding methods for global and instance
authorization control are generated in the local types of the ABAP behavior pool.
 Expand the following code sample to view the source code of /DMO/R_Travel_D.
 Sample Code
managed;

strict;

define behavior for /DMO/R_Travel_D alias Travel

implementation in class /dmo/bp_i_travel_d unique

Develop PUBLIC 593

persistent table /DMO/A_TRAVEL_D

lock master
authorization master ( instance,global )
etag master LocalLastChangedAt
{
create;
update;
delete;
field ( numbering : managed, readonly ) TravelUUID;

mapping for /DMO/A_TRAVEL_D

{ AgencyID = agency_id;
Description = description;
EndDate = end_date;
LocalCreatedAt = local_created_at;
LocalCreatedBy = local_created_by;
LocalLastChangedAt = local_last_changed_at;
LocalLastChangedBy = local_last_changed_by;
OverallStatus = overall_status;
TravelUUID = travel_uuid; }
}

define behavior for /DMO/R_Booking_D alias Booking

implementation in class /dmo/bp_i_booking_d unique

persistent table /DMO/A_BOOKING_D

{
update;
delete;
association _BookingSupplement { create; }
field ( readonly ) TravelUUID;
field ( numbering : managed, readonly ) BookingUUID;

mapping for /DMO/A_BOOKING_D

{ AirlineID = carrier_id;
BookingStatus = booking_status;
BookingUUID = booking_uuid;
TravelUUID = parent_uuid; }
}

define behavior for /DMO/R_BookingSupplement_D alias BookingSupplement

implementation in class /dmo/bp_i_bookingsupplement_d unique

persistent table /DMO/A_BKSUPPL_D

{
update;
delete;
field ( numbering : managed, readonly ) BookSupplUUID;

mapping for /DMO/A_BKSUPPL_D

{ BookSupplPrice = price;

594 PUBLIC Develop
BookSupplUUID = booksuppl_uuid;
BookingUUID = parent_uuid;
TravelUUID = root_uuid; }

}
4.2.4.1.2.2 Developing Actions
For the managed scenario with draft, add actions for nonstandard modify operations.
Actions are used to manifest business-logic-specific work-flows in one operation. You can implement simple
status changes or a complete creation work-flow in one operation. For the UI, you can define action buttons
that execute the action directly when the consumer chooses the button. For more detailed information, see
Actions [page 101].
For this scenario, define and implement the following actions:
• For the travel entity, the following actions are described:

• acceptTravel
The action sets the travel status to Accepted (A).
Technically speaking, this action is an instance action with return parameter $self. The value of
the field OverallStatus is changed by executing a modify request to update this field with the value
A.
• rejectTravel
The action sets the travel status to Rejected (X).
Technically speaking, this action is an instance action with return parameter $self. The value of
the field OverallStatus is changed by executing a modify request to update this field with the value
X.
• deductDiscount
The action calculates a new travel price by deducting a discount for the BookingFee. The consumer
can freely choose the percentage that is deducted. The value must be passed together with the action
request. On the Fiori UI, the UI provides a pop-up window for the consumer to fill in the requested
value. The action parameter is modeled with an abstract entity.
Technically speaking, the action is an instance action with an importing action parameter and
returns itself. The parameter is modeled with an abstract entity. The value of the field BookingFee is
changed by executing a modify request to update this field with the calculated value.
• reCalcTotalPrice
The action calculates the total price for one travel instance. It adds up the prices of all bookings,
including their supplements, and the booking fee of the travel instance. If different currencies are used,
the prices are converted to the currency of the travel instance.

Develop PUBLIC 595
Technically speaking, the action is an internal instance action. This action is invoked by
determinations that are triggered when one of the involved fields is changed: BookingFee (travel
entity), FlightPrice (booking entity), and Price (booking supplement entity).
For a detailed description on how to implement the described behavior for the relevant entity, check the
implementation steps in the following topics.
Implementing Actions for the Travel Entity [page 596]

For the managed scenario with draft, define and implement actions on the travel entity.
4.2.4.1.2.2.1 Implementing Actions for the Travel Entity
For the managed scenario with draft, define and implement actions on the travel entity.
Actions acceptTravel and rejectTravel
Both actions change the status of a travel instance. They are implemented exactly in the same way: Define the
actions in the behavior definition and implement them in the behavior implementation class for Travel.
Definition
Define instance actions with result $self. The field OverallStatus is set to read only, so the consumer
can only change the status via the actions acceptTravel and rejectTravel.
 Sample Code

...
{ ...
field ( readonly ) OverallStatus;
action rejectTravel result [1] $self;

… }
Via a quick fix, you can generate the method declaration in the behavior pool directly from the behavior
definition editor.
Implementation
1. Define constants that are available for the travel status in the private section of the local types.
 Sample Code

PRIVATE SECTION.
CONSTANTS:
BEGIN OF travel_status,
open TYPE c LENGTH 1 VALUE 'O', "Open
accepted TYPE c LENGTH 1 VALUE 'A', "Accepted
rejected TYPE c LENGTH 1 VALUE 'X', "Rejected
END OF travel_status.
….

596 PUBLIC Develop

ENDCLASS.
2. Update the field OverallStatus with a modify request for all instances with the given keys. Provide the
value accpeted for accepting the travel, and rejected for rejecting the travel.
3. The actions return $self. That means, they must return the updated instances in the result parameter. For
that reason, read the updated instances from the buffer and fill an internal table.
4. Pass the internal table to the result parameter.
 Expand the following code sample to view the source code of Action acceptTravel.
 Sample Code
METHOD acceptTravel.

"Modify travel instance


ENTITY Travel
UPDATE FIELDS ( OverallStatus )
OverallStatus = travel_status-
accepted ) ).
"Read changed data for action result


ENTITY Travel
ALL FIELDS WITH

ENDMETHOD.
 Expand the following code sample to view the source code of Action rejectTravel.
 Sample Code
METHOD rejectTravel.

"Modify travel instance


ENTITY Travel
rejected ) ).


ENTITY Travel
ALL FIELDS WITH

ENDMETHOD.
Action deductDiscount
Define the action in the behavior definition and implement it in the behavior implementation class for Travel.

Develop PUBLIC 597
deductDiscount requires an importing parameter for entering the discount percentage. The value must be
passed together with the action request. The action parameter is modeled with an abstract entity.
Creating an Abstract Entity for the Action Input Parameter

1. Create a data definition for a CDS abstract entity, as described in .
2. Define an element for the discount percentage with the type abap.int1.
3. Annotate the element with @Consumption.defaultValue: '10' to set the default value for the
discount percentage to 10.
 Sample Code
@EndUserText.label: 'Abstract Entity for Deducting Discount'

define abstract entity /DMO/A_TRAVEL_DISCOUNT

{
@Consumption.defaultValue: '10'
discount_percent : abap.int1;

}
Define the action in the behavior definition and implement it in the behavior implementation class for Travel.
Definition
Define an instance action with an action parameter /DMO/A_TRAVEL_DISCOUNT and the result $self.
 Sample Code

...
{ ...

action deductDiscount parameter /DMO/A_TRAVEL_DISCOUNT result [1] $self;

… }
definition editor.
Implementation
 Note
The input parameter of parameter actions is passed to the action method as the component %param in the
importing parameter.
Calculate the new total price for the travel instance by deducting the provided discount percentages. The
following steps guide you through the implementation.
1. Define an internal table and pass the entries of the importing parameter keys. Loop at the internal table for
the keys with parameter values that do not match the preconditions for percentage value:
1. It must not be initial.
2. It must be less than 100.
3. It must be greater or equal than 0.
2. Append the transactional key to the failed table and append the corresponding message to the reported
table if there are keys that do not match the preconditions. Delete the entries in the internal table that do
not match the preconditions.

598 PUBLIC Develop
3. If there are still entries in the internal table that match the preconditions, read all travel instances with the
imported keys into an internal table travels for the remaining entries.
4. Loop over the internal table and calculate the new reduced booking fee and append it to an internal table
for update.
5. Execute a modify request to update the field BookingFee for the instances in the buffer.
6. To fill the action result, read the involved travel instances and fill the result correspondingly.
 Expand the following code sample to view the source code of Action deductDiscount.
 Sample Code
METHOD deductDiscount.

DATA travels_for_update TYPE TABLE FOR UPDATE /DMO/R_Travel_D.

DATA(keys_with_valid_discount) = keys.
LOOP AT keys_with_valid_discount ASSIGNING FIELD-
SYMBOL(<key_with_valid_discount>) WHERE %param-discount_percent IS INITIAL
OR %param-
discount_percent > 100
OR %param-
discount_percent <= 0.
APPEND VALUE #( %tky = <key_with_valid_discount>-

%tky ) TO failed-travel.
APPEND VALUE #( %tky = <key_with_valid_discount>-

%tky

%msg = NEW /dmo/
cm_flight_messages(

textid = /dmo/
cm_flight_messages=>discount_invalid

severity =
%element-TotalPrice = if_abap_behv=>mk-on
%op-%action-deductDiscount = if_abap_behv=>mk-on
DELETE keys_with_valid_discount.
ENDLOOP.
CHECK keys_with_valid_discount IS NOT INITIAL.
"get total price


ENTITY Travel
FIELDS ( BookingFee )
WITH CORRESPONDING #( keys_with_valid_discount )
DATA percentage TYPE decfloat16.
DATA(discount_percent) = keys_with_valid_discount[ KEY id %tky =
<travel>-%tky ]-%param-discount_percent.
percentage = discount_percent / 100 .
DATA(reduced_fee) = <travel>-BookingFee * ( 1 - percentage ) .
APPEND VALUE #( %tky = <travel>-%tky
BookingFee = reduced_fee
) TO travels_for_update.
ENDLOOP.
"update total price with reduced price


ENTITY Travel
UPDATE FIELDS ( BookingFee )
WITH travels_for_update.


ENTITY Travel
ALL FIELDS WITH
CORRESPONDING #( travels )
RESULT DATA(travels_with_discount).

Develop PUBLIC 599
result = VALUE #( FOR travel IN travels_with_discount ( %tky = travel-
%tky
%param =
travel ) ).

ENDMETHOD.
Action reCalcTotalPrice
The action reCalcTotal price is called by determinations if changes on prices in the travel entity itself or in
the child entities are executed. The total price on the travel entity is then recalculated.
Definition
Define the internal action in the behavior definition and implement it in the behavior implementation class for
Travel.
 Remember
Internal actions can only be called from BO internal consumers.
In our demo scenario, the action is called from determinations on all three BO entities, whenever a price field or
a currency code field is changed.
 Sample Code

...
{ ...
internal action reCalcTotalPrice;

… }
definition editor.
Implementation
To determine the total price of a travel, all prices must be converted to the travel currency and then summed
up. This is done for each BO entity separately. The following steps guide you through the implementation.
1. Define an internal standard table amounts_per_currencycode to process amounts and the related
currency code.
2. Read all the instances with the imported keys into an internal table travels.
3. Delete instances with empty CurrencyCode. For such instances, the total price cannot be calculated.
4. Read all bookings for the returned travels into an internal table bookings. Return the link table to receive
the associated bookings for each travel.
5. Read all booking supplements for the returned bookings into an internal table bookingsupplements.
Return the link table to receive the associated bookingsupplements for each affected booking.
6. Loop at travels and start filling the amounts per currency with the corresponding values from the travel
instance.
7. Loop at booking_links where the travel ID matches the respective travel and add the price to the travel
price in the table amounts_per_currencycode if it has the same currency code. The ABAP statement

600 PUBLIC Develop
COLLECT is useful in this case, as it sums the amounts with the same currency code and appends a new
line if the currency codes differ.
8. Loop at bookingsupplement_links where the booking ID matches the respective booking and add the
price to the travel price in the table amounts_per_currencycode if it has the same currency code.
9. Delete the entries in this able where the currency_code is not filled.
10. Loop at the table amounts_per_currencycode and convert the amounts with currency codes other than
the travel currency code into the currency code of the travel instance.
11. Sum up the converted amounts for one travel.
12. Modify the travel entity with the new total price for all requested travel instances.
 Expand the following code sample to view the source code of Action reCalCTotalPrice.
 Sample Code
METHOD reCalcTotalPrice.

TYPES: BEGIN OF ty_amount_per_currencycode,
amount TYPE /dmo/total_price,
currency_code TYPE /dmo/currency_code,
END OF ty_amount_per_currencycode.
DATA: amounts_per_currencycode TYPE STANDARD TABLE OF
ty_amount_per_currencycode.
" Read all relevant travel instances.


ENTITY Travel
FIELDS ( BookingFee CurrencyCode )
DELETE travels WHERE CurrencyCode IS INITIAL.
" Read all associated bookings and add them to the total price.


ENTITY Travel BY \_Booking
FIELDS ( FlightPrice CurrencyCode )
LINK DATA(booking_links)
" Read all associated booking supplements and add them to the total price.


ENTITY Booking BY \_BookingSupplement
FIELDS ( BookSupplPrice CurrencyCode )
LINK DATA(bookingsupplement_links)
" Set the start for the calculation by adding the booking fee.
amounts_per_currencycode = VALUE #( ( amount = <travel>-
bookingfee
currency_code = <travel>-
currencycode ) ).
LOOP AT booking_links INTO DATA(booking_link) USING KEY id WHERE source-
%tky = <travel>-%tky.
" Short dump occurs if link table does not match read table, which
must never happen
DATA(booking) = bookings[ KEY id %tky = booking_link-target-%tky ].
COLLECT VALUE ty_amount_per_currencycode( amount = booking-
flightprice
currency_code = booking-
currencycode ) INTO amounts_per_currencycode.
LOOP AT bookingsupplement_links INTO DATA(bookingsupplement_link)
USING KEY id WHERE source-%tky = booking-%tky.
DATA(bookingsupplement) = bookingsupplements[ KEY id %tky =
bookingsupplement_link-target-%tky ].
COLLECT VALUE ty_amount_per_currencycode( amount =
bookingsupplement-booksupplprice

Develop PUBLIC 601
currency_code =
bookingsupplement-currencycode ) INTO amounts_per_currencycode.
ENDLOOP.
ENDLOOP.
DELETE amounts_per_currencycode WHERE currency_code IS INITIAL.
CLEAR <travel>-TotalPrice.
LOOP AT amounts_per_currencycode INTO DATA(amount_per_currencycode).
" If needed do a Currency Conversion
IF amount_per_currencycode-currency_code = <travel>-CurrencyCode.
<travel>-TotalPrice += amount_per_currencycode-amount.
ELSE.

/DMO/CL_FLIGHT_AMDP=>convert_currency(

EXPORTING
iv_amount = amount_per_currencycode-amount
iv_currency_code_source = amount_per_currencycode-
currency_code
iv_currency_code_target = <travel>-CurrencyCode
iv_exchange_rate_date =
cl_abap_context_info=>get_system_date( )
IMPORTING
ev_amount =
DATA(total_booking_price_per_curr)
).
<travel>-TotalPrice += total_booking_price_per_curr.
ENDIF.
ENDLOOP.
ENDLOOP.
" write back the modified total_price of travels


ENTITY travel
UPDATE FIELDS ( TotalPrice )
WITH CORRESPONDING #( travels ).

ENDMETHOD.
4.2.4.1.2.3 Developing Determinations
For the managed scenario with draft, add determinations to calculate values implicitly.
With determinations, you can generalize the calculation of values in the business logic of a managed BO. For
more detailed information, see Determinations [page 119].
 Note
You can assign determinations to determine actions that are called by side effects. This enables immediate
feedback after the user changes UI fields or field groups. For more detailed information, see Side Effects
[page 133].
For this demo scenario, define and implement determinations for all three BO entities.
• For the travel entity, the following determinations are described:

• setTravelNumber

602 PUBLIC Develop
The semantic ID for the travel entity is drawn by the determination when a new instance is created.
Since the semantic TravelID should not be provided by the client, the field must be set to read
only.
 Note
In this demo scenario, we use a simplified approach to determine new readable IDs for the BO
instances. To ensure that gap-free and non-duplicate IDs are assigned, use a number range object.
Technically speaking, this determination is a determination on save with the trigger operation
create.
• setStatusToOpen
The travel is set to Open when a new instance is created.
Technically speaking, this determination is a determination on modify with the trigger operation
create.
• calculateTotalPrice
The determination adds the prices of the travel (BookingFee), the booking (FlightPrice), and
the booking supplement entity (Price). The sum of these values is the total price of the travel. The
determination is triggered whenever one of the fields or the corresponding currency field is changed,
and when a travel instance is created. Since the recalculation should be triggered whenever one of the
mentioned fields is changed, the calculation of the total price is outsourced to an action. This action is
triggered by a determination on each entity.
 Note
You can only define trigger fields for a determination from the same entity the determination is
assigned to. A determination that is defined for the travel entity cannot have trigger fields from the
booking entity.
Technically speaking, this determination is a determination on modify with the trigger operation
create and with the field triggers BookingFee and CurrencyCode.
• For the booking entity, the following determinations are described:
• setBookingNumber
The semantic ID for the booking entity is drawn by the determination when a new instance is created.
Since the semantic BookingID should not be provided by the client, the field must be set to read
only.
Technically speaking, this is a determination on save with the trigger operation create.
• setBookingDate
The booking date is set when the booking instance is saved to the database. The booking date is only
set internally by the determination and must not be changed after the instance is saved. Therefore, set
the field BookingDate to read only. #
Technically speaking, this is determination on save with the trigger operation create.
See description above. Since the recalculation must also be triggered when the related fields of the
booking entity are changed, the determination must be defined and implemented again.
Technically speaking, this is a determination on modify with the field triggers FlightPrice and
CurrencyCode.
• For the booking supplement entity, the following determinations are described:
• setBookSupplNumber

Develop PUBLIC 603
The semantic ID for the booking supplement entity is drawn by the determination when a new instance
is created. Since the semantic BookingSupplementID should not be provided by the client, the field
must be set to read only.
Technically speaking, this is a determination on save with the trigger operation create.
See description above. Since the recalculation must also be triggered when the related fields of the
booking supplement entity are changed, the determination must be defined and implemented again.
Technically speaking, this is a determination on modify with the trigger operation create and the
field triggers BookSupplPrice and CurrencyCode.
Determining Values for the Travel Entity [page 604]

For the managed scenario with draft, define and implement determinations on the travel entity for
implicit value calculation.
Determining Values for the Booking Entity [page 608]

For the managed scenario with draft, define and implement determinations on the booking entity for
implicit value calculation.
Determining Values for the Booking Supplement Entity [page 612]

For the managed scenario with draft, define and implement determinations on the booking supplement
entity for implicit value calculation.
4.2.4.1.2.3.1 Determining Values for the Travel Entity
For the managed scenario with draft, define and implement determinations on the travel entity for implicit
value calculation.
Determination setTravelNumber
Define the determination in the behavior definition and implement it in the behavior implementation class for
Travel.
Definition
Define a determination on modify with trigger operation create. Since the travel ID must not be changed
externally, define the field TravelID as readonly.
 Sample Code

...
{ ...
field ( readonly ) TravelID;
determination setTravelNumber on save { create; }

… }

604 PUBLIC Develop
definition editor.
Quick Fix for Generating Method Declaration in the Behavior Pool
Implementation
Determine the number for a new travel instance by selecting the highest available number from the database
and add 1. The following steps guide you through the implementation.
1. Read all the travel instances with the imported keys into an internal table and delete the instances that
already have a travel number (TravelID). Continue to work only with instances that do not have a travel
number yet. If the determination is executed several times, the travel numbers must not be calculated
again. This is particularly important in order to stick to the rule of idempotence for determinations.
 Remember
The determination result must not change if the determination is executed several times under the
same conditions (idempotence). See Rules for Determinations [page 119].
2. Select the maximum travel number from the database table /DMO/A_TRAVEL_D.
3. Update the field TravelID of all involved instances with a modify request and assign a new TravelID by
adding 1 to the max travel from before . Write messages in the request's reported table.
 Note
Since the determination is only executed on save, it is secured that adding 1 to the maximum number in
the persisted table returns unique results.
 Expand the following code sample to view the source code of Determination setTravelNumber.
 Sample Code
METHOD setTravelNumber.

"Ensure idempotence


ENTITY Travel
FIELDS ( TravelID )
DELETE travels WHERE TravelID IS NOT INITIAL.
CHECK travels IS NOT INITIAL.
"Get max travelID

SELECT SINGLE FROM /DMO/A_TRAVEL_D FIELDS MAX( travel_id ) INTO
@DATA(max_travelid).

"update involved instances


ENTITY Travel
UPDATE FIELDS ( TravelID )
WITH VALUE #( FOR travel IN travels INDEX INTO i (
%tky = travel-%tky
TravelID = max_travelid + i ) ).

ENDMETHOD.

Develop PUBLIC 605
Determination setStatusToOpen
Travel.
Definition
Define a determination on modify with trigger operation create. The overall status of the travel is only
changed by the actions rejectTravel and acceptTravel, see Accept and Reject Travel [page 596].
Therefore the field is read only for the external consumer.
 Sample Code

...
{ ...
field ( readonly ) TravelID; OverallStatus;
determination setStatusToOpen on modify { create; }

… }
definition editor.
Implementation
Set the status to Open when new instances are created The following steps guide you through the
implementation.
1. Read all the travel instances with the imported keys into an internal table and delete the instances that
already have an entry in the status field (OverallStatus). Continue to work only with instances that do not
have a status yet. If the determination is executed after the status value is set by the consumer, the status
must not be set to open.
2. For those instances, that have an initial value in OverallStatus update the field OverallStatus with
open by executing a modify request for all instances with the imported keys. The constant open was
defined before in the private section of the local types. Write messages in the reported table of the modify
request.
 Note
Idempotence is not an issue in this determination. Even if the determination is executed several times
and an instance already has the status Open, the outcome of the determination does not change with
the modify request execution.
 Expand the following code sample to view the source code of Determination setStatusToOpen.
 Sample Code
METHOD setStatusToOpen.


ENTITY Travel
FIELDS ( OverallStatus )
"If Status is already set, do nothing
DELETE travels WHERE OverallStatus IS NOT INITIAL.

606 PUBLIC Develop


ENTITY Travel
WITH VALUE #( FOR travel IN travels ( %tky = travel-%tky
open ) ).

ENDMETHOD.
Determination calculateTotalPrice
Travel.
 Note
The actual calculation of the total price is done by the action recalcTotalPrice. The determination just
executes the action. See Action recalcTotalPrice [page 600].
Definition
Define a determination on modify with operation trigger create and field triggers BookingFee and
CurrencyCode and define the field TotalPrice as read only, as the value must no be defined externally.
 Sample Code

...
{ ...
field ( readonly ) TravelID; OverallStatus; TotalPrice;
determination calculateTotalPrice on modify { create; field BookingFee,
CurrencyCode; }

… }
definition editor.
Implementation
Execute the action recalcPrice when the trigger fields are changed. The following steps guide you through
the implementation.
1. Execute a modify request for action execution for all instances with the imported keys. Write messages in
the reported table of the modify request.
 Expand the following code sample to view the source code of Determination calculateTotalPrice.
 Sample Code


ENTITY Travel
FROM CORRESPONDING #( keys ).


Develop PUBLIC 607
ENDMETHOD.
4.2.4.1.2.3.2 Determining Values for the Booking Entity
For the managed scenario with draft, define and implement determinations on the booking entity for implicit
value calculation.
Determination setBookingNumber
Travel.
Definition
Define a determination on save with trigger operation create. Since the booking ID must not be changed
externally, define the field BookingID as read only.
 Sample Code

...
{ ...
field ( readonly ) BookingID;
determination setBookingNumber on save { create; }

… }
definition editor.
Implementation
Determine the number for a new booking instance by looping at all bookings for one booking and determine the
greatest ID. Add 1 for every new booking instance. The following steps guide you through the implementation.
1. Read all the corresponding travel instances for the incoming booking keys into an internal table travels.
If multiple bookings of the travel are requested, the travel is returned only once.
2. Read all bookings for all affected travels into an internal table bookings. Return the link table to receive
the associated bookings for each travel.
3. Loop at travels and define a variable for the maximum booking ID and set the value to '0000' (initial
value).
4. Loop at booking_links where the travel key matches the affected travel. Compare the booking ID with
the maximum booking ID to determine the maximum booking ID available for the travel instance.
5. Provide a booking ID for all bookings of this travel that have none. Only the booking instances that have
no booking ID assigned are taken into account. This is particularly important in order to stick to the rule of
idempotence for determinations.

608 PUBLIC Develop
 Remember
Write the new booking IDs into a new internal table typed as table for update.
6. Update the booking entity with the entries of the internal update table.
 Expand the following code sample to view the source code of Determination setBookingNumber.
 Sample Code
METHOD setBookingNumber.

DATA:
max_bookingid TYPE /dmo/booking_id,

bookings_update TYPE TABLE FOR UPDATE /DMO/R_Travel_D\\Booking,

booking TYPE STRUCTURE FOR READ RESULT /DMO/R_Booking_D.

"Read all travels for the requested bookings
" If multiple bookings of the same travel are requested, the travel is
returned only once.


" Read all bookings for all affected travels


ENTITY Travel BY \_Booking
FIELDS ( BookingID )
LINK DATA(booking_links)
" Process all affected travels.
" find max used bookingID in all bookings of this travel
max_bookingid = '0000'.
LOOP AT booking_links INTO DATA(booking_link) USING KEY id WHERE source-
%tky = travel-%tky.
must never happen
booking = bookings[ KEY id %tky = booking_link-target-%tky ].
IF booking-BookingID > max_bookingid.
max_bookingid = booking-BookingID.
ENDIF.
ENDLOOP.
"Provide a booking ID for all bookings of this travel that have none.
LOOP AT booking_links INTO booking_link USING KEY id WHERE source-%tky
= travel-%tky.
must never happen
booking = bookings[ KEY id %tky = booking_link-target-%tky ].
IF booking-BookingID IS INITIAL.
max_bookingid += 1.
BookingID = max_bookingid
) TO bookings_update.
ENDIF.
ENDLOOP.
ENDLOOP.
" Provide a booking ID for all bookings that have none.


ENTITY booking
UPDATE FIELDS ( BookingID )
WITH bookings_update.


Develop PUBLIC 609
ENDMETHOD.
Determination setBookingDate
Booking.
Definition
Define a determination on save with trigger operation create. Once the booking date is set, when a booking
instance is saved to the database, the date should not be changed afterward. Therefore the field BookingDate
is read only for the external consumer.
 Sample Code

...
{ ...
field ( readonly ) TravelUUID, BookingID, BookingDate;
determination setBookingDate on save { create; }

… }
definition editor.
Implementation
Set the system date for the booking date. The following steps guide you through the implementation.
1. Read all the booking instances with the imported keys into an internal table and delete the instances that
already have a booking date (BookingDate). Continue to work only with instances that do not have a
booking date yet. If the determination is executed several times, the booking date must not be calculated
again. This is particularly important in order to stick to the rule of idempotence for determinations.
 Remember
2. Assign the system date sy-datum to BookingDate for every incoming booking instance .
3. Update the field BookingDate of all involved instances with a modify request.
 Expand the following code sample to view the source code of Determination setBookingDate.
 Sample Code
METHOD setBookingDate.


ENTITY Booking
FIELDS ( BookingDate )
DELETE bookings WHERE BookingDate IS NOT INITIAL.

610 PUBLIC Develop
CHECK bookings IS NOT INITIAL.
LOOP AT bookings ASSIGNING FIELD-SYMBOL(<booking>).
<booking>-BookingDate = cl_abap_context_info=>get_system_date( ).
ENDLOOP.


ENTITY Booking
UPDATE FIELDS ( BookingDate )
WITH CORRESPONDING #( bookings ).

ENDMETHOD.
Booking.
 Note
The actual calculation of the total price is done by the action recalcPrice. The determination just
Definition
Define a determination on modify with operation trigger create and field triggers FlightPrice and
CurrencyCode.
 Sample Code

...
{ ...
determination calculateTotalPrice on modify { create; field FlightPrice,
CurrencyCode; }

… }
definition editor.
Implementation
Execute the action reCalcTotalPrice when the trigger fields are changed. The following steps guide you
through the implementation.
1. To get the TravelUUID, read the travel instance by a read by association into an internal table. The key of
the root instance is needed for the action execution.
2. Execute a modify request for action execution for all affected travel instances.
 Note
The response parameters failed and reported are not retrieved in this EML call, since the action
reCalcTotalPrice does not return these parameters. It is assumes that the action cannot fail as it is
only called internally and processed by the managed BO provider.
The response parameter result is not retrieved as the action doesn't define this parameter.

Develop PUBLIC 611
 Sample Code

" Read all parent UUIDs


" Trigger Re-Calculation on Root Node

ENTITY Travel
FROM CORRESPONDING #( travels ).

ENDMETHOD.
4.2.4.1.2.3.3 Determining Values for the Booking Supplement

Entity
For the managed scenario with draft, define and implement determinations on the booking supplement entity
for implicit value calculation.
Determination setBookSupplNumber
BookingSupplement.
Definition
Define a determination on save with trigger operation create. Since the booking supplement ID must not be
changed externally, define the field BookingSupplementID as read only.
 Sample Code

...
{ ...
field ( readonly ) TravelUUID, BookingSupplementID;
determination setBookSupplNumber on save { create; }

… }
definition editor.
Implementation
The implementation for determining new booking supplement numbers is the same as the calculation for the
booking. For a detailed step-by-step description, see Determination setBookingNumber [page 608].

612 PUBLIC Develop
 Expand the following code sample to view the source code of Determination setBookSupplNumber.
 Sample Code
METHOD setBookSupplNumber.

DATA:
max_bookingsupplementid TYPE /dmo/booking_supplement_id,

bookingsupplements_update TYPE TABLE FOR UPDATE /DMO/R_Travel_D\
\BookingSupplement,

bookingsupplement TYPE STRUCTURE FOR READ RESULT /DMO/
R_BookingSupplement_D.

"Read all bookings for the requested booking supplements
" If multiple booking supplements of the same booking are requested, the
booking is returned only once.


ENTITY BookingSupplement BY \_Booking
FIELDS ( BookingUUID )
" Read all booking supplements for the affected bookings


ENTITY Booking BY \_BookingSupplement
FIELDS ( BookingSupplementID )
LINK DATA(bookingsupplement_links)
" Process all affected bookings.
" find max used booking supplement ID in all booking supplements of
this booking
max_bookingsupplementid = '00'.
LOOP AT bookingsupplement_links INTO DATA(bookingsupplement_link) USING
KEY id WHERE source-%tky = booking-%tky.
bookingsupplement = bookingsupplements[ KEY id %tky =
IF bookingsupplement-BookingSupplementID > max_bookingsupplementid.
max_bookingsupplementid = bookingsupplement-BookingSupplementID.
ENDIF.
ENDLOOP.
"Provide a booking supplement ID for all booking supplements of this
booking that have none.
LOOP AT bookingsupplement_links INTO bookingsupplement_link USING KEY
id WHERE source-%tky = booking-%tky.
bookingsupplement = bookingsupplements[ KEY id %tky =
IF bookingsupplement-BookingSupplementID IS INITIAL.
max_bookingsupplementid += 1.
APPEND VALUE #( %tky = bookingsupplement-%tky
bookingsupplementid = max_bookingsupplementid
) TO bookingsupplements_update.
ENDIF.
ENDLOOP.
ENDLOOP.
" Provide a booking supplement ID for all booking supplements that have
none.


ENTITY BookingSupplement
UPDATE FIELDS ( BookingSupplementID ) WITH bookingsupplements_update.

ENDMETHOD.

Develop PUBLIC 613
BookingSupplement.
 Note
The actual calculation of the total price is done by the action recalcPrice. The determination just
Definition
Define a determination on modify with operation trigger create and field triggers BookSupplPrice and
CurrencyCode.
 Sample Code

...
{ ...
determination calculateTotalPrice on modify { create; field BookSupplPrice,
CurrencyCode; }

… }
definition editor.
Implementation
Execute the action reCalcTotalPrice when the trigger fields are changed. The steps are exactly the same as
in Determination calculateTotalPrice [page 611].
 Sample Code

" Read all parent UUIDs


ENTITY BookingSupplement BY \_Travel
" Trigger Re-Calculation on Root Node


ENTITY Travel
FROM CORRESPONDING #( travels ).

ENDMETHOD.

614 PUBLIC Develop
4.2.4.1.2.4 Developing Feature Control
For the managed scenario with draft, enable and disable functionality with feature control.
Feature control is used to define the availability of behavior components, like fields, actions, and operations.
You can define if these components are always available for the client or only under certain circumstances
(dynamic feature control). For more detailed information, see Feature Control [page 128].
For this demo scenario, define and implement field, operation and action control.
• Define field control.

• field (readonly)
Fields that are filled by the RAP managed runtime framework (internally) are set to read only as the
consumer is not allowed to change these. Marking these fields as read only in the behavior definition
makes also has an effect on the UI. The end user cannot provide values for these fields. In the travel
scenario, the fields that are set to read only are the administrative fields and fields that are filled
internally, for example by determinations. These fields are:
• On the travel entity:
TravelID, OverallStatus, TotalPriceLocalCreatedAt, LocalCreatedBy,
LocalLastChangedAt, LocalLastChangedBy
• On the booking entity:
TravelUUID, BookingID, BookingDate, LocalLastChangedAt
• On the booking supplement entity:
TravelUUID, BookingUUID, BookingSupplementID, LocalLastChangedAt
The key fields whose values are set by the RAP managed runtime framework via managed numbering
must also be set to read only. They also receive the attribute numbering: managed. These fields are:
• On the travel entity: TravelUUID
• On the booking entity: BookingUUID
• On the booking supplement entity: BookSupplUUID
• field (mandatory)
Fields whose values are checked by validations are set to mandatory. These fields are:
CustomerID, AgencyID, BeginDate, EndDate
• On the booking entity:
CustomerID, AirlineID, ConnectionID, FlightDate
• On the booking supplement entity:
SupplementID
• field (feature: instance)
Fields whose logic depends on other circumstances are controlled by dynamic feature control. In this
scenario, the BookingFee (on the travel entity) is set to read only if the instance's status is Accepted
(A). The feature control condition must be implemented in the behavior class.
• Define operation control.
• create (features : instance)

Develop PUBLIC 615
Use dynamic operation control for the associations that are enabled for create. In this demo scenario,
you can only create new booking instance for a travel if the overall status is not rejected ('X'). The
feature control condition must be implemented in the behavior class.
association _Booking { create (features : instance); }
• Define action control.
• action (features: instance)
Dynamic operation control is used for actions that are enabled depending on other states of the
instance. These actions are
The action acceptTravel can only be executed, if the overall status is not already set to Accepted
(A): action ( features: instance ) acceptTravel result [1] $self;,
The action rejectTravel can only be executed, if the overall status is not already set Rejected
(X): action ( features: instance ) rejectTravel result [1] $self; on the travel
entity.
The action deductDiscount can only be executed, if the overall status is not already set Accepted
(A): action ( features: instance ) deductDiscount result [1] $self; on the
travel entity.
Adding Feature Control for the Travel Entity [page 616]

For the managed scenario with draft, enable and disable functionality with feature control on the travel
entity.
Adding Feature Control for the Booking Entity [page 618]

For the managed scenario with draft, enable and disable functionality with feature control on the
booking entity.
Adding Feature Control for the Booking Supplement Entity [page 618]
For the managed scenario with draft, enable and disable functionality with feature control on the
booking supplement entity.
4.2.4.1.2.4.1 Adding Feature Control for the Travel Entity
For the managed scenario with draft, enable and disable functionality with feature control on the travel entity.
Define the static and dynamic feature control in the behavior definition and implement dynamic feature control
in the behavior implementation class for Travel.
Definition
Define field, action, and operation control. For dynamic feature control, add (feature: instance) to the
feature control definition.
 Sample Code

...
{ ...

616 PUBLIC Develop
association _Booking { create ( features : instance ); }
field ( readonly ) TravelID, OverallStatus, TotalPrice, LocalCreatedAt,
LocalCreatedBy, LocalLastChangedAt, LocalLastChangedBy;
field ( mandatory ) CustomerID, AgencyID, BeginDate, EndDate;
field ( features : instance ) BookingFee;
action ( features : instance ) acceptTravel result [1] $self;
action ( features : instance ) rejectTravel result [1] $self;

action ( features : instance ) deductDiscount parameter /DMO/
A_TRAVEL_DISCOUNT result [1] $self;

… }
Via a quick fix, you can generate the method declaration for the feature control implementation in the behavior
pool directly from the behavior definition editor.
Dynamic Feature Control Implementation for the Travel Entity
Dynamic feature control must be implemented in the behavior implementation in the method FOR FEATURES.
You can use the quick fix on one of the dynamic feature control features in the behavior definition for the
method declaration. The following steps guide you through the implementation.
1. Read all the instances with the imported keys into an internal table travels. The fields that are relevant
to decide whether features are available must be included in the read result. For the travel entity, only the
field OverallStatus is relevant.
2. Fill the result table of the method with the respective feature. Use the transaction key %tky to identify
the travel instance. The importing parameter keys contains the %field, %action, %assoc component to
determine what kind of feature is controlled. Use a condition statement to define the circumstance and the
outcome of each dynamically controlled feature. You can work with the constants, defined in the private
section of the behavior class, to refer to the values of the overall status.
 Expand the following code sample to view the source code of GET_INSTANCE_FEATURES.
 Sample Code


ENTITY Travel
FIELDS ( OverallStatus )
FAILED failed.
result = VALUE #( FOR ls_travel IN travels
( %tky = ls_travel-%tky
%field-BookingFee = COND #( WHEN ls_travel-
OverallStatus = travel_status-accepted
THEN
if_abap_behv=>fc-f-read_only
ELSE
if_abap_behv=>fc-f-unrestricted )
%action-acceptTravel = COND #( WHEN ls_travel-
THEN
if_abap_behv=>fc-o-disabled
ELSE
if_abap_behv=>fc-o-enabled )
%action-rejectTravel = COND #( WHEN ls_travel-
OverallStatus = travel_status-rejected
THEN
ELSE

Develop PUBLIC 617
%action-deductDiscount = COND #( WHEN ls_travel-
THEN
ELSE
%assoc-_Booking = COND #( WHEN ls_travel-
OverallStatus = travel_status-rejected
THEN
ELSE
) ).

ENDMETHOD..
4.2.4.1.2.4.2 Adding Feature Control for the Booking Entity
For the managed scenario with draft, enable and disable functionality with feature control on the booking
entity.
Define static feature control in the behavior definition. For the Booking entity, there is no dynamic feature
control.
Definition
Define field control.
 Sample Code

...
{...
field ( readonly ) TravelUUID, BookingID, BookingDate, LocalLastChangedAt;

… }
4.2.4.1.2.4.3 Adding Feature Control for the Booking

Supplement Entity
For the managed scenario with draft, enable and disable functionality with feature control on the booking
supplement entity.
Define the static feature control in the behavior definition. For the BookingSupplement, there is no dynamic
feature control.
Definition
Define field control.

618 PUBLIC Develop
 Sample Code

...
{ ...
field ( readonly ) TravelUUID, BookingUUID, BookingSupplementID,
LocalLastChangedAt;
field ( mandatory ) SupplementID;

… }
4.2.4.1.2.5 Developing Authorization
For the managed scenario with draft, add authorization control to prevent unauthorized modifying access to
the business object.
With authorization control, you define which users are allowed to make changes on BO instances. The RAP
model differentiates between general authorization to use operations (global authorization), and instance-
specific authorization, which assigns authorization to use operations depending on values of an instance in
question (instance authorization). For more detailed information, see Authorization Control [page 80].
In this reference scenario, authorization for each standard operation is considered separately. That means,
one user group might be able to create new instances, but is not allowed to update this instance or vice
verse. Actions, however, use the same authorization as the operation update. The authorization control can be
delegated for these operations.
 Note
In the ABAP Flight Reference Scenario, the authorization objects aren't configured in the back end and
thus would prevent any operation for any user. Hence, the code example provides a simulated authorization
check without using authorization objects in addition to the check via the authorization object. Don't use
the simulation code in productive applications.
For this scenario, define and implement the following authorization control:
• Define and implement global authorization.

Global authorization is checked for all standard operations and actions. The authorization for the operating
user is checked with authorization objects for each modifying operation separately, which means there
can be a different authorization for the create, update and delete operation. All actions are treated like the
update operation. In this example implementation, a simulation is provided to allow all users to execute all
operations.
For a detailed description on how to implement global authorization control, see Implementing Global
Authorization [page 620].
• Define and implement instance authorization.
Instance authorization is checked for all instance-related operations. Instance authorization is checked
with an authorization object against an authorization field. In this example scenario, users are only

Develop PUBLIC 619
authorized to modify travel instances that have an agency with one specific country code. A simulation
implementation is provided to allow users to modify instances only, if the country code of the related
agency is US. However, you can use any other country code as well.
 Note
In the dedicated authorization methods, it's only possible to check instance authorization against the
state of the instance before the current LUW. In other words, authorization is checked against the
persistent state of the instance, if there's one. For new instances, the same authorization as for global
authorization is applied. To check authorization against incoming values, you need to implement a
precheck.
For a detailed description on how to implement instance authorization control, see Implementing Instance
Authorization [page 624].
• Define and implement prechecks.
Prechecks check against incoming values. In this example, the precheck implementation checks that only
BOs with AgencyIDs with the country_code US can created or updated.
For a detailed description on how to implement prechecks, see Implementing Prechecks [page 630].
 Note
Authorization for authorization-dependent entities is delegated to the authorization master entity. That
means, modify requests on authorization-dependent entities are treated like the update operation on the
authorization master entity.
Implementing Global Authorization [page 620]

For the managed scenario with draft, authorize users to generally modify travel instances.
Implementing Instance Authorization [page 624]

For the managed scenario with draft, authorize users to modify travel instances based on an
authorization field.
Implementing Prechecks [page 630]

For the managed scenario with draft, add prechecks to check authorization against incoming values to
prevent values from reaching the transactional buffer.
4.2.4.1.2.5.1 Implementing Global Authorization

For the managed scenario with draft, authorize users to generally modify travel instances.
Define global authorization in the behavior definition and implement it in the behavior implementation class for
Travel. For conceptual information, see Authorization Control [page 80].
 Note

620 PUBLIC Develop
Definition
If not already done so, define authorization master (global) for the travel entity and authorization
dependent by _Travel for the booking and the booking supplement entity in the behavior definition.
In addition, delegate the authorization control for all actions, except for the internal and draft actions, and the
create-by-association to the update operation. The syntax authorization: update is used.
 Sample Code
managed;

with draft;


implementation in class /DMO/BP_TRAVEL_D unique


...
{...
association _Booking { create ( features : instance, authorization:
update ) ; }
...
action ( features : instance, authorization: update ) acceptTravel result
[1] $self;
action ( features : instance, authorization: update ) rejectTravel result
[1] $self;

action ( features : instance, authorization: update ) deductDiscount
parameter /DMO/A_TRAVEL_DISCOUNT result [1] $self;

...}


implementation in class /DMO/BP_BOOKING_D unique

....
{...
association _BookingSupplement { create ( authorization: update ); }
...}


implementation in class /DMO/BP_BOOKINGSUPPLEMENT_D unique

...
{
...

}
Via a quick fix, you can generate the method declaration for the authorization control implementation in the
behavior pool directly from the behavior definition editor.
Implementation
Global authorization control must be implemented in the behavior implementation in the method FOR GLOBAL
AUTHORIZATION. You can use the quick fix in the behavior definition for the method declaration. The methods
imports the parameter requested_authorizations, which indicates the operations for which authorization
is requested. In the implementation, you have to fill the parameter result, which must be filled with the
authorization result for each requested operation. The method also has the changing parameter reported,
which is to be filled if you want to return messages for unauthorized cases. For more information, about
implementation details, see Authorization Implementation [page 86].
The authorization concept in this guide assumes that there can be different authorizations for creating,
updating, and deleting instances. All actions of the travel BO are considered with the same authorization
as the update operation. With this approach, it is possible that one user is allowed to create a new travel

Develop PUBLIC 621
instance, but is not allowed to use actions. Actions and create-by-association are defined with the addition
authorization: update and thus must not be treated separately in the authorization implementation.
As the authorization for create, update, and delete is the same for global and instance authorization (except
for the relevant authorization field for instance authorization), it is best practice to outsource the actual
authorization check in separate methods that can be called by for all authorization checks that are need in the
BO implementation.
The following steps guide you through the implementation.
Methods for Authorization Checks

1. For each operation, create a method to check the authorization for it.
2. We use the authorization object /DMO/TRVL to check the authorization for each operation.
For more information, about using and configuring authorization objects, see and Authorization Basics.
 Home For more information, about using and configuring authorization objects, see User and Role
Administration of Application Server ABAP
In each method, call the authorization object and check for the relevant activity.
Authorization Fields in Authorization Object

Operation Activity Field
create Field 01 (Add or Create)
update + all actions Field 02 (Change)
delete Field 06 (Delete)
The authorization object checks against the authorization field /DMO/CNTRY. For global authorization,
this is not relevant as the authorization for executing the operations is independent of the state of the
respective instance, and thus independent of the value of the authorization field. For that reason, you can
use 'DUMMY' for the authorization field.
The implementation considers the authorization for each modify operation separately. There can be a
different authorization for creating, updating, and deleting instances on the travel BO.
3. Evaluate the authorization for the respective operation based on sy-subrc and fill the response
parameter of the method.
4. As the authorization which is checked by the authorization object is not configured in the backend, we
provide a simulation implementation to allow all users for all operations. Do not use this piece of code in
productive applications.
 Expand the following code sample to view the source code of the methods is_create_granted,
is_update_granted, and is_delete_granted.
 Sample Code

PRIVATE SECTION.
...
METHODS is_create_granted
RETURNING VALUE(create_granted) TYPE abap_bool.
METHODS is_update_granted
RETURNING VALUE(update_granted) TYPE abap_bool.
METHODS is_delete_granted
RETURNING VALUE(delete_granted) TYPE abap_bool.
ENDCLASS.

622 PUBLIC Develop
METHOD is_create_granted.

AUTHORITY-CHECK OBJECT '/DMO/TRVL'

ID '/DMO/CNTRY' DUMMY

ID 'ACTVT' FIELD '01'.
create_granted = COND #( WHEN sy-subrc = 0 THEN abap_true ELSE
abap_false ).
"Simulation for full authorization
"(not to be used in productive code)
create_granted = abap_true.
ENDIF.
ENDMETHOD.
METHOD is_update_granted.



update_granted = COND #( WHEN sy-subrc = 0 THEN abap_true ELSE
abap_false ).
update_granted = abap_true.
ENDIF.
ENDMETHOD.
METHOD is_delete_granted.



delete_granted = COND #( WHEN sy-subrc = 0 THEN abap_true ELSE
abap_false ).
delete_granted = abap_true.
ENDIF.
ENDMETHOD.

ENDCLASS.
Global Authorization Implementation

1. For each operation, check if the authorization is requested. In this example, all actions are treated like the
update operation. The draft action Edit must be delegated manually in the implementation. Authorizations
for all other actions are delegated in the behavior definition.
2. Fill the reported parameter with an adequate message, if the user is unauthorized for the respective
operation.
 Expand the following code sample to view the source code of the method
get_global_authorizations.
 Sample Code

PRIVATE SECTION.
...
IMPORTING REQUEST requested_authorizations FOR travel RESULT result.
ENDCLASS.
IF requested_authorizations-%create EQ if_abap_behv=>mk-on.
IF is_create_granted( ) = abap_true.
result-%create = if_abap_behv=>auth-allowed.
ELSE.
result-%create = if_abap_behv=>auth-unauthorized.

APPEND VALUE #( %msg = NEW /dmo/cm_flight_messages(

textid = /dmo/
cm_flight_messages=>not_authorized


Develop PUBLIC 623
severity =
%global = if_abap_behv=>mk-on
ENDIF.
ENDIF.
"Edit is treated like update
IF requested_authorizations-%update = if_abap_behv=>mk-
on OR
requested_authorizations-%action-Edit = if_abap_behv=>mk-
on.
IF is_update_granted( ) = abap_true.
result-%update = if_abap_behv=>auth-allowed.
result-%action-Edit = if_abap_behv=>auth-allowed.
ELSE.
result-%update = if_abap_behv=>auth-unauthorized.
result-%action-Edit = if_abap_behv=>auth-unauthorized.


textid = /dmo/

severity =
ENDIF.
ENDIF.
IF requested_authorizations-%delete = if_abap_behv=>mk-on.
IF is_delete_granted( ) = abap_true.
result-%delete = if_abap_behv=>auth-allowed.
ELSE.
result-%delete = if_abap_behv=>auth-unauthorized.


textid = /dmo/

severity =
ENDIF.
ENDIF.
ENDMETHOD.

ENDCLASS.
4.2.4.1.2.5.2 Implementing Instance Authorization
For the managed scenario with draft, authorize users to modify travel instances based on an authorization field.
Define instance authorization in the behavior definition and implement it in the behavior implementation class
for Travel. For conceptual information, see Authorization Control [page 80].
 Note

624 PUBLIC Develop
Definition
If not already done so, define authorization master (instance) for the travel entity and
authorization dependent by _Travel for the booking and the booking supplement entity in the
If not already done, delegate the authorization control for all actions, except for the internal and draft actions,
and the create-by-association to the update operation. The syntax authorization: update is used.
 Sample Code
managed;

with draft;




...
authorization master ( global, instance )
{...
association _Booking { create ( features : instance, authorization:
update ) ; }
...
action ( features : instance, authorization: update ) acceptTravel result
[1] $self;
action ( features : instance, authorization: update ) rejectTravel result
[1] $self;

action ( features : instance, authorization: update ) deductDiscount
parameter /DMO/A_TRAVEL_DISCOUNT result [1] $self;

...}



....
{...
association _BookingSupplement { create ( authorization: update ); }
...}



...
{
...

}
Via a quick fix, you can generate the method declaration for the authorization control implementation in the
behavior pool directly from the behavior definition editor.
Implementation
Instance authorization control must be implemented in the behavior implementation in the method FOR
INSTANCE AUTHORIZATION. You can use the quick fix in the behavior definition for the method declaration.
The method imports the parameter requested_authorizations, which indicates the operations for which
authorization is requested. Like other instance-specific implementations, the method imports the key of the
instances, for which authorization is requested. In the implementation, you have to fill the parameter result,
which must be filled with the authorization result for each requested operation. The method also has the
changing parameter reported, which is to be filled if you want to return messages for unauthorized cases. For
more information, about implementation details, see Authorization Implementation [page 86].
The authorization concept in this guide assumes that there can be different authorizations for creating,
updating, and deleting instances. All actions of the travel BO are considered with the same authorization as the

Develop PUBLIC 625
update operation. With this approach, it is possible that one user is allowed to create a new travel instance, but
is not allowed to use actions.
As the authorization for create, update, and delete is the same for global and instance authorization (except
for the relevant authorization field for instance authorization), it is best practice to outsource the actual
authorization check in separate methods that can be called for all authorization checks that are needed in the
BO implementation. The implementation for these methods is explained in detail in Methods for Authorization
Checks [page 622]. Since the instance authorization check is based on a field value, the methods must be
adapted to also import a parameter.
The following steps guide you through the implementation.
Methods for Authorization Checks

1. In the methods is_update_granted and is_delete_granted, add an optional importing parameter to
pass the country code of the used agency ID. (The method is_create_granted is not used for instance
authorization checks as the create operation is not instance specific.)
2. In the method implementation for the corresponding method, differentiate between calls from global
and instance authorization by adding an if-block, in which the authorization object is called when the
authorization field country_code is supplied.
3. Evaluate the authorization for the respective operation based on sy-subrc and fill the response
parameter of the method.
4. As the authorization which is checked by the authorization object is not configured in the backend, we
provide a simulation implementation to allow all users for all operations. Do not use this piece of code in
productive applications.
5. To simulate the authorization check against the agency's country code, we provide a simulation
implementation to only allow modification on instances that have an agency with country code US. You
can change this country code by any other.
 Expand the following code sample to view the source code of the methods is_update_granted, and
is_delete_granted.
 Sample Code

PRIVATE SECTION.
...
METHODS is_update_granted
IMPORTING country_code TYPE land1 OPTIONAL
RETURNING VALUE(update_granted) TYPE abap_bool.
METHODS is_delete_granted
IMPORTING country_code TYPE land1 OPTIONAL
RETURNING VALUE(delete_granted) TYPE abap_bool.
ENDCLASS.
METHOD is_update_granted.
"For instance auth
IF country_code IS SUPPLIED.


ID '/DMO/CNTRY' FIELD country_code

abap_false ).
" simulation of auth check for demo,
" auth granted for country_code US, else not
* CASE country_code.
* WHEN 'US'.

626 PUBLIC Develop
* create_granted = abap_true.
* WHEN OTHERS.
* create_granted = abap_false.
* ENDCASE.
"For global auth
ELSE.



abap_false ).
ENDIF.
ENDMETHOD.
METHOD is_delete_granted.
"For instance auth
IF country_code IS SUPPLIED.


ID '/DMO/CNTRY' FIELD country_code

abap_false ).
" simulation of auth check for demo,
" auth granted for country_code US, else not
* CASE country_code.
* WHEN 'US'.
* create_granted = abap_true.
* WHEN OTHERS.
* create_granted = abap_false.
* ENDCASE.
"For global auth
ELSE.



abap_false ).
ENDIF.
ENDMETHOD.
...

ENDCLASS.
Instance Authorization Implementation
In this scenario, the instance authorization is based on the value of the agency's country code that is used in
the travel instance. With instance authorization you can only check authorization against the persistent state
of the instance. That means, you have to provide the value of the country code as it is on the persistent table
(and not the value, which is supplied by the request). In other words, if an update request changes the value of
the agency to a value that is not in the authorization scope for this user, the request is not denied during the
transaction phase (as the value on the persistent table is one, for which the user is authorized). The request
is only denied during the save sequence if a precheck checks the authorization of the incoming value. See
Implementing Prechecks [page 630].
For instances that don't exist on the persistent database table yet (because they have just been created in the
current LUW), authorization is always granted. This also becomes relevant in draft scenarios for edit-drafts.

Develop PUBLIC 627
The following steps guide you through the implementation steps for instance authorization.
1. Read all the instances with the imported keys into an internal table travels. As the AgencyID is relevant
for the authorization, it must be included in the read result.
2. To get the agency's country code of the persistent version of the imported instance keys, select from the
persistent table for travels /DMO/A_TRAVEL_D with an inner join on the agency table /DMO/AGENCY.
3. Loop at the travels table to assign the authorization for each insane separately. There are two cases to
consider:
• For instances that have a persistent state on the database table /DMO/A_TRAVEL_D, delegate the
authorization check to the relevant method for update or delete and pass the retrieved value for the
corresponding country code of the agency. To check if a persistent instance exists, check if an instance
with the current travel UUID exists on the select result. If sy-subrc returns 0, the read was successful.
If the corresponding authorization check methods deny authorization for the respective operation, fill
the reported parameter with an adequate message.
• For instances that do not have a persistent state on the database table /DMO/A_TRAVEL_D, check the
authorization for create, as update or delete operations on newly created instances are considered as
part of the create operation as long as the changes are not committed.
4. Fill the result parameter result with the determined authorization for each operation.
get_instance_authorizations.
 Sample Code

PRIVATE SECTION.
...
METHODS get_instance_authorizations FOR INSTANCE AUTHORIZATION
IMPORTING keys REQUEST requested_authorizations FOR travel RESULT
result.
ENDCLASS.
METHOD get_instance_authorizations.
DATA: update_requested TYPE abap_bool,
delete_requested TYPE abap_bool,
update_granted TYPE abap_bool,
delete_granted TYPE abap_bool.


ENTITY Travel
FIELDS ( AgencyID )
FAILED failed.
"Select country_code and agency of corresponding persistent travel
instance
"authorization only checked against instance that have active
persistence

SELECT FROM /DMO/A_TRAVEL_D AS travel INNER JOIN /DMO/AGENCY AS
agency

ON travel~agency_id = agency~agency_id
FIELDS travel~travel_uuid , travel~agency_id, agency~country_code
FOR ALL ENTRIES IN @travels WHERE travel_uuid EQ @travels-
TravelUUID
INTO TABLE @DATA(travel_agency_country).
"edit is treated like update
update_requested = COND #( WHEN requested_authorizations-
%update = if_abap_behv=>mk-on OR
requested_authorizations-%action-
Edit = if_abap_behv=>mk-on

628 PUBLIC Develop
THEN abap_true ELSE abap_false ).
delete_requested = COND #( WHEN requested_authorizations-
%delete = if_abap_behv=>mk-on
"get country_code of agency in corresponding instance on persistent
table
READ TABLE travel_agency_country WITH KEY travel_uuid = travel-
TravelUUID
ASSIGNING FIELD-SYMBOL(<travel_agency_country_code>).
"Auth check for active instances that have before image on
persistent table
IF sy-subrc = 0.
"check auth for update
IF update_requested = abap_true.
update_granted = is_update_granted( <travel_agency_country_code>-
country_code ).
IF update_granted = abap_false.


textid = /dmo/
cm_flight_messages=>not_authorized_for_agencyid

agency_id = travel-
AgencyID
severity =
%element-AgencyID = if_abap_behv=>mk-on
ENDIF.
ENDIF.
"check auth for delete
IF delete_requested = abap_true.
delete_granted = is_delete_granted( <travel_agency_country_code>-
country_code ).
IF delete_granted = abap_false.


textid = /dmo/

agency_id = travel-AgencyID
severity =
ENDIF.
ENDIF.
" operations on draft instances and on active instances that have
no persistent before image (eg Update on newly created instance)
" create authorization is checked, for newly created instances
ELSE.
update_granted = delete_granted = is_create_granted( ).


textid = /dmo/

severity =
ENDIF.
ENDIF.
APPEND VALUE #( LET upd_auth = COND #( WHEN update_granted =
abap_true THEN if_abap_behv=>auth-allowed
ELSE if_abap_behv=>auth-
unauthorized )
del_auth = COND #( WHEN delete_granted =
abap_true THEN if_abap_behv=>auth-allowed

Develop PUBLIC 629
unauthorized )
IN
%tky = travel-%tky
%update = upd_auth
%action-Edit = upd_auth
%delete = del_auth
) TO result.
ENDLOOP.
ENDMETHOD.

ENDCLASS.
4.2.4.1.2.5.3 Implementing Prechecks
For the managed scenario with draft, add prechecks to check authorization against incoming values to prevent
values from reaching the transactional buffer.
Define prechecks in the behavior definition and implement it in the behavior implementation class for Travel.
For conceptual information, see Operation Precheck [page 115] .
Definition
Define the create and update with the addition (precheck). With the addition of precheck, the behavior
implementation for precheck is called, before the main operation is executed. To get an overview of the runtime
behavior for create and update with precheck and other standard operations, see Standard Operations
[page 88]. The precheck operations receive all entities to be created and returns failed and reported as
changing parameters if the check against the incoming values returns a negative result. For more information
about the response parameters, see Response Parameters [page 159].
Additionally, add with addtional implementation to the draft action Resume. This is required to trigger
a check against the AgencyID field in case of an edit draft. This additional check is only required for RAP
BOs with draft capabilities.
 Expand the following code sample to view the source code Of the behavior definition for /DMO/R_Travel_D.
 Sample Code

managed;
strict;
with draft;
implementation in class /dmo/bp_travel_d unique
persistent table /dmo/a_travel_d
draft table /dmo/d_travel_d
lock master
total etag LastChangedAt
authorization master ( global, instance )
{
create ( precheck );
update ( precheck );
...
draft action Resume with additional implementation;

630 PUBLIC Develop

}
Via a quick fix, you can generate the method declaration for the prechecks in the behavior pool directly from
the behavior definition editor.
Implementation
Prechecks
The authorization to create or save an updated instance with a provided agency ID is checked based on the
value of the agency's country/region code. It's only possible to save newly created or updated instance with
a certain value of country_code. The demo scenario uses US, which can be changed to any other country
code. The precheck for the create and update operation checks whether this condition is fulfilled before a
create is triggered. Since both operation precheks check against the same incoming value, a helper method
precheck_auth was created to streamline the implementation. Both precheck implementations delegate the
actual check against the agencyID country code fo the helper method. Both methods return failed and
reported as changing parameters.
 Expand the following code sample to view the source code of the methods precheck_create FOR CREATE and
precheck_update FOR UPDATE.
 Sample Code
METHOD precheck_create.

precheck_auth(
EXPORTING
entities_create = entities
CHANGING
).
ENDMETHOD.
METHOD precheck_update.
precheck_auth(
EXPORTING
entities_update = entities
CHANGING
).

ENDMETHOD.
Method precheck_auth
The method precheck_auth first differentiates whether it is called from the precheck method FOR CREATE
or FOR UPDATE based on its importing parameters and the operation variable. An assert ensures that
the method can only be called from one of the precheck implementations and not both at the same time.
A select retrieves the corresponding country_code for the AgencyID from the database table. The
implementation loops over all entities that were imported and delegates the check against the US value for
the country_code based on the operation type: If the operation variable is flagged as create, the method
is_create_granted is called and received the retrieved country_code as importing parameter. In case
operation is flagged as update, the method is_update_granted is called and check the country_code.

Develop PUBLIC 631
If any other value than US is set, the boolean value is_modify_granted is set to abap_false, meaning that
the authorization is denied. In this case, the response parameters failed and reported are filled.
 Note
 Expand the following code sample to view the source code of the method precheck_auth.
 Sample Code
METHOD precheck_auth.

DATA:
entities TYPE t_entities_update,
operation TYPE if_abap_behv=>t_char01,
agencies TYPE SORTED TABLE OF /dmo/agency WITH UNIQUE KEY
agency_id,
is_modify_granted TYPE abap_bool.
" Either entities_create or entities_update is provided. NOT both and at
least one.
ASSERT NOT ( entities_create IS INITIAL EQUIV entities_update IS
INITIAL ).
IF entities_create IS NOT INITIAL.
entities = CORRESPONDING #( entities_create MAPPING %cid_ref = %cid ).
operation = if_abap_behv=>op-m-create.
ELSE.
entities = entities_update.
operation = if_abap_behv=>op-m-update.
ENDIF.
DELETE entities WHERE %control-AgencyID = if_abap_behv=>mk-off.
agencies = CORRESPONDING #( entities DISCARDING DUPLICATES MAPPING
agency_id = AgencyID EXCEPT * ).
CHECK agencies IS NOT INITIAL.
SELECT FROM /dmo/agency FIELDS agency_id, country_code
FOR ALL ENTRIES IN @agencies
WHERE agency_id = @agencies-agency_id
INTO TABLE @DATA(agency_country_codes).
LOOP AT entities INTO DATA(entity).
is_modify_granted = abap_false.
READ TABLE agency_country_codes WITH KEY agency_id = entity-AgencyID
ASSIGNING FIELD-SYMBOL(<agency_country_code>).
"If invalid or initial AgencyID -> validateAgency
CHECK sy-subrc = 0.
CASE operation.
WHEN if_abap_behv=>op-m-create. is_modify_granted =
is_create_granted( <agency_country_code>-country_code ).
WHEN if_abap_behv=>op-m-update. is_modify_granted =
is_update_granted( <agency_country_code>-country_code ).
ENDCASE.
IF is_modify_granted = abap_false.
APPEND VALUE #(
%cid = COND #( WHEN operation =
if_abap_behv=>op-m-create THEN entity-%cid_ref )
%tky = entity-%tky
) TO failed.
APPEND VALUE #(
%cid = COND #( WHEN operation =
if_abap_behv=>op-m-create THEN entity-%cid_ref )
%tky = entity-%tky

632 PUBLIC Develop
textid = /dmo/
agency_id = entity-AgencyID
severity =
) TO reported.
ENDIF.
ENDLOOP.

ENDMETHOD.
Resume with Additional Implementation
The draft capabilities of the BO require an additional check implementation for an edit draft use case.
If a draft has expired and the AgencyID was changed and the user comes back to work on the instance,
the precheck implementation must be triggered again to ensure the consistency of the authority check
against the country_code value. The implementation read the AgencyID of the travel. Then the %control-
AgencyID is set to true to trigger the precheck implementation. An edit draft scenario is treated as
update in case of the precheck, so the helper method precheck_auth is called with the exporting parameter
entities_update. The helper method treats this call as an update in its implementation.
 Expand the following code sample to view the source code of the method resume.
 Sample Code
METHOD resume.

DATA:
entities_update TYPE t_entities_update.
READ ENTITIES OF /dmo/r_travel_d IN LOCAL MODE
ENTITY Travel
FIELDS ( AgencyID )
WITH VALUE #(
FOR key IN keys
%is_draft = if_abap_behv=>mk-on
( %key = key-%key )
)
" Set %control-AgencyID (if set) to true, so that the precheck_auth
checks the permissions.
entities_update = CORRESPONDING #( travels CHANGING CONTROL ).
IF entities_update IS NOT INITIAL.
precheck_auth(
EXPORTING
entities_update = entities_update
CHANGING
).
ENDIF.

ENDMETHOD.

Develop PUBLIC 633
4.2.4.1.2.6 Developing Validations
For the managed scenario with draft, add validations to check the values provided by the client.
Validations are used to check whether provided values by a client are consistent. They give direct feedback
(messages) before the BO instance is saved to the database. For more detailed information, see Validations
[page 123].
 Note
You can assign validations to determine actions that are called by side effects. This enables immediate
feedback after the user changes UI fields or field groups. For more detailed information, see Action
Definition [page 102].
As validations verify the state of an instance, state messages are used to return messages.
 Note
State messages reflect the business object state. Since validations check for data inconsistencies, they
return state messages. State messages are stored on the database and can be retrieved together with the
BO instance they relate to. In draft scenarios, state messages are used to describe data inconsistencies. As
state messages are persisted, they must be invalidated in the implementation. For more information, refer
to State Messages [page 268].
For messages that relate to a change of a BO instance, transition messages are used. Every modify request
is a change of state. If a modify requests fails, transition messages are used to describe and explain the
failure. Transition messages are not saved on a database. They disappear automatically once the failed
operation is rolled back. For more information, refer to Transition Messages [page 264]
.
For the travel demo scenario, define and implement validation for all three BO entities:
• For the travel entity, the following validations are described:

• validateCustomer
The provided customer ID is checked against the entries in /DMO/CUSTOMER. Saving instances with
invalid or initial values for the customer ID is rejected. In such a case, the validation returns failed keys
and a message.
The validation is triggered on create and on every update of the trigger field CustomerID.
• validateAgency
The provided agency ID is checked against the entries in /DMO/AGENCY. Saving instances with invalid
or initial values for the agency ID is rejected. In such a case, the validation returns failed keys and a
message.
The validation is triggered on create and on every update of the trigger field AgencyID.
• validateDates
The provided starting date is checked against the system date. It cannot be earlier than the system
date. In addition, the starting and the end date are compared against it each other. The end date

634 PUBLIC Develop
cannot be before the start date. If one of the conditions is not fulfilled, the saving is rejected and the
validation returns failed keys and a message.
The validation is triggered on create and on every update of the trigger fields BeginDate and
EndDate.
• validateCurrencyCode
The provided currency code is checked against the entries in I_Currency.Saving instances with
invalid or initial values for the currency code is rejected. In such a case, the validation returns failed
keys and a message
The validation is triggered on create and on every update of the trigger field CurrencyCode.
• For the booking entity, the following validations are described:
• validateCustomer
See validateCustomer [page 636] of travel entity.
• validateConnection
The provided values for AirlineID, ConnectionID and FlightDate are checked against the flight
data in /DMO/FLIGHT. Only existing flights with valid connection and airline IDs can be added to the
booking instance. If the condition is not fulfilled, the validation returns failed keys and a message.
The validation is triggered on create and every update of the trigger fields AirlineID,
ConnectionID, and FlightDate.
keys and a message
• For the booking supplement entity, the following validation is described:
• validateSupplement
The provided supplement ID is checked against the entries in /DMO/SUPPLEMENT. Saving instances
with invalid or initial values for the supplement ID is rejected. In such a case, the validation returns
failed keys and a message.
The validation is triggered on create and on every update of the trigger field SupplementID.
keys and a message
Validating Values for the Travel Entity [page 636]

For the managed scenario with draft, define and implement validations on the travel entity for value
consistency checks.
Validating Values for the Booking Entity [page 643]

For the managed scenario with draft, define and implement validations on the booking entity for value
consistency checks.
Validating Values for the Booking Supplement Entity [page 649]

For the managed scenario with draft, define and implement validations on the booking supplement
entity for value consistency checks.

Develop PUBLIC 635
4.2.4.1.2.6.1 Validating Values for the Travel Entity
For the managed scenario with draft, define and implement validations on the travel entity for value
consistency checks.
Validation validateCustomer
Define the validation in the behavior definition and implement it in the behavior implementation class for Travel.
Definition
Define a validation on save with trigger operation create and trigger field CustomerID. Since there must
always be a customer assigned to a certain travel, define the field CustomerID as mandatory.
 Sample Code

...
{ ...
field ( mandatory ) CustomerID;
validation validateCustomer on save { create; field CustomerID; }

… }
definition editor.
Implementation
Validate the customer ID by checking if the provided value is the ID of an entry in the customer database table.
Raise adequate messages for the consumer if the value is initial or not valid. The following steps guide you
1. Read all the instances with the imported keys into an internal table travels. This table is the basis to
check whether messages must be raised.
2. Copy the entries to another internal table and delete all instances with an initial customer ID. If the
resulting internal table is not initial, select the entries of /DMO/CUSTOMER with the given customer ID. If
there is no corresponding entry in this database table, the provided customer ID is not valid.
3. Loop over the internal table travels. To avoid duplicate state messages for the consumer, append an
empty message to the reported table to clear the state area.
4. If the customer ID is initial, write the transactional key to the failed table and append the corresponding
message to the state area VALIDATE_CUSTOMER. The RAP runtime framework provides the method new
message, with which you can easily retrieve messages from message classes provide the respective
parameters. The reported table includes the component %element. Here you can specify which CDS
element is responsible for the state inconsistency. The Fiori Elements UI, evaluates this component and
highlights the corresponding input field.
5. If there is no entry in the customer master data table, write the transactional key to the failed table and
append the corresponding message to the state area VALIDATE_CUSTOMER.
The messages for the managed scenario with draft are stored in the message class /dmo/cm_flight that is
part of the ABAP Flight Reference Scenario.

636 PUBLIC Develop
 Sample Code
METHOD validateCustomer.


ENTITY Travel
FIELDS ( CustomerID )

DATA customers TYPE SORTED TABLE OF /DMO/CUSTOMER WITH UNIQUE KEY
customer_id.

customers = CORRESPONDING #( travels DISCARDING DUPLICATES MAPPING
customer_id = CustomerID EXCEPT * ).
DELETE customers WHERE customer_id IS INITIAL.
IF customers IS NOT INITIAL.

SELECT FROM /DMO/CUSTOMER FIELDS customer_id

FOR ALL ENTRIES IN @customers
WHERE customer_id = @customers-customer_id
INTO TABLE @DATA(valid_customers).
ENDIF.
" Raise message for non existing customer id
%state_area = 'VALIDATE_CUSTOMER'
IF travel-CustomerID IS INITIAL.


textid =
/dmo/cm_flight_messages=>enter_customer_id

severity =
%element-CustomerID = if_abap_behv=>mk-on
ELSEIF travel-CustomerID IS NOT INITIAL AND NOT
line_exists( valid_customers[ customer_id = travel-CustomerID ] ).


customer_id =
travel-customerid

textid =
/dmo/cm_flight_messages=>customer_unkown

severity =
%element-CustomerID = if_abap_behv=>mk-on
ENDIF.
ENDLOOP.

ENDMETHOD.
Validation validateAgency

Develop PUBLIC 637
Definition
Define a validation on save with trigger operation create and trigger field AgencyID. Since there must always
be an agency assigned to a certain travel, define the field AgencyID as mandatory.
 Sample Code

...
{ ...
field ( mandatory ) CustomerID, AgencyID;
validation validateAgency on save { create; field AgencyID; }

… }
definition editor.
Implementation
Validate the agency ID by checking if the provided value is the ID of an entry in the agency database table. Raise
adequate messages for the consumer if the value is initial or not valid. The implementation steps are exactly
the same as for the validation ValidateCustomer.
 Expand the following code sample to view the source code of Validation validateAgency.
 Sample Code
METHOD validateAgency.

DATA: modification_granted TYPE abap_boolean,
agency_country_code TYPE land1.


ENTITY Travel
FIELDS ( AgencyID TravelID )
DATA agencies TYPE SORTED TABLE OF /dmo/agency WITH UNIQUE KEY agency_id.
" Optimization of DB select: extract distinct non-initial agency IDs
agencies = CORRESPONDING #( travels DISCARDING DUPLICATES MAPPING
agency_id = AgencyID EXCEPT * ).
DELETE agencies WHERE agency_id IS INITIAL.
IF agencies IS NOT INITIAL.
" Check if Agency ID exists
SELECT FROM /dmo/agency FIELDS agency_id, country_code
FOR ALL ENTRIES IN @agencies
WHERE agency_id = @agencies-agency_id
INTO TABLE @DATA(valid_agencies).
ENDIF.
" Raise message for non existing Agency id
%state_area = 'VALIDATE_AGENCY'
IF travel-AgencyID IS INITIAL.
textid = /dmo/
cm_flight_messages=>enter_agency_id
severity =

638 PUBLIC Develop
ELSEIF travel-AgencyID IS NOT INITIAL AND NOT
line_exists( valid_agencies[ agency_id = travel-AgencyID ] ).
agency_id =
travel-agencyid
textid
= /dmo/cm_flight_messages=>agency_unkown
severity =
ENDIF.
ENDLOOP.
ENDMETHOD.

Validation validateDates
Definition
Define a validation on save with trigger operation create and trigger fields BeginDate and EndDate. Since
the travel dates are an essential part of the travel data, define the fields BeginDate and EndDate as
mandatory.
 Sample Code

...
{ ...
validation validateDates on save { create; field BeginDate, EndDate; }

… }
Implementation
Validate the travel dates by comparing the value of the BeginDate with the EndDate. The end date must not
be before the begin date and the begin date must be after the system date. Raise adequate messages for the
consumer if the provided values are not valid. The following steps guide you through the implementation. The
messages for the managed scenario with draft are stored in the message class /DMO/CM_FLIGHT that is part
of the ABAP Flight Reference Scenario.
3. The travel date must fulfill four conditions:
1. Begin date must not be initial.
2. End date must not be initial.

Develop PUBLIC 639
3. Begin date must not be before system date.
4. End date must not be before begin date.
For all of the situations, check with an if-loop and append the transactional key to the failed
table. In addition, append the corresponding message to the state area VALIDATE_DATES. The RAP
runtime framework provides the method new message, with which you can easily retrieve messages
from message classes provide the respective parameters. The reported table includes the component
%element. Here you can specify which CDS element is responsible for the state inconsistency. The Fiori
Elements UI, evaluates this component and highlights the corresponding input field.
 Expand the following code sample to view the source code of Validation validateDates.
 Sample Code
METHOD validateDates.

ENTITY Travel
FIELDS ( BeginDate EndDate TravelID )

%state_area = 'VALIDATE_DATES' ) TO reported-
travel.
IF travel-BeginDate IS INITIAL.
textid
= /dmo/cm_flight_messages=>enter_begin_date
severity =
%element-BeginDate = if_abap_behv=>mk-on ) TO
reported-travel.
ENDIF.
IF travel-EndDate IS INITIAL.
textid
= /dmo/cm_flight_messages=>enter_end_date
severity =
%element-EndDate = if_abap_behv=>mk-on ) TO
reported-travel.
ENDIF.
IF travel-EndDate < travel-BeginDate AND travel-BeginDate IS NOT INITIAL
AND travel-EndDate IS NOT INITIAL.
textid
= /dmo/cm_flight_messages=>begin_date_bef_end_date
begin_date =
travel-BeginDate
end_date =
travel-EndDate
severity =
%element-BeginDate = if_abap_behv=>mk-on
%element-EndDate = if_abap_behv=>mk-on ) TO
reported-travel.

640 PUBLIC Develop
ENDIF.
IF travel-BeginDate < cl_abap_context_info=>get_system_date( ) AND
travel-BeginDate IS NOT INITIAL.
begin_date =
travel-BeginDate
textid
= /dmo/cm_flight_messages=>begin_date_on_or_bef_sysdate
severity =
%element-BeginDate = if_abap_behv=>mk-on ) TO
reported-travel.
ENDIF.
ENDLOOP.

ENDMETHOD.
Validation validateCurrenyCode
Definition
Define a validation on save with trigger operation create and trigger field CurrencyCode. Since the currency
code must always be provided for a booking, defined the field CurrencyCode as mandatory.
 Sample Code

...
{ ...
field ( mandatory ) CurrencyCode;
validation validateCurrencyCode on save { create; field CurrencyCode; }

… }
definition editor.
Implementation
Validate the currency code by checking if the provided value is the ID of an entry in the currency database table.
Raise adequate messages for the consumer if the value is initial or not valid. The following steps guide you
2. Copy the entries to another internal table and delete all instances with an initial currency code. If the
resulting internal table is not initial, select the entries of I_Currency with the given currency code. If there
is no corresponding entry in this database table, the provided currency code is not valid.
4. If the currency code is initial, write the transactional key to the failed table and append the corresponding
message to the state area VALIDATE_CURRENCYCODE. The RAP runtime framework provides the method

Develop PUBLIC 641
new message, with which you can easily retrieve messages from message classes provide the respective
parameters. The reported table includes the component %element. Here you can specify which CDS
element is responsible for the state inconsistency. The Fiori Elements UI, evaluates this component and
highlights the corresponding input field.
5. If there is no entry in the currency code master data table, write the transactional key to the failed table
and append the corresponding message to the state area VALIDATE_CURRENCYCODE.
The messages for the managed scenario with draft are stored in the message class /dmo/cm_flight that is
part of the ABAP Flight Reference Scenario.
 Expand the following code sample to view the source code of Validation validateCurrencyCode.
 Sample Code
METHOD validateCustomer.


ENTITY Travel
FIELDS ( CustomerID )


currencies = CORRESPONDING #( travels DISCARDING DUPLICATES MAPPING
currency = currencycode EXCEPT * ).


ENDIF.
%state_area = 'VALIDATE_CURRENCYCODE'
IF travel-currencycode IS INITIAL.
travel.


textid = /dmo/

severity =
%element-currencycode = if_abap_behv=>mk-on
ELSEIF NOT line_exists( currency_db[ currency = travel-currencycode ] ).
travel.

textid = /dmo/

severity =
currency_code =
travel-currencycode )
ENDIF.
ENDLOOP.


642 PUBLIC Develop
ENDMETHOD.
4.2.4.1.2.6.2 Validating Values for the Booking Entity
For the managed scenario with draft, define and implement validations on the booking entity for value
consistency checks.
Validation validateCustomer
Define the validation in the behavior definition and implement it in the behavior implementation class for
Booking.
Definition
Define a validation on save with trigger operation create and trigger field CustomerID. Since there must
always be a customer assigned to a certain travel, define the field CustomerID is mandatory.
 Sample Code

...
{ ...
field ( mandatory ) CustomerID;

… }
definition editor.
Implementation
The validation for the customer ID field is done similarly to the validation for the customer ID in the travel entity.
See Validation validateCustomer [page 636].
To retrieve the correct messages of validations in child entities and to display them on the UI, you have to
define a path expression to the root entity. To fill the path expression with the correct keys, you have to read the
keys of the parent entity first. This is done by a read by association. You do not need the full result of the read by
association, but just the link table, which contains the key mappings of source and target entity.
 Sample Code
METHOD validateCurrencyCode.


ENTITY booking
FIELDS ( currencycode )

Develop PUBLIC 643


FROM CORRESPONDING #( bookings )
LINK DATA(travel_booking_links).




ENDIF.
IF booking-currencycode IS INITIAL.
booking.


textid = /dmo/

severity =
%path = VALUE #( travel-%tky =
travel_booking_links[ KEY id source-%tky = booking-%tky ]-target-%tky )
currencycode ] ).
booking.


textid = /dmo/

severity =
currency_code =
booking-currencycode )
travel_booking_links[ KEY id source-%tky = booking-%tky ]-target-%tky )
ENDIF.
ENDLOOP.

ENDMETHOD.
Validation validateConnection
Booking.

644 PUBLIC Develop
Definition
Define a validation on save with trigger operation create and trigger fields AirlineID, ConnectionID,
and FlightDate. Since a booking instance must always entail this flight information, define these fields as
mandatory.
 Sample Code

...
{ ...
validation validateConnection on save { create; field AirlineID,
ConnectionID, FlightDate; }

… }
definition editor.
Implementation
Validate the flight-related fields by checking if the provided values match an entry in the master database
table /DMO/FLIGHT. Raise adequate messages for the consumer if the values are initial or not valid. The
following steps guide you through the implementation.
1. Read all the instances with the imported keys into an internal table bookings. This table is the basis to
2. Read the corresponding travel instances via a read by association. The parent keys are needed for the path
expression %path in the reported table. It represents the path the path to the root entity and is important
to display the messages correctly on the UI.
3. Loop over the internal table bookings. To avoid duplicate state messages for the consumer, append an
4. If the airline ID is initial, write the transactional key to the failed table and append the corresponding
message to the state area VALIDATE_CONNECTION.
Messages are created with the /dmo/cm_flight_messages message exception class, with which you can
easily retrieve messages from message classes and provide the respective parameters.
The reported table contains the component %path, in which you have to maintain the keys of all parent
instances, including the root entity. Use the key mappings in the link table to fill the path expression. Only if
all parent keys are maintained is the message displayed correctly on the UI.
The reported table includes the component %element. Here you can specify which CDS element is
responsible for the state inconsistency. The Fiori Elements UI, evaluates this component and highlights the
corresponding input field.
5. Repeat the step for the values in ConnectionID and FlightDate. Like AirlineID, they must not be
initial.
6. If all related fields are not empty you can check if the values match an entry in the flight master data table.
If the select finds a corresponding row (=sy-subrc <> 0), write the transactional key to the failed table
and append the corresponding message to the state area VALIDATE_CONNECTION.
 Expand the following code sample to view the source code of Validation validateConnection.
 Sample Code
METHOD validateConnection.


Develop PUBLIC 645

ENTITY Booking
FIELDS ( BookingID AirlineID ConnectionID FlightDate )


FROM CORRESPONDING #( bookings )
LINK DATA(travel_booking_links).
LOOP AT bookings ASSIGNING FIELD-SYMBOL(<booking>).
"overwrite state area with empty message to avoid duplicate messages
APPEND VALUE #( %tky = <booking>-%tky
%state_area = 'VALIDATE_CONNECTION' ) TO
reported-booking.
" Raise message for non existing airline ID
IF <booking>-AirlineID IS INITIAL.
APPEND VALUE #( %tky = <booking>-%tky ) TO failed-booking.
%state_area = 'VALIDATE_CONNECTION'


textid = /dmo/
cm_flight_messages=>ENTER_AIRLINE_ID

severity =
travel_booking_links[ KEY id source-%tky = <booking>-%tky ]-target-%tky )
%element-AirlineID = if_abap_behv=>mk-on
ENDIF.
" Raise message for non existing connection ID
IF <booking>-ConnectionID IS INITIAL.


textid = /dmo/
cm_flight_messages=>ENTER_CONNECTION_ID

severity =
%element-ConnectionID = if_abap_behv=>mk-on
ENDIF.
" Raise message for non existing flight date
IF <booking>-FlightDate IS INITIAL.


textid = /dmo/
cm_flight_messages=>ENTER_FLIGHT_DATE

severity =
%element-FlightDate = if_abap_behv=>mk-on
ENDIF.
" check if flight connection exists
IF <booking>-AirlineID IS NOT INITIAL AND
<booking>-ConnectionID IS NOT INITIAL AND
<booking>-FlightDate IS NOT INITIAL.

SELECT SINGLE Carrier_ID, Connection_ID, Flight_Date FROM /DMO/
FLIGHT WHERE carrier_id = @<booking>-AirlineID

AND
connection_id = @<booking>-ConnectionID

646 PUBLIC Develop
AND
flight_date = @<booking>-FlightDate
INTO
@DATA(flight).
IF sy-subrc <> 0.


textid =
/dmo/cm_flight_messages=>NO_FLIGHT_EXISTS

carrier_id =
<booking>-AirlineID
flight_date =
<booking>-FlightDate
severity =
%element-FlightDate = if_abap_behv=>mk-on
%element-AirlineID = if_abap_behv=>mk-on
%element-ConnectionID = if_abap_behv=>mk-on
ENDIF.
ENDIF.
ENDLOOP.
ENDMETHOD.

Validation validateCurrencyCode
Booking.
Definition
Define a validation on save with trigger operation create and trigger field CurrencyCode. Since there must
always be a currency code assigned to a booking price, define the field CurrencyCode as mandatory.
 Sample Code

...
{ ...
field ( mandatory ) CurrencyCode;

… }
definition editor.
Implementation
The validation for the currency code field is done similarly to the validation for the currency code in the travel
entity. See Validation validateCurrencyCode [page 641].
To retrieve the correct messages of validations in child entities and to display them on the UI, you have to
define a path expression to the root entity. To fill the path expression with the correct keys, you have to read the

Develop PUBLIC 647
keys of the parent entity first. This is done by a read by association. You do not need the full result of the read by
association, but just the link table, which contains the key mappings of source and target entity.
 Sample Code


ENTITY booking

DATA: currencies TYPE SORTED TABLE OFI_Currency WITH UNIQUE KEY currency.



ENDIF.
IF booking-currencycode IS INITIAL.
booking.


textid = /dmo/

severity =
currencycode ] ).
booking.


textid = /dmo/

severity =
currency_code =
booking-currencycode )
ENDIF.
ENDLOOP.

ENDMETHOD.

648 PUBLIC Develop
4.2.4.1.2.6.3 Validating Values for the Booking Supplement
Entity
For the managed scenario with draft, define and implement validations on the booking supplement entity for
value consistency checks.
Validation validateSupplement
BookingSupplement.
Definition
Define a validation on save with trigger operation create and trigger field SupplementID. Since a booking
supplement instance always needs a supplement, define the field SupplementID as mandatory.
 Sample Code

...
{ ...
field ( mandatory ) SupplementID
validation validateSupplement on save { create; field SupplementID; }

… }
definition editor.
Implementation
Validate the supplement ID by checking if the provided value is an entry in the supplement database table.
Raise adequate messages for the consumer if the value is initial or not valid. The implementation steps
are exactly the same as for the validation ValidateCustomer. For a detailed step-by-step description, see
Validation validateCustomer [page 643].
To fill the %path component in the reported table, you have to provide the keys of all parent instances.
Therefore you have to execute a read by association to every entity in the business object structure. In this
case, to Booking and to BookingSupplement.
 Expand the following code sample to view the source code of Validation validateSupplement.
 Sample Code
METHOD validateSupplement.


FIELDS ( SupplementID )
RESULT DATA(bookingsupplements)
FAILED DATA(read_failed).
failed = CORRESPONDING #( DEEP read_failed ).



Develop PUBLIC 649
FROM CORRESPONDING #( bookingsupplements )
LINK DATA(booksuppl_booking_links).


FROM CORRESPONDING #( bookingsupplements )
LINK DATA(booksuppl_travel_links).

DATA supplements TYPE SORTED TABLE OF /DMO/SUPPLEMENT WITH UNIQUE KEY
supplement_id.

supplements = CORRESPONDING #( bookingsupplements DISCARDING DUPLICATES
MAPPING supplement_id = SupplementID EXCEPT * ).
DELETE supplements WHERE supplement_id IS INITIAL.
IF supplements IS NOT INITIAL.

SELECT FROM /DMO/SUPPLEMENT FIELDS supplement_id

FOR ALL ENTRIES IN @supplements
WHERE supplement_id = @supplements-
supplement_id
INTO TABLE @DATA(valid_supplements).
ENDIF.
LOOP AT bookingsupplements ASSIGNING FIELD-SYMBOL(<bookingsupplement>).
APPEND VALUE #( %tky = <bookingsupplement>-%tky
%state_area = 'VALIDATE_SUPPLEMENT'
) TO reported-bookingsupplement.
IF <bookingsupplement>-SupplementID IS INITIAL.
APPEND VALUE #( %tky = <bookingsupplement>-%tky ) TO failed-
bookingsupplement.


textid = /dmo/
cm_flight_messages=>ENTER_SUPPLEMENT_ID

severity =
%path = VALUE #( booking-%tky =
booksuppl_booking_links[ KEY id source-%tky = <bookingsupplement>-%tky ]-
target-%tky
travel-%tky =
booksuppl_travel_links[ KEY id source-%tky = <bookingsupplement>-%tky ]-
target-%tky )
%element-SupplementID = if_abap_behv=>mk-on
ELSEIF <bookingsupplement>-SupplementID IS NOT INITIAL AND
NOT line_exists( valid_supplements[ supplement_id = <bookingsupplement>-
SupplementID ] ).
APPEND VALUE #( %tky = <bookingsupplement>-%tky ) TO failed-
bookingsupplement.


textid = /dmo/
cm_flight_messages=>SUPPLEMENT_UNKNOWN

severity =
booksuppl_booking_links[ KEY id source-%tky = <bookingsupplement>-%tky ]-
target-%tky
travel-%tky =
booksuppl_travel_links[ KEY id source-%tky = <bookingsupplement>-%tky ]-
target-%tky )
%element-SupplementID = if_abap_behv=>mk-on
ENDIF.
ENDLOOP.
ENDMETHOD.


650 PUBLIC Develop
Validation validateCurrencyCode
BookingSupplement.
Definition
Define a validation on save with trigger operation create and trigger field CurrencyCode. Since there must
always be currency code, define the field CurrencyCode as mandatory.
 Sample Code

...
{ ...
field ( mandatory ) SupplementID

… }
definition editor.
Implementation
Validate the currency code by checking if the provided value is an entry in I. Raise adequate messages for the
consumer if the value is initial or not valid. The implementation steps are exactly the same as for the validation
ValidateCustomer. For a detailed step-by-step description, see Validation validateCustomer [page 643].
To fill the %path component in the reported table, you have to provide the keys of all parent instances.
Therefore you have to execute a read by association to every entity in the business object structure. In this
case, to Booking and to BookingSupplement.
 Expand the following code sample to view the source code of Validation validateSupplement.
 Sample Code


RESULT DATA(booking_supplements).


FROM CORRESPONDING #( booking_supplements )
LINK DATA(booksuppl_booking_links).


FROM CORRESPONDING #( booking_supplements )
LINK DATA(booksuppl_travel_links).


currencies = CORRESPONDING #( booking_supplements DISCARDING DUPLICATES
MAPPING currency = currencycode EXCEPT * ).



Develop PUBLIC 651
ENDIF.
LOOP AT booking_supplements INTO DATA(booking_supplement).
APPEND VALUE #( %tky = booking_supplement-%tky
IF booking_supplement-currencycode IS INITIAL.
APPEND VALUE #( %tky = booking_supplement-%tky ) TO
failed-bookingsupplement.


textid = /dmo/

severity =
booksuppl_booking_links[ KEY id source-%tky = booking_supplement-%tky ]-
target-%tky
travel-%tky =
booksuppl_travel_links[ KEY id source-%tky = booking_supplement-%tky ]-
target-%tky )
ELSEIF NOT line_exists( currency_db[ currency = booking_supplement-
currencycode ] ).
APPEND VALUE #( %tky = booking_supplement-%tky ) TO
failed-bookingsupplement.


textid = /dmo/

severity =
booksuppl_booking_links[ KEY id source-%tky = booking_supplement-%tky ]-
target-%tky
travel-%tky =
booksuppl_travel_links[ KEY id source-%tky = booking_supplement-%tky ]-
target-%tky )
ENDIF.
ENDLOOP.

ENDMETHOD.
4.2.4.1.2.7 Developing Side Effects
For the managed scenario with draft, add side effects to model interdependencies between BO properties for a
reload of the affected properties.
With side effects, you can trigger data, permission, or message updates based on data changes in UI scenarios
with draft-enabled BOs. For more detailed information, see Side Effects [page 133].

652 PUBLIC Develop
For this demo scenario, define side effects on all three BO entities. Side effects are defined in the behavior
definition in the entity behavior body.
• For the travel entity, the following side effects are relevant:
• Whenever the field BookingFee is changed, the recalculation of the field TotalPrice must be
triggered to adjust the value with the new amount for the booking fee field.
• Whenever the field AgencyID is changed, the user must receive feedback if the used value is valid for
this field. This is validated by the validation validateAgency. To be able to define a trigger point for
the validation, it must firstly be defined in a determine action.
• Whenever the field CustomerID is changed, the user must receive feedback if the used value is valid
for this field. This is validated by the validation validateCustomer. To be able to define a trigger point
for the validation, it must firstly be defined in a determine action.
• Whenever the fields BeginDate and EndDate are changed, the user must receive feedback if the
used values are valid for these fields. This is validated by the validation validateDates. To be able to
define a trigger point for the validation, it must firstly be defined in a determine action.
• For the booking entity, the following side effects are described:
• Whenever the field FlightPrice is changed, the recalculation of the fieldTotalPriceof the travel
entity must be triggered to adjust the value with the new amount of the flight price field.
• For the booking supplement entity, the following side effects are described.
• Whenever the field BookSupplPrice is changed, the recalculation of the field TotalPrice of the
travel entity must be triggered to adjust the value with the new amount for the booking supplement
price field.
Defining Side Effects for the Travel Entity [page 653]

For the managed scenario with draft, define side effects on the travel entity for immediate feedback on
the Fiori Elements UI.
Defining Side Effects for the Booking Entity [page 656]

For the managed scenario with draft, define side effects on the booking entity for immediate feedback
on the Fiori Elements UI.
Defining Side Effects for the Booking Supplement Entity [page 656]
For the managed scenario with draft, define side effects on the booking entity for immediate feedback
on the Fiori Elements UI.
4.2.4.1.2.7.1 Defining Side Effects for the Travel Entity
For the managed scenario with draft, define side effects on the travel entity for immediate feedback on the Fiori
Elements UI.
Side Effects for Total Price Recalculation
The side effect triggers the recalculation of the Total Price on every change of the Booking Fee.

Develop PUBLIC 653
Define the side effect with field trigger and field target in the behavior body of the behavior definition.
 Sample Code

...
side effects

{ field BookingFee affects field TotalPrice; }
Whenever the Booking Fee is changed, the Total Price is reloaded and the determination to calculate the
total price is triggered.
Side Effect to Trigger the Validation of the AgencyID
The side effect triggers the validation that checks if the AgencyID is valid and reloads the respective
messages. To be able to define a trigger point for the side effect, it must firstly be defined in a determine
action.
 Note
The keyword side effects can only appear once in the behavior definition body. You have to define all
side effects for one entity together.
 Sample Code

...
{ ...
determine action AgencyValidation { validation validateAgency; }
side effects { field BookingFee affects field TotalPrice;
determine action AgencyValidation executed on field AgencyID
affects messages; }

… }
Whenever the AgencyID is changed the determine action is triggered, which calls the validation and the
messages are reloaded.
Side Effect to Trigger the Validation of the CustomerID
The side effect triggers the validation that checks if the CustomerID is valid and reloads the respective
messages. To be able to define a trigger point for the side effect, it must firstly be defined in a determine action.
 Note

654 PUBLIC Develop
 Sample Code

...
{ ...
determine action CustomerValidation { validation validateCustomer; }
determine action AgencyValidation executed on field
AgencyID affects messages;
determine action CustomerValidaiton executed on field
CustomerID affects messages;
}

… }
Whenever the CustomerID is changed the determine action is triggered, which calls the validation and the
messages are reloaded.
Side Effect to Trigger the Validation of the Dates
The side effect triggers the validation that checks if the BeginDate and the EndDate is valid and reloads the
respective messages. To be able to define a trigger point for the side effect, it must firstly be defined in a
determine action.
 Note
 Sample Code

...
{ ...
determine action CustomerValidation { validation validateCustomer; }
determine action DatesValidation { validation validateDates; }
determine action AgencyValidation executed on field
AgencyID affects messages;
determine action CustomerValidaiton executed on field
CustomerID affects messages;
determine action DatesValidation executed on field
BeginDate, field EndDate affects messages;
}

… }
Whenever the BeginDate or the EndDate is changed the determine action is triggered, which calls the
validation and the messages are reloaded.

Develop PUBLIC 655
4.2.4.1.2.7.2 Defining Side Effects for the Booking Entity
For the managed scenario with draft, define side effects on the booking entity for immediate feedback on the
Fiori Elements UI.
The side effect triggers the recalculation of the Total Price on every change of the Flight Price.
Define the side effect with field trigger and field target in the behavior body of the behavior definition on the
booking entity.
 Sample Code
define behavior for /DMO/R_Booking_D alias Travel

...
{ ...
side effects { field FlightPrice affects field _Travel.TotalPrice;; }

… }
Whenever the Flight Price is changed on the booking entity, the Total Price on the travel entity is
reloaded and the determination to calculate the total price is triggered.
4.2.4.1.2.7.3 Defining Side Effects for the Booking

Supplement Entity
For the managed scenario with draft, define side effects on the booking entity for immediate feedback on the
Fiori Elements UI.
The side effect triggers the recalculation of the Total Price on every change of the BookSupplPrice.
Define the side effect with field trigger and field target in the behavior body of the behavior definition on the
booking booking supplements.
 Sample Code

...
{ ...
side effects { field BookSupplPrice affects field _Travel.TotalPrice;; }

… }

656 PUBLIC Develop
Whenever the BookSupplPrice is changed on the booking supplement entity, the Total Price on the travel
entity is reloaded and the determination to calculate the total price is triggered.
4.2.4.2 Exposing the Managed Business Object for a UI

Business Service
In the previous chapters, you have created a managed business object from scratch. To expose it as a business
service the following steps are relevant:
1. Projecting the Managed BO for Non-Draft Exposure [page 657]

2. Defining and Publishing a UI Service [page 667]
4.2.4.2.1 Projecting the Managed BO for Non-Draft

Exposure
For the managed scenario with draft, create a projection layer for the managed BO.
Whereas the business object that we have created so far is service agnostic, the business object projection is
an approach to define a subset of this business object as service-specific for the UI use case. In this scenario,
we want to publish a UI service, so UI-specifics are defined in the BO projection. For more information about
the BO projection layer, see Business Object Projection [page 198].
For the travel demo scenario, define the data model and the behavior projection:
• For the data model projection, the following steps are relevant:
• Create CDS projection views.
In the CDS projection views define UI-service-specific features, such as search capabilities, text
associations, and value helps.
• Create metadata extensions.
Metadata extensions are primarily used to define the annotations that are relevant for the UI design.
They are outsourced in metadata extension to obtain an easy approach for layering.
For a detailed description on how to define data model projection features, see Projecting the BO Data
Model [page 658].
• For the behavior projection, the following steps are relevant:
• Create a projection behavior definition.
For a detailed description on behavior projection features, see Projecting the BO Behavior [page 666].

Develop PUBLIC 657
4.2.4.2.1.1 Projecting the BO Data Model
For the managed scenario with draft, create and implement CDS projection views and metadata extensions for
the BO entities.
Create data definition for projection views for all three BO entities Travel, Booking, and Booking Supplement.
In ADT, use the context menu on the underlying CDS view entity to open the wizard for creating CDS data
definition. For a detailed step-by-step description, see .
Select the template Define Projection View.
 Note
The draft scenario in the ABAP Flight Reference Scenario uses the suffix _D. Since the CDS projection
views only represent the active UI service, we use the marker _A before the suffix to distinguish the
active projection layer from the projection layer that includes draft. In addition, projection views carry the
prefix C_ as they represent the consumption layer. For more information, see Naming Conventions for
Development Objects [page 306].
For each projection view, create a metadata extension. In ADT, right-click on the data definition to open the
creation wizard for metadata extensions. For more information, see .
 Note
According to the virtual data model (VDM) guidelines, the metadata extension use the same name as the
related CDS view.
Documentation).
Projection View /DMO/C_Travel_A_D
The projection view is a projection on /DMO/R_Travel_D. Include the keyword root in the projection view.
Use all elements of the underlying BO travel entity. You do not need to use the administrative data in the
projection view, except for the element representing the ETag master.
Enable the usage of a metadata extension with the annotation @Metadata.allowExtension:true.
Enable search capabilities for the travel entity, with the @Search annotations on the entity header and on
designated elements. For more information, see Enabling Text and Fuzzy Searches in SAP Fiori Apps [page
897].
To indicate that TravelID is the semantic identifier of the BO-entity, use the annotation
@ObjectModel.semanticKey: ['TravelID'] in the header of the projection view.

658 PUBLIC Develop
To retrieve the long texts of the ID elements CustomerID, AgencyID, and OverallStatus denormalize the
text elements from the associated text provider views into the projection view. For more information, see
Getting Language-Dependent Text in Projection Views [page 895].
Define value helps for the elements CustomerID, AgencyID, CurrencyCode, and OverallStatus. For more
As soon as all projection views of the composition structure of the business object are available, redirect the
composition to child to the projection view of the booking entity.
 Expand the following code sample to view the source code of Projection View /DMO/C_Travel_A_D.
 Sample Code
@EndUserText.label: 'Travel Projection View for Draft RefScen'


define root view entity /DMO/C_Travel_A_D


as projection on /DMO/R_Travel_D

{
key TravelUUID,
TravelID,


AgencyID,


CustomerID,
BeginDate,
EndDate,
BookingFee,
TotalPrice,
CurrencyCode,
Description,

@Consumption.valueHelpDefinition: [{ entity: {name: '/DMO/
I_Overall_Status_VH', element: 'OverallStatus' } }]

OverallStatus,
LocalLastChangedAt,
/* Associations */
_Agency,

_Booking : redirected to composition child /DMO/C_Booking_A_D,

_Currency,
_OverallStatus,
_Customer
}


Develop PUBLIC 659
Metadata Extension /DMO/C_Travel_A_D
Define the metadata extension as extension of the CDS projection view /DMO/C_Travel_A_D.
Define the layer #CORE.
Use all the @UI annotations to design the user interface for the travel app. For more information, see Defining
CDS Annotations for Metadata-Driven UIs [page 786].
To trigger actions via action buttons on the UI, use @UI annotations for data action on both the list report
page and the object page. It is not important which element is annotated with this annotation, the action
button always appears on the upper right corner on the UI. To enable multi-inline editing on the list report
page, annotate the action Deduct_Discount with @UI.lineIte.invocationGrouping: #CHANGE_SET.
The action is then processed for all selected instances in once change set.
 Expand the following code sample to view the source code of Metadata Extension /DMO/C_Travel_A_D.
 Sample Code

title: { type: #STANDARD, value: 'TravelID' } },
presentationVariant: [{ sortOrder: [{ by: 'TravelID', direction:
#DESC }] }] }

annotate entity /DMO/C_Travel_A_D

with
{
@UI.facet: [{ id: 'Travel',
purpose: #STANDARD,
label: 'Travel',
position: 10 },
{ id: 'Booking',
purpose: #STANDARD,
label: 'Booking',
position: 20,
@UI.hidden: true
TravelUUID;
@UI: { lineItem: [ { position: 10, importance: #HIGH },

label: 'Reject Travel' },
{ type: #FOR_ACTION, dataAction: 'deductDiscount',
label: 'Deduct Discount', invocationGrouping: #CHANGE_SET } ],
identification: [ { position: 10, label: 'Travel ID' },
label: 'Deduct Discount' } ],
TravelID;
@UI: { lineItem: [ { position: 20, importance: #HIGH } ] ,
AgencyID;

660 PUBLIC Develop
CustomerID;
@UI: { lineItem: [ { position: 40, importance: #MEDIUM } ] ,
BeginDate;
EndDate;

BookingFee;
TotalPrice;
// CurrencyCode;

Description;

selectionField: [ { position: 40 } ] ,
OverallStatus;
@UI.hidden: true
OverallStatusText;
@UI.hidden: true
LocalLastChangedAt;

}
Projection View /DMO/C_Booking_A_D
The projection view is a projection on /DMO/R_Booking_D.
Use all elements of the underlying BO travel entity, in particular the element representing the ETag master.
Enable search capabilities for the booking entity, with the @Search annotations. For more information, see
To retrieve the long texts of the ID elements CustomerID, CarrierID, and BookingStatus denormalize
the text elements from the associated text provider views into the projection view. For more information, see
Getting Language-Dependent Text in Projection Views [page 895].
Define value helps for the elements CustomerID, AirlineID, ConnectionID, FlightDate, CurrencyCode,
and BookingStatus. For more information, see Providing Value Help [page 776].
composition to child to the projection view of the booking entity and the association to the root entity to the
respective projection view.
 Expand the following code sample to view the source code of Projection View /DMO/C_Booking_A_D.

Develop PUBLIC 661
 Sample Code
@EndUserText.label: 'Booking Proj View for Draft RefScen'


define view entity /DMO/C_Booking_A_D

as projection on /DMO/R_Booking_D

{
key BookingUUID,
TravelUUID,
BookingID,
BookingDate,


CustomerID,


AirlineID,


additionalBinding: [ { localElement: 'FlightDate',
element: 'FlightDate'},
{ localElement: 'AirlineID',
element: 'AirlineID'},
{ localElement: 'FlightPrice',
element: 'Price', usage: #RESULT},
{ localElement: 'CurrencyCode',
element: 'CurrencyCode', usage: #RESULT } ] } ]
ConnectionID,
FlightDate,


element: 'Price', usage: #RESULT },
FlightPrice,
CurrencyCode,

@Consumption.valueHelpDefinition: [{entity: {name: '/DMO/

BookingStatus,
_BookingStatus._Text.Text as BookingStatusText: localized,
LocalLastChangedAt,
/* Associations */

_BookingSupplement: redirected to composition child /DMO/
C_BookingSupplement_A_D,

_BookingStatus,
_Carrier,
_Connection,
_Customer,

_Travel: redirected to parent /DMO/C_Travel_A_D

}

662 PUBLIC Develop

Metadata Extension /DMO/C_Booking_A_D
Define the metadata extension as extension of the CDS projection view /DMO/C_Booking_A_D.
 Expand the following code sample to view the source code of Metadata Extension /DMO/C_Booking_A_D.
 Sample Code

@UI: { headerInfo: { typeName: 'Booking',

annotate entity /DMO/C_Booking_A_D with

{
purpose: #STANDARD,
label: 'Booking',
position: 10 },
purpose: #STANDARD,
position: 20,
targetElement: '_BookingSupplement'} ]
@UI.hidden: true
BookingUUID;
@UI.hidden: true
TravelUUID;

BookingID;

BookingDate;

CustomerID;

AirlineID;

ConnectionID;

FlightDate;

Develop PUBLIC 663
FlightPrice;
// CurrencyCode;
BookingStatus;
@UI.hidden: true
BookingStatusText;
@UI.hidden: true
LocalLastChangedAt;

}
Projection View /DMO/C_BookingSupplement_A_D
The projection view is a projection on /DMO/R_BookingSupplement_D.
Enable search capabilities for the travel entity, with the @Search annotations. For more information, see
To retrieve the long texts of the ID element SupplementID, denormalize the text element from the associated
text provider view into the projection view. For more information, see Getting Language-Dependent Text in
Projection Views [page 895].
Define value helps for the elements SupplementID and CurrencyCode. For more information, see Providing
Value Help [page 776].
association to the parent to the projection view of the booking entity and the association to the root entity to
the respective projection view.
 Expand the following code sample to view the source code of Projection View /DMO/
C_BookingSupplement_A_D.
 Sample Code
@EndUserText.label: 'BookingSuppl Proj View for Draft RefScen'


define view entity /DMO/C_BookingSupplement_A_D

as projection on /DMO/R_BookingSupplement_D

{
key BookSupplUUID,
TravelUUID,
BookingUUID,
BookingSupplementID,


664 PUBLIC Develop
@Consumption.valueHelpDefinition: [ {entity: {name: '/DMO/
I_Supplement', element: 'SupplementID' } ,

additionalBinding: [ { localElement: 'BookSupplPrice',
element: 'CurrencyCode', usage: #RESULT }] }] }]
SupplementID,
_SupplementText.Description as SupplementDescription : localized,
BookSupplPrice,
CurrencyCode,
LocalLastChangedAt,
/* Associations */

_Booking : redirected to parent /DMO/C_Booking_A_D,

_Product,
_SupplementText,

_Travel : redirected to /DMO/C_Travel_A_D

}

Metadata Extension /DMO/C_BookingSupplement_A_D
Define the metadata extension as extension of the CDS projection view /DMO/C_BookingSupplement _A_D.
 Expand the following code sample to view the source code of Metadata Extension /DMO/
C_BookingSupplement_A_D.
 Sample Code


annotate entity /DMO/C_BookingSupplement_A_D

with
{
purpose: #STANDARD,
position: 10 } ]
@UI.hidden:true
BookSupplUUID;
@UI.hidden:true
BookingUUID;
@UI.hidden:true
TravelUUID;

Develop PUBLIC 665
SupplementID;
BookSupplPrice;
// CurrencyCode;
@UI.hidden: true
LocalLastChangedAt;

}
4.2.4.2.1.2 Projecting the BO Behavior
For the managed scenario with draft, create a projection behavior definition for defining the projection
behavior.
Create a projection behavior definition for the travel business object. In ADT, use the context menu of the root
projection view to open the wizard for creating behavior definitions. The implementation type is prefilled with
Projection. For a more detailed description, see .
Projection Behavior Definition /DMO/C_Travel_A_D
Use the complete behavior that was defined in the underlying behavior definition for the non-draft BO
projection.
C_Travel_A_D.
 Sample Code
projection;

strict(2);
use side effects;

define behavior for /DMO/C_Travel_A_D alias Travel

use etag
{
use create;
use update;
use delete;
use action deductDiscount;
use association _Booking { create; }
}

define behavior for /DMO/C_Booking_A_D alias Booking

use etag
{
use update;
use delete;

666 PUBLIC Develop
use association _BookingSupplement { create; }
}

define behavior for /DMO/C_BookingSupplement_A_D alias BookingSupplement

use etag
{
use update;
use delete;

}
4.2.4.2.2 Defining and Publishing a UI Service
For the managed scenario with draft, define a UI service and bind it to a protocol.
To address the managed BO from the ABAP-external world, it must be exposed as a business service to OData.
In the service definition, you define which artifacts are included in the service. The service binding defines the
protocol with which the service is addressed. In addition, it provides the means to activate the service locally.
The Fiori Elements App Preview can be used as soon as the service is activated.
Create a service definition for the non-draft business service. For more information, see .
Based on the service definition, create a service binding. For more information, see . You can choose between
OData V2 and V4 protocol to expose a UI service.
 Note
The draft scenario in the ABAP Flight Reference Scenario uses the suffix _D. To distinguish the active-only
service from the service with draft, we use the addition _A before the suffix. For more information, see
Naming Conventions for Development Objects [page 306].
Service Definition /DMO/UI_TRAVEL_A_D
Include the projection views of the business object and all related CDS entities that are relevant for UI
consumption into the service definition.
 Expand the following code sample to view the source code of Service Definition /DMO/UI_TRAVEL_A_D.
 Sample Code
@EndUserText.label: 'Travel Draft Scenario(active projection)'

@ObjectModel.leadingEntity.name: '/DMO/C_Travel_A_D'

define service /DMO/UI_TRAVEL_A_D {

expose /DMO/C_Travel_A_D as Travel;

expose /DMO/C_Booking_A_D as Booking;


Develop PUBLIC 667
expose /DMO/C_BookingSupplement_A_D as BookingSupplement;









expose /DMO/I_Overall_Status_VH as OverallStatusVH;



}
Service Binding /DMO/UI_TRAVEL_A_D_O2
Expose the service as a UI service with OData protocol V2 and publish it locally. You can then use the preview to
test the service.
4.2.4.3 Draft-Enabling the Managed Business Object
You can now draft-enable the managed business object with a few additions in the behavior definition.
In draft business objects, the implementation of the business logic must be able to handle request for draft and
for active instances. Above all, the implementation must be able to differentiate those requests.
The business object receives the information if a request is aimed at draft or active instances via the draft
indicator %IS_DRAFT. This draft indicator is a component of the primary key in all incoming requests in draft
scenarios. The transactional key %tky includes the draft indicator. So in draft scenarios, it is best practice to
use %tky for referring to the primary key, as the indicator for drafts or non-drafts is already included there. In
non-draft scenarios, the transactional key %tky comprises just the primary key information.
If you consequently use the derived type %tky to refer to the key of instances in your implementation,
draft-enabling is just done in the behavior definition with a few additional syntax elements. The draft indicator
%is_draft is added as a key component to %tky in draft scenarios. This means, the implementation receives
the information if the request is aimed at draft or active instances. So, you do not have to adjust your
implementation in draft scenarios.
The following steps are necessary to draft-enable a managed business object: Adding Draft Capabilities to the
Managed Business Object [page 669]

668 PUBLIC Develop
4.2.4.3.1 Adding Draft Capabilities to the Managed
Business Object
For the managed scenario with draft, add draft behavior to the behavior definition.
In the previous sections of this development guide, you have developed a running business service with a
managed business object. Draft capabilities are included to the business service by adding the syntax element
with draft to the behavior definition. As soon as you use this keyword element in the behavior definition, you
are guided through the follow-up steps in the behavior definition by tool support. Syntax warnings and quick
fixes are available to adapt the managed business object to the draft prerequisites.
Draft-Enabled Business Objects Requirements
 Note
Business objects with implementation type unmanaged are draft-enabled in the same way.
Adaptions in the Behavior Definition
Follow these steps to draft-enable the travel business object:
1. Add the syntax element with draft to the header of the behavior definition.
 Note
You receive a syntax error that there is no draft persistence available for the draft BO.
2. Create a draft database table for the Travel entity by using the quick fix in the behavior definition:
• Define the draft database table in the behavior definition by using the keyword draft table and
specify the name for the draft database table.
In the example scenario, we use /DMO/D_TRAVEL_D.
 Note
The draft scenario in the ABAP Flight Reference Scenario uses the suffix _D. For the draft database
tables, we use the prefix D_ to indicate the draft persistence. For detailed information, see Naming
• Use the quick fix to create a database table with the specified name.

Develop PUBLIC 669
Quick Fix: Draft Table Generation
The wizard for creating database tables opens. When you finish the database table generation wizard,
the ADT tooling support automatically generates the table elements corresponding to the active
persistence. In addition, the draft admin structure include %admin is included in the database table.
For more information about the draft database table, see Draft Database Table [page 50].
• Add the annotation @AbapCatalog.anonymizedWhenDelivered : true to the elements that
store user information. (Only relevant for the travel draft table.)
 Expand the following code sample to view the source code of Database Table /DMO/D_TRAVEL_D.
 Sample Code
@EndUserText.label : 'Draft table for entity /DMO/R_Travel_D'

@AbapCatalog.enhancement.category : #EXTENSIBLE_ANY

define table /DMO/D_TRAVEL_D {

key traveluuid : sysuuid_x16 not null;
travelid : /dmo/travel_id;
agencyid : /dmo/agency_id;
customerid : /dmo/customer_id;
begindate : /dmo/begin_date;
enddate : /dmo/end_date;
@Semantics.amount.currencyCode : '/dmo/d_travel_d.currencycode'
bookingfee : /dmo/booking_fee;
@Semantics.amount.currencyCode : '/dmo/d_travel_d.currencycode'
totalprice : /dmo/total_price;
currencycode : /dmo/currency_code;
overallstatus : /dmo/overall_status;

}
3. Repeat the creation of draft database tables for the Booking entity and the BookingSupplement entity.
In the example scenario, we use the names /DMO/D_BOOKING_D and /DMO/D_BKSUPPL_D.
4. Define a total ETag field for the draft business object.
The total ETag is used to enable optimistic concurrency checks during the transition from draft to active
data.
• Add a total ETag field to the persistent database table of the Travel entity.
 Expand the following code sample to view the source code of Database Table /DMO/A_TRAVEL_D.

670 PUBLIC Develop
 Sample Code
@EndUserText.label : 'Active Travel Persistence for Draft Reference

Scenario'


define table /DMO/A_TRAVEL_D {

...

}
• Add the element in the CDS view entity /DMO/R_Travel_D and annotate it with the annotation
@Semantics.systemDateTime.lastChangedAt: true to allow the RAP runtime framework to
update it automatically.
 Expand the following code sample to view the source code of Database Table /DMO/R_Travel_D.
 Sample Code
@EndUserText.label: 'Travel View Entity for Draft RefScen'


define root view entity /DMO/R_Travel_D

as select from /DMO/A_TRAVEL_D

composition [0..*] of /DMO/R_Booking_D as _Booking




{ ///DMO/A_TRAVEL_D


Develop PUBLIC 671
//total ETag field
//Associations
_Booking,
_Agency,
_Customer,
_Currency

}
 Note
The total ETag field does not need to be included in the projection view. The ETag is only used for
internal processing of draft data and does not need to be exposed for the business service.
• Add the total ETag field to the mapping prescription in the behavior definition for the Travel entity.
 Expand the following code sample to view the source code of Database Table /DMO/R_Travel_D.
 Sample Code


...


EndDate = end_date;
LastChangedAt = last_changed_at;

}
• Regenerate the draft database table /DMO/D_TRAVEL_D to include the total ETag field. The behavior
definition provides a quick fix for the regeneration.
Quick Fix: Regeneration Draft Table

• Define the element LastChangedAt as total ETag in the behavior definition by using the keyword
total etag.

672 PUBLIC Develop
 Note
The definition of the total ETag is only possible directly after the lock master definition in the
 Sample Code
managed;

strict( 2 );
with draft;


implementation in class /DMO/BP_I_TRAVEL_D unique


draft table /DMO/D_TRAVEL_D

lock master
...
{

}
5. Explicitly draft-enable the compositions within the draft BO.

As soon as you draft-enable a business object by adding with draft to the behavior definition, all
BO-internal associations are automatically draft-enabled. To make this behavior explicit, the behavior
prompts you to specify the compositions within a draft BO with with draft.
For more information, see Draft-Enabled Associations [page 54].
6. Define the validations and determinations for the draft determine action Prepare.
The determinations and validations that are defined in the Prepare action are called before and during the
Activate action to transfer draft to active instances. For more information, see Preparing Draft Instances
for Activation [page 73].
• Define the Prepare action in the behavior definition.
• Include all validations that are defined for the travel BO in the Prepare
 Note
It is not generally necessary to include all validations in the Prepare action, but only those that
you want to check during the transition from draft to active.
 Sample Code
managed;

strict( 2 );
with draft;


...
draft determine action Prepare
{
validation validateAgency;
validation validateCustomer;
validation validateDates;
validation validateAuthOnCreate;
validation Booking ~ validateCustomer;
validation Booking ~ validateConnection;

validation Bookingsupplement ~ validateSupplement; }
 Expand the following code sample to view the source code of Behavior Definition /DMO/R_Travel_D.

Develop PUBLIC 673
 Sample Code
managed;

strict( 2 );
with draft;




draft table /DMO/D_TRAVEL_D

lock master
//authorization master ( instance )
{
create;
update;
delete;
association _Booking { create ( features : instance ); with draft; }
field ( readonly ) TravelID, OverallStatus, TotalPrice, LocalCreatedAt,
LocalCreatedBy, LocalLastChangedAt, LocalLastChangedBy;
field ( features : instance ) BookingFee;
action ( features : instance ) acceptTravel result [1] $self;
action ( features : instance ) rejectTravel result [1] $self;

action ( features : instance ) deductDiscount parameter /DMO/
A_TRAVEL_DISCOUNT result [1] $self;

determination setTravelNumber on save { create; }
determination setStatusToNew on modify { create; }
determination calculateTotalPrice on modify { create; field BookingFee,
CurrencyCode; }
validation validateAgency on save { create; field AgencyID; }
determine action validationAgency { validation validateAgency; }
determine action validationCustomer { validation validateCustomer; }
determine action validationDates { validation validateDates; }
side effects
{ field BookingFee affects field TotalPrice;
determine action validationAgency executed on field AgencyID affects
messages;
determine action validationCustomer executed on field CustomerID affects
messages;
determine action validationDates executed on field BeginDate, field
EndDate affects messages; }
draft action resume;
draft action Edit;
draft action Activate;
draft action Discard;
{
validation validateAgency;
validation Booking ~ validateCustomer;
validation Booking ~ validateConnection;
validation Bookingsupplement ~ validateSupplement; }


EndDate = end_date;

674 PUBLIC Develop
}



persistent table /DMO/A_BOOKING_D

draft table /DMO/D_BOOKING_D

//authorization dependent by <association>
{
update;
delete;
association _BookingSupplement { create ; with draft; }
association _Travel { with draft; }
field ( readonly ) TravelUUID, BookingID, BookingDate, LocalLastChangedAt;
determination setBookingDate on save { create; }
determination calculateTotalPrice on modify { create; field FlightPrice,
CurrencyCode; }
validation validateConnection on save { create; field AirlineID,
ConnectionID, FlightDate; }
side effects
{ field FlightPrice affects field _Travel.TotalPrice; }

mapping for /DMO/A_BOOKING_D

}



persistent table /DMO/A_BKSUPPL_D

draft table /DMO/D_BKSUPPL_D

{
update;
delete;
association _Booking { with draft; }
field ( readonly ) TravelUUID, BookingUUID, BookingSupplementID,
LocalLastChangedAt;
field ( mandatory ) SupplementID;
determination setBookSupplNumber on save { create; }
determination calculateTotalPrice on modify { create; field CurrencyCode,
BookSupplPrice; }
side effects

Develop PUBLIC 675
{ field BookSupplPrice affects entity _Travel; }

mapping for /DMO/A_BKSUPPL_D

{ BookSupplPrice = price;
BookSupplUUID = booksuppl_uuid;
BookingUUID = parent_uuid;
TravelUUID = root_uuid; }

}
 Note
Draft-enabled business objects require a feature control method in the behavior pool. If you do not use
dynamic feature control in your business logic, include the method declaration and an empty method
implementation. In Draft BOs, feature control is called for every request to determine whether draft or
active instances are requested.
Adaptions in the Behavior Pool

If you have consequently used %tky to refer to the key fields of instances, you shouldn't have to make changes
in the behavior implementation in general.
For authorization, it is different. When draft-enabling a business object, draft actions are implicitly added to the
BO behavior. There are two draft actions, which need to be considered in the authorization implementation as
they also call the authorization methods during their runtime, see Runtime Edit Action [page 62] and Runtime
Activate Action [page 65].
In this demo example, authorization for actions is handled exactly like the update operation. This can also be
applied for the draft actions Edit and Activate.
Add the relevant draft actions to the action mapping in the behavior implementation for global and instance
authorization.
 Expand the following code sample to view the source code of the method get_global_authorizations.

IF requested_authorizations-%create EQ if_abap_behv=>mk-on.
IF is_create_granted( ) = abap_true.
result-%create = if_abap_behv=>auth-allowed.
ELSE.
result-%create = if_abap_behv=>auth-unauthorized.


textid = /dmo/

error )
%global = if_abap_behv=>mk-on ) TO reported-travel.
ENDIF.
ENDIF.
"Actions are treated like update
IF requested_authorizations-%update = if_abap_behv=>mk-on OR
requested_authorizations-%action-Edit = if_abap_behv=>mk-on OR
requested_authorizations-%action-Prepare = if_abap_behv=>mk-on OR
requested_authorizations-%action-acceptTravel = if_abap_behv=>mk-on OR
requested_authorizations-%action-rejectTravel = if_abap_behv=>mk-on OR
requested_authorizations-%action-deductDiscount = if_abap_behv=>mk-on.
IF is_update_granted( ) = abap_true.
result-%update = if_abap_behv=>auth-allowed.
result-%action-Edit = if_abap_behv=>auth-allowed.

676 PUBLIC Develop
result-%action-Prepare = if_abap_behv=>auth-allowed.
result-%action-acceptTravel = if_abap_behv=>auth-allowed.
result-%action-rejectTravel = if_abap_behv=>auth-allowed.
result-%action-deductDiscount = if_abap_behv=>auth-allowed.
ELSE.
result-%update = if_abap_behv=>auth-unauthorized.
result-%action-Edit = if_abap_behv=>auth-unauthorized.
result-%action-Prepare = if_abap_behv=>auth-unauthorized.
result-%action-acceptTravel = if_abap_behv=>auth-unauthorized.
result-%action-rejectTravel = if_abap_behv=>auth-unauthorized.
result-%action-deductDiscount = if_abap_behv=>auth-unauthorized.


textid = /dmo/

error )
ENDIF.
ENDIF.
IF requested_authorizations-%delete = if_abap_behv=>mk-on.
IF is_delete_granted( ) = abap_true.
result-%delete = if_abap_behv=>auth-allowed.
ELSE.
result-%delete = if_abap_behv=>auth-unauthorized.


textid = /dmo/

error )
ENDIF.
ENDIF.
ENDMETHOD.

}
 Expand the following code sample to view the source code of the method get_instance_authorizations.
 Sample Code



ENTITY Travel
FIELDS ( AgencyID )
FAILED failed.
instance
"authorization only checked against instance that have active persistence

SELECT FROM /DMO/A_TRAVEL_D AS travel INNER JOIN /DMO/AGENCY AS agency

FOR ALL ENTRIES IN @travels WHERE travel_uuid EQ @travels-TravelUUID
"all actions are treated like update
requested_authorizations-%assoc-
_Booking = if_abap_behv=>mk-on OR
Edit = if_abap_behv=>mk-on OR

Develop PUBLIC 677
Prepare = if_abap_behv=>mk-on OR
acceptTravel = if_abap_behv=>mk-on OR
deductDiscount = if_abap_behv=>mk-on OR
rejectTravel = if_abap_behv=>mk-on
table
TravelUUID
"Auth check for active instances that have before image on persistent
table
IF sy-subrc = 0.
country_code ).


textid = /dmo/

severity =
%element-AgencyID = if_abap_behv=>mk-on ) TO
reported-travel.
ENDIF.
ENDIF.
country_code ).


textid = /dmo/

severity =
reported-travel.
ENDIF.
ENDIF.
" operations on draft instances and on active instances that have no
persistent before image (eg Update on newly created instance)
ELSE.


textid = /dmo/

error )
reported-travel.
ENDIF.

678 PUBLIC Develop
ENDIF.
APPEND VALUE #( LET upd_auth = COND #( WHEN update_granted = abap_true
THEN if_abap_behv=>auth-allowed
unauthorized )
del_auth = COND #( WHEN delete_granted = abap_true
unauthorized )
IN
%tky = travel-%tky
%update = upd_auth
%assoc-_Booking = upd_auth
%action-Prepare = upd_auth
%action-acceptTravel = upd_auth
%action-deductDiscount = upd_auth
%action-rejectTravel = upd_auth
%delete = del_auth
) TO result.
ENDLOOP.

ENDMETHOD.
 Expand the following code sample to view the source code of the method get_instance_authorizations.
 Sample Code



ENTITY Travel
FIELDS ( AgencyID )
FAILED failed.
instance
"authorization only checked against instance that have active persistence

SELECT FROM /DMO/A_TRAVEL_D AS travel INNER JOIN /DMO/AGENCY AS agency

FOR ALL ENTRIES IN @travels WHERE travel_uuid EQ @travels-TravelUUID
"all actions are treated like update
requested_authorizations-%assoc-
_Booking = if_abap_behv=>mk-on OR
Edit = if_abap_behv=>mk-on OR
Prepare = if_abap_behv=>mk-on OR
acceptTravel = if_abap_behv=>mk-on OR
deductDiscount = if_abap_behv=>mk-on OR
rejectTravel = if_abap_behv=>mk-on

Develop PUBLIC 679
table
TravelUUID
"Auth check for active instances that have before image on persistent
table
IF sy-subrc = 0.
country_code ).


textid = /dmo/

severity =
reported-travel.
ENDIF.
ENDIF.
country_code ).


textid = /dmo/

severity =
reported-travel.
ENDIF.
ENDIF.
" operations on draft instances and on active instances that have no
persistent before image (eg Update on newly created instance)
ELSE.


textid = /dmo/

error )
reported-travel.
ENDIF.
ENDIF.
APPEND VALUE #( LET upd_auth = COND #( WHEN update_granted = abap_true
unauthorized )
del_auth = COND #( WHEN delete_granted = abap_true
unauthorized )
IN
%tky = travel-%tky
%update = upd_auth

680 PUBLIC Develop
%assoc-_Booking = upd_auth
%action-Prepare = upd_auth
%action-acceptTravel = upd_auth
%action-deductDiscount = upd_auth
%action-rejectTravel = upd_auth
%delete = del_auth
) TO result.
ENDLOOP.

ENDMETHOD.
Result
As soon as you activate the behavior definition, the business object is draft-enabled. In general, that means:
• Transactional requests are processed by the draft runtime,

• The importing structures for all methods in the behavior pool receive an additional component, the
draft indicator %is_draft. In particular, the transactional key %tky determines whether the operation
is executed on a draft or on an active instance.
• The draft actions are implicitly available and applied during the draft life cycle.
• The existing UI service does not change as long as you do not include the draft capabilities in the projection
behavior definition. It still behaves like a non-draft business service. The underlying draft BO processes
every request with the draft indicator is_draft set to false.
For more information, see Draft Runtime [page 56].
The conversion to a draft business object sometimes requires follow-up activities of existing implementations
in the business logic. In general, scan the existing code thoroughly to detect cases where you need to
differentiate between active and draft processing.
If the transactional key %tky is used for referring to the key components, no adaptation is necessary for these
implementations. The %is_draft is automatically added as key component to the %tky structure.
4.2.4.4 Exposing the Draft Business Object for a UI

Business Service
In the previous chapters, you have created a draft business object by draft-enabling a managed business
object. Since the managed business object projection without draft capabilities remains untouched, it
continues to operate only on active instances.
If you want to have a business service with draft capabilities, you can either add the draft features to the
existing business object projection or create a new projection for the draft service. This is done in this demo
scenario. In the end, you have two parallel business services, one for active only and one that includes draft
features. To expose the draft business as a business service the following steps are relevant:
• Projecting the Draft BO for Draft Exposure [page 682]

• Defining and Publishing a UI Service with Draft Capabilities [page 692]

Develop PUBLIC 681
4.2.4.4.1 Projecting the Draft BO for Draft Exposure
For the managed scenario with draft, create a projection layer for the draft BO.
In the first part of this development guide, you have created a non-draft business service based on a
managed business object. The business object projection includes all elements in the data model and the
behavior features that are relevant for the UI service. This projection remains stable, even when you add draft
capabilities to the basic business object. The projection layer filters out the elements and behavior features
that are draft-specific as they are not included in the projection.
To expose the draft business object for a UI service, it is necessary that you define a business object projection
that also includes the draft specific features. For more information about the BO projection layer, see Business
Object Projection [page 198].
For the travel demo scenario, define the data model and the behavior projection for the draft projection:
• For the data model projection, the following steps are relevant:
• Create CDS projection views.
In the CDS projection views define UI-service-specific features, such as search capabilities, text
associations, and value helps.
• Create metadata extensions.
Metadata extensions are primarily used to define the annotations that are relevant for the UI design.
They are outsourced in metadata extension to obtain an easy approach for layering.
For a detailed description on how to define data model projection features, see Projecting the BO Data
Model [page 658].
• For the behavior projection, the following steps are relevant:
• Create a projection behavior definition.
For a detailed description on behavior projection features, see Projecting the BO Behavior [page 666].
4.2.4.4.1.1 Projecting the Draft BO Data Model
For the managed scenario with draft, create and implement CDS projection views and metadata extensions for
the draft BO entities.
Create data definition for projection views for all three BO entities Travel, Booking, and Booking Supplement.
In ADT, use the context menu on the underlying CDS view entity to open the wizard for creating CDS data
definition. For a detailed step-by-step description, see .

682 PUBLIC Develop
 Note
The draft scenario in the ABAP Flight Reference Scenario uses the suffix _D. Since the new CDS projection
views represent the UI service with draft capabilities, we use the marker _D before the suffix to distinguish
the active projection layer from the projection layer that includes draft. In addition, projection views carry
the prefix C_ as they represent the consumption layer. For more information, see Naming Conventions for
Development Objects [page 306].
For each projection view, create a metadata extension. In ADT, right-click on the data definition to open the
creation wizard for metadata extensions.
 Note
According to the virtual data model (VDM) guidelines, the metadata extension use the same name as the
related CDS view.
Documentation).
Projection View /DMO/C_Travel_D_D
897].
For the OData V4 consumption of a draft business object via a Fiori Elements UI, the annotation
@ObjectModel.semanticKey: ['SemanticIdentifier'] must be used to ensure that draft indications
on the instance are displayed.
To retrieve the long texts of the ID elements CustomerID, AgencyID, and OverallStatus denormalize the
text elements from the associated text provider view into the projection view. For more information, see Getting
Language-Dependent Text in Projection Views [page 895].
Define value helps for the elements CustomerID, AgencyID, CurrencyCode and OverallStatus. For more
In contrast to the ETag master field, which is necessary to ensure optimistic concurrency control in the OData
consumption, you do not need to include the total ETag field in the draft business service projection. The total
ETag is only necessary for internal draft processing.
composition to child to the projection view of the booking entity.
 Expand the following code sample to view the source code of Projection View /DMO/C_Travel_D_D.

Develop PUBLIC 683
 Sample Code
@EndUserText.label: 'Travel Projection View with Draft'

@ObjectModel.semanticKey: ['TravelID']

define root view entity /DMO/C_Travel_D_D



{
key TravelUUID,
TravelID,


AgencyID,


CustomerID,
BeginDate,
EndDate,
BookingFee,
TotalPrice,
CurrencyCode,
Description,

@Consumption.valueHelpDefinition: [{ entity : {name: '/DMO/
I_Overall_Status_VH', element: 'OverallStatus' } }]

OverallStatus,
_OverallStatus._Text.Text as OverallStatusText: localized,
LocalLastChangedAt,
/* Associations */
_Agency,

_Booking : redirected to composition child /DMO/C_Booking_D_D,

_Currency,
_Customer,
_OverallStatus
}

Metadata Extension /DMO/C_Travel_D_D
Define the metadata extension as extension of the CDS projection view /DMO/C_Travel_A_D.
 Expand the following code sample to view the source code of Metadata Extension /DMO/C_Travel_D_D.

684 PUBLIC Develop
 Sample Code

title: { type: #STANDARD, value: 'TravelID' } },
presentationVariant: [{ sortOrder: [{ by: 'TravelID', direction:
#DESC }], visualizations: [{type: #AS_LINEITEM}] }] }

annotate entity /DMO/C_Travel_D_D with

{
@UI.facet: [{ id: 'Travel',
purpose: #STANDARD,
label: 'Travel',
position: 10 },
{ id: 'Booking',
purpose: #STANDARD,
label: 'Booking',
position: 20,
@UI.hidden: true
TravelUUID;
@UI: { lineItem: [ { position: 10, importance: #HIGH },
label: 'Deduct Discount', invocationGrouping: #CHANGE_SET } ],
identification: [ { position: 10, label: 'Travel ID' },
label: 'Deduct Discount' } ],
TravelID;
AgencyID;
CustomerID;
BeginDate;
EndDate;
BookingFee;
TotalPrice;
// CurrencyCode;
Description;

Develop PUBLIC 685
OverallStatus;
@UI.hidden: true
OverallStatusText;
@UI.hidden: true
LocalLastChangedAt;

}
Projection View /DMO/C_Booking_D_D
Enable search capabilities for the booking entity, with the @Search annotations. For more information, see
To retrieve the long texts of the ID elements CustomerID and CarrierID, denormalize the text elements
from the associated text provider views into the projection view. For more information, see Getting Language-
Dependent Text in Projection Views [page 895].
Define value helps for the elements CustomerID, AirlineID, ConnectionID, FlightDate, and
CurrencyCode. For more information, see Providing Value Help [page 776].
composition to child to the projection view of the booking entity and the association to the root entity to the
 Expand the following code sample to view the source code of Projection View /DMO/C_Booking_D_D.
 Sample Code
@EndUserText.label: 'Booking Proj View with Draft'

@ObjectModel.semanticKey: ['BookingID']

define view entity /DMO/C_Booking_D_D

as projection on /DMO/R_Booking_D

{
key BookingUUID,
TravelUUID,
BookingID,
BookingDate,


CustomerID,


AirlineID,


686 PUBLIC Develop

element: 'Price', usage: #RESULT},
ConnectionID,
FlightDate,


FlightPrice,
CurrencyCode,

@Consumption.valueHelpDefinition: [{entity: {name: '/DMO/

BookingStatus,
_BookingStatus._Text.Text as BookingStatusText: localized,
LocalLastChangedAt,
/* Associations */

C_BookingSupplement_D_D,

_BookingStatus,
_Carrier,
_Connection,
_Customer,

_Travel: redirected to parent /DMO/C_Travel_D_D

}
Metadata Extension /DMO/C_Booking_D_D
Define the metadata extension as extension of the CDS projection view /DMO/C_Booking_D_D.
 Expand the following code sample to view the source code of Metadata Extension View /DMO/
C_Booking_D_D.
 Sample Code

@UI: { headerInfo: { typeName: 'Booking',

annotate entity /DMO/C_Booking_D_D with


Develop PUBLIC 687
{
purpose: #STANDARD,
label: 'Booking',
position: 10 },
purpose: #STANDARD,
position: 20,
targetElement: '_BookingSupplement'} ]
@UI.hidden: true
BookingUUID;
@UI.hidden: true
TravelUUID;
BookingID;
BookingDate;
CustomerID;
AirlineID;
ConnectionID;
FlightDate;
FlightPrice;
// CurrencyCode;
BookingStatus;
@UI.hidden: true
BookingStatusText;
@UI.hidden: true
LocalLastChangedAt;

}
Projection View /DMO/C_BookingSupplement_D_D
Enable search capabilities for the travel entity, with the @Search annotations. For more information, see

688 PUBLIC Develop
To retrieve the long texts of the ID element SupplementID, denormalize the text element from the associated
text provider view into the projection view. For more information, see Getting Language-Dependent Text in
Define value helps for the elements SupplementID and CurrencyCode. For more information, see Providing
Value Help [page 776].
association to the parent to the projection view of the booking entity and the association to the root entity to
the respective projection view.
C_BookingSupplement_D_D.
 Sample Code
@EndUserText.label: 'BookingSuppl Proj View for Draft RefScen'

@ObjectModel.semanticKey: ['BookingSupplementID']

define view entity /DMO/C_BookingSupplement_D_D

as projection on /DMO/R_BookingSupplement_D

{
key BookSupplUUID,
TravelUUID,
BookingUUID,

@Consumption.valueHelpDefinition: [ {entity: {name: '/DMO/
I_Supplement', element: 'SupplementID' } ,

additionalBinding: [ { localElement: 'BookSupplPrice',
element: 'CurrencyCode', usage: #RESULT }] }]
SupplementID,
BookSupplPrice,
CurrencyCode,
LocalLastChangedAt,
/* Associations */

_Booking : redirected to parent /DMO/C_Booking_D_D,

_Product,
_SupplementText,

_Travel : redirected to /DMO/C_Travel_D_D

}

Metadata Extension /DMO/C_BookingSupplement_D_D
Define the metadata extension as extension of the CDS projection view /DMO/C_BookingSupplement_D_D.

Develop PUBLIC 689
 Sample Code


annotate entity /DMO/C_BookingSupplement_D_D

with
{
purpose: #STANDARD,
position: 10 } ]
@UI.hidden:true
BookSupplUUID;
@UI.hidden:true
BookingUUID;
@UI.hidden:true
TravelUUID;
SupplementID;
BookSupplPrice;
// CurrencyCode;
@UI.hidden: true
LocalLastChangedAt;
}

4.2.4.4.1.2 Projecting the Draft BO Behavior
For the managed scenario with draft, create a projection behavior definition for defining the projection
behavior.
Create a projection behavior definition for the travel business object. In ADT, use the context menu of the root

690 PUBLIC Develop
Projection Behavior Definition /DMO/C_Travel_D_D
Use the complete behavior that was defined in the underlying behavior definition for the draft BO projection.
(The template does not include everything, some features must be added manually.)
C_Travel_D_D.
 Sample Code
projection;

strict;
use draft;

define behavior for /DMO/C_Travel_D_D alias Travel

use etag
{
use create;
use update;
use delete;
use action Edit;
use action Activate;
use action Discard;
use action Prepare;
use action Resume;
use association _Booking { create; with draft; }
}

define behavior for /DMO/C_Booking_D_D alias Booking

use etag
{
use update;
use delete;
use association _BookingSupplement { create; with draft; }
use association _Travel { with draft; }
}

define behavior for /DMO/C_BookingSupplement_D_D alias BookingSupplement

use etag
{
use update;
use delete;
use association _Booking { with draft; }

}

Develop PUBLIC 691
4.2.4.4.2 Defining and Publishing a UI Service with Draft
Capabilities
For the managed scenario with draft, define a UI service and bind it to a protocol.
To address the draft BO from the ABAP-external world, it must be exposed as a business service to OData. In
the service definition, you define which artifacts are included in the service. The service binding defines the
protocol with which the service is addressed. In addition, it provides the means to activate the service locally.
The Fiori Elements App Preview can be used as soon as the service is activated.
Create a service definition for the draft business service. For more information, see .
Based on the service definition, create a service binding. For more information, see .
UI services of draft business objects with Fiori Elements are only supported with OData V4. Fiori Elements
cannot handle the full scope of draft services that are exposed with OData V2.
 Note
The draft scenario in the ABAP Flight Reference Scenario uses the suffix _D. To distinguish the draft service
from the service with draft, we use the addition _D before the suffix. For more information, see Naming
Service Definition /DMO/UI_TRAVEL_D_D
Include the projection views of the business object and all related CDS entities that are relevant for UI
 Sample Code
@EndUserText.label: 'Travel Draft Scenario (draft projection)'

@@ObjectModel.leadingEntity.name: '/DMO/C_Travel_D_D'

define service /DMO/UI_TRAVEL_D_D {

expose /DMO/C_Travel_D_D as Travel;

expose /DMO/C_Booking_D_D as Booking;

expose /DMO/C_BookingSupplement_D_D as BookingSupplement;









expose /DMO/I_Overall_Status_VH as OveallStatusVH;


692 PUBLIC Develop


}
Service Binding
test the service.
4.2.5 Developing Transactional Apps with Multi-Inline-Edit

Capabilities
The following section guides you through the implementation steps to create an application with multi-inline-
edit capabilities.
Introduction
Multi-inline-edit capabilities are always necessary if you want the end user of a UI app to be able to edit, add,
and delete all instances directly on a Fiori UI list report without navigating to the object page of one instance.
It is always relevant for customizing and maintaining complete table data. Multi-inline-capabilities on the UI
represent the same feature scope as transaction SM30 in SAP GUI.
The following preview displays a multi-inline-edit app for maintaining and administrating flight carrier
information. All instances can be edited on the same screen in inline mode. New instances can be added
or deleted via the create and delete button on the UI.
 Expand the following item to view an animated GIF of Multi-Inline-Editing on a Fiori UI.

Develop PUBLIC 693
Multi-Inline-Editing on a Fiori UI
Technical Architecture of a Multi-Inline-Edit App
The technical requirements of a RAP BO that enables multi-inline-editing on a Fiori Elements UI app are defined
by the structure of the Fiori Elements UI. A simple list reporting app consists of a list report page, on which all
instances of the root view entity are displayed. From any instance, you can navigate to its object page, which
displays all the instances of the child entity in a list, if the UI facet of the object page is modeled correctly.
The list of child instances can always be edited in multi-inline-edit mode, which means by choosing Edit on the
instance's object page, all fields of every child instance are editable at the same time. In this multi-inline-edit
mode, you can change fields of different instances and then save the complete composition structure (root
entity instance and all its child instances) at the same time. Since RAP BOs use a lock master/dependent
mechanism, it is ensured that by choosing the Edit button, all instance of the child entity are locked.
The existing multi-inline-edit capabilities of the list of child instances are used to enable multi-inline-editing also
for standalone master data entities. In this case, standalone refers to entities that are by default root entities in
a RAP BO.
To enable multi-inline-editing also for default root view entities, RAP offers the solution to model a technical
root entity with just one instance, from which you can navigate to its object page. This singleton pattern
provides a single-entrance point to all master data instances. The technical root entity also provides the
technical requirement of a lock master entity, which is essential for multi-inline-editing on the child entity. The
master data entity is then modeled as a child entity in order to enable the standard multi-inline-edit capabilities
of the object page of a UI. Like this, you can edit the master data of all instances at the same time.

694 PUBLIC Develop
In other words, for this scenario, you need to model a root entity with a single instance which has a composition
to the master data entity that is editable as a list on the object page of the single root instance on the UI.
Multi-Inline-Scenario with Singleton Pattern in RAP BO
 Note
You cannot expose the same business object in a regular list report app and in a multi-inline-edit-enabled
app at the same time. To expose a BO as a multi-inline-edit-scenario, a dummy root entity needs to be
introduced and changes the common BO structure drastically.
Example Scenario
This example scenario develops an app to configure airline master data of the flight reference scenario. The
master data contains the airline ID, the full name and the currency code that the airline uses. The data of all
airlines shall be editable at the same time on one list.
The scenario is based on the database table /dmo/carrier and the interface view /DMO/I_Carrier. The
transactional view /DMO/I_Carrier_S of the new business object selects from the interface view and thus,
the new BO is built on it.
This development guide illustrates how a BO for a multi-inline-edit scenario is developed from scratch. It does
not show development steps to migrate a regular business object into a business object for a multi-inline-edit
scenario.
The example scenario can be downloaded into your system from Git Hub. You find the carrier multi-inline-edit
scenario in the package /DMO/FLIGHT_REAUSE_CARRIER.

Develop PUBLIC 695
Prerequisites

 Restriction
Development Steps
Defining the Data Model and the Business Object Structure [page 696]
The multi-inline-edit scenario uses flight carrier master data of the ABAP Flight Reference Scenario.
The final app processes carrier data in multi-inline-edit mode.
Developing Transactional Behavior [page 700]

The multi-inline-edit scenario implements some standard behavior for draft BOs and additional specific
behavior that is required to enable multi-inline-editing on the UI.
Projecting the BO for UI Exposure [page 708]

For the multi-inline-edit scenario, create a business object projection for UI exposure.
Defining and Publishing a UI Service with Multi-Inline-Edit Capabilities [page 713]

For the multi-inline-edit, define a UI service and bind it to a protocol.
4.2.5.1 Defining the Data Model and the Business Object

Structure
The multi-inline-edit scenario uses flight carrier master data of the ABAP Flight Reference Scenario. The final
app processes carrier data in multi-inline-edit mode.
The RAP business object in this scenario consists of two BO entities. The root entity represents the singleton
entry point, whereas the first child entity comprises the general carrier data, like an ID, the full name and the
currency code that is used by the airline.
The composition tree of the Carrier BO looks like the following.

696 PUBLIC Develop
Carrier Business Object with Singleton Root Entity
The root entity /DMO/I_CarriersLockSingleton_S is a technical artifact to ensure the single entrance
point to the list of carrier data and the lock master for all carrier instances. It always retrieves only one dummy
instance that has no relevance for any data of the BO. The real data substance of the BO lies in the child
entity /DMO/I_Carrier_S. This CDS view selects from the database table /dmo/carrier, where the data is
stored.
• Creating the Singleton Root Entity [page 698]

• Creating the Master Data Entity [page 699]

Develop PUBLIC 697
4.2.5.1.1 Creating the Singleton Root Entity
For the multi-inline-edit scenario, create a data definition for a CDS view entity that defines the singleton
pattern for the BO.
Context
The multi-inline-edit scenario requires a singleton root entity with exactly one instance that represents the
single entrance point for the carrier data list on the UI.
The singleton pattern is implemented in a RAP BO by one simple trick: You model a root entity that selects
from an always existing CDS view and restrict the selection result with a where clause to ensure that there is
always only one single result. Such a CDS view can be the released CDS view I_Language, which is always
available in your SAP system. By restricting the selection result to the session language, you receive the
required result. There is always only one session language, which is by default always available in the select list
of the CDS view I_Language. The actual instance that is modeled in the root CDS view entity does not contain
elements of the underlying CDS view I_Language, but defines a key element with a dummy value and other
elements that are relevant for the draft processing. It is important to point out that the underlying CDS view
I_Language does not have any relevance for the scenario. It just ensures the singleton mechanism for a RAP
business object.
Procedure
1. Create a data definition for a CDS view entity to model the singleton pattern for the BO.
Select the template Define Root View Entity for the singleton entity and enter the name and a description
for the view entity.
The CDS view entity /DMO/I_CarriersLockSingleton_S uses the CDS view I_Language as a data
source. This CDS view is released for every system and can be used for any RAP BO. The language data is
not used in the singleton entity.
2. Model the root view entity as a singleton entity to receive a single entrance point for the UI.
Restrict the selection list by the system language with a where clause. This ensures that there is always
only one instance that is retrieved for requests on this entity.
Define a dummy field as key for the instance. You can use any hard-coded value.
3. Define a total ETag field to enable draft capabilities for the BO.
In this scenario, the total ETag in the root view is determined by the maximum value of all its child
instances. The child carrier instances use the field last_changed_at as ETag fields. Whenever an
instance is updated the field receives a new value and the total ETag is updated.
To get access to the data of the child instance, model a left outer join with the database table of the child
instances /dmo/carrier. The join must use a dummy join condition as there is no field on the left side
that matches any field on the right side of the join. By using a dummy join condition such as on 0 = 0,
every instance (there is just one) receives the fields that are selected from the joined data source.
Add the maximum of the field last_changed_at of the carrier database table to the select list of the root
view entity.

698 PUBLIC Develop
4. Define the composition structure of the carrier BO.
Once the CDS view entity of the child entity /DMO/I_Carrier_S exists, define the composition to is and
use the association in the select list.
 Expand the following code sample to view the source code of CDS root view entity /DMO/
I_CarriersLockSingleton_S.
 Sample Code

@EndUserText.label: 'Carrier Singleton Root View'
define root view entity /DMO/I_CarriersLockSingleton_S
as select from I_Language
left outer join /dmo/carrier as carr on 0 = 0
composition [0..*] of /DMO/I_Carrier_S as _Airline
{
key 1 as CarrierSingletonID,
max (carr.last_changed_at) as LastChangedAtMax,
_Airline
}
where
I_Language.Language = $session.system_language

4.2.5.1.2 Creating the Master Data Entity
For the multi-inline-edit scenario, create a data definition for a CDS view entity that selects the carrier master
data.
Context
The multi-inline-edit scenario requires that the master data entity is modeled as a child entity of a root entity
that enables a singleton mechanism.
Procedure
1. Create a data definition for a CDS view entity to model the carrier master data.
Select the template Define View Entity with To-Parent Association for the child entity and enter the name
and a description for the view entity.
The CDS view entity /DMO/I_Carrier_S uses the database table /dmo/carrier as data source. All
fields are selected.
2. Define the association to the parent view entity.
Include a dummy field with the same hard-coded value as the key field in the root view entity in the select
list. This field is used as the on-condition of the association.
3. Use the @Semantics annotations that automatically update the administrative fields in the managed
scenario.

Develop PUBLIC 699
4. Suppress search and text annotations that are inherits from the underlying CDS view by using the header
annotation @Metadata.ignorePropagatedAnnotations: true.
 Expand the following code sample to view the source code of CDS view entity /DMO/I_Carrier_S.
 Sample Code

@EndUserText.label: 'Transactional Carrier View'
define view entity /DMO/I_Carrier_S
as select from /DMO/I_Carrier as Airline
association to parent /DMO/I_CarriersLockSingleton_S
as _CarrierSingleton on $projection.CarrierSingletonID =
_CarrierSingleton.CarrierSingletonID
{
key AirlineID,
1 as CarrierSingletonID,
Name,
CurrencyCode,
LocalCreatedBy,
LocalCreatedAt,
LocalLastChangedBy,
//local etag field --> odata etag
LocalLastChangedAt,
//total etag field
LastChangedAt,
/* Associations */
_CarrierSingleton
}

4.2.5.2 Developing Transactional Behavior
The multi-inline-edit scenario implements some standard behavior for draft BOs and additional specific
behavior that is required to enable multi-inline-editing on the UI.
Context
The behavior for the singleton business object is defined in a behavior definition. Since the carrier business
object is draft-enabled, there is some standard draft behavior that must be available for the draft BO. Other
behavior results as a consequence of the special singleton pattern that is used in this BO.

700 PUBLIC Develop
Procedure
(/DMO/I_CarriersLockSingleton_S), you can directly create a behavior definition for the carrier singleton
data model. In the wizard, choose the implementation type Managed. For a detailed description, see .
Standard Behavior in the Template

The template for the managed implementation types provides a suggestion for the behavior pool and the
addition strict as best practice for RAP BOs. For every entity in the composition tree a behavior definition is
added and the persistent table is specified. As the root entity uses a join on its data source, a persistent table is
not found.
The standard operations create, update and delete are included for each entity. The create operation
on child entities is not supported in RAP scenarios. Instances of child entities can only be created by the
create-by-association operation, which is also included for parent entities.
The template also proposes to include the behavior characteristics lock, authorization and etag. The
master for lock and authorization is defined on the root entity with dependents on the child entity. The
template proposes to use the instance authorization. However, this business object does not implement
the authorization handler method as authorization would always include the configuration of authorization
objects in the system. This example BO focuses on the implementation parts that are relevant for the
singleton mechanism. That is why the authorization handler remains empty in this BO. You can also use
global authorization. The definition of authorization control requires an implementation in an ABAP behavior
pool, even if the implementation remains empty. Since this carrier BO only has little behavior that must
implemented, you can use one implementation class for both entities. The template proposes the name of the
behavior pool that is used for both entities.
The root entity instance can never be modified. Therefore it does not need an ETag. The ETag master is defined
on the child entity with the ETag field LocalLastChangedAt.
The child entity uses different field names in the CDS view than on the database table. Add a mapping
definition for the carrier child entity for all fields.
Singleton-Specific Behavior
Since the root view entity is only designed as an entrance point to the app, it is expected that there is always
only just one single instance. It is not intended that you can create, update, or delete instances on the root
entity. Delete this modification behavior from the template on the root entity.
The implementation type managed requires the specification of a persistent table for each BO entity. For
the root view entity, there is no persistent table, which leads to a syntax error in the behavior definition.
Modification on the root view entity is not allowed in this scenario. Therefore, no persistent table is required.
To solve the syntax issue in the behavior definition, define an unmanaged save for the root view entity with the
syntax with unmanaged save. Since this scenario does not intend to save any modification of the root entity
instances at all, the saver implementation method in the behavior pool remains empty. It is then called during
the save sequence of the BO, but does not change anything for the single root view entity instance.
Set the fields CarrierSingletonID in the root entity to read-only. As no modification is allowed on the root
entity, the field should not be editable on the UI.
Draft-Specific Behavior
To draft-enable the carrier business object, define with draft in the behavior definition header.

Develop PUBLIC 701
Draft-enablement requires that a draft database table is available for each entity. By adding draft table and
a name for the draft table on each entity, you can make use of the behavior definition quick fix that triggers the
creation of a draft table. The draft table for the root entity /dmo/d_carr_lock is just a dummy table that is
not used, as no modification on the root entity instance is possible in this scenario. The draft table for the child
entity /dmo/d_carrier is used for the draft life cycle management of carrier draft instances.
The draft-enablement also requires the definition of a total ETag field. The field LastChangedAtMax is
calculated in the root view entity to be used as total ETag field.
Add the addition with draft to the associations association _Airline {create;} and association
_CarrierSingleton; to explicitly define that the association is always followed with regards to the draft
indicator. This is automatically implicitly enabled, but for transparency reasons, it is best practice to explicitly
add it to the behavior definition. The field CarrierSingletonID is used in the on-condition for the to-parent
association _CarrierSingleton in the child entity. It must be set to read-only to ensure that the connecting
element between parent and child cannot be changed.
All master fields of the child entity are mandatory as no instance should exist without the AirlineID, Name or
CurrencyCode. In addition, the key field AirlineID must be read-only on update.
The strict mode in a draft-enabled business object requires the explicit definition of all draft actions. Define all
five draft actions in the behavior definition section of the root entity.
 Expand the following code sample to view the source code of behavior definition /DMO/
I_CarriersLockSingleton_S.
 Sample Code
managed implementation in class /dmo/bp_i_carrierslocksingle_s unique;

strict;
with draft;
define behavior for /DMO/I_CarriersLockSingleton_S alias CarriersLockSingleton
with unmanaged save
draft table /dmo/d_carr_lock
lock master
total etag LastChangedAtMax
{
association _Airline { create; with draft; }
field ( readonly ) CarrierSingletonID;
draft action Edit;
draft action Activate;
draft action Discard;
draft action Resume;
}
define behavior for /DMO/I_Carrier_S alias Carrier
persistent table /dmo/carrier
draft table /dmo/d_carrier
lock dependent by _CarrierSingleton
authorization dependent by _CarrierSingleton
{
update;
delete;
field ( readonly ) CarrierSingletonID;
field ( mandatory : create, readonly : update ) AirlineID;
field ( mandatory ) Name, CurrencyCode;
association _CarrierSingleton { with draft; }
mapping for /dmo/carrier

702 PUBLIC Develop
Name = name;
}

}
4.2.5.2.1 Developing Feature Control for the Carrier Entity
For the multi-inline-edit scenario, enable and disable functionality with feature control on the carrier entity.
Context
The carrier data that is used in this scenario to demonstrate multi-inline-edit capabilities on a Fiori UI is also
used by other business objects as master data for travel instances. The booking entity in a travel business
object has an association to the carrier interface view and validates if the carrier that is used in a booking
instance exists on the database table for carrier data. This ensures that only existing airlines are used. Up
to now, the carrier data remained stable as no other business object modified data on the database table.
With the current scenario, this changes. When maintaining the carrier data, it must be ensured that no carrier
instances can be deleted that is already used by another business object. This is enforced by defining feature
control for the delete operation. The instance feature control checks if the airline is used in a flight connection
that is maintained on the database table /dmo/connection. The delete operation is only enabled if the airline
ID is not used in a connection.
Procedure
Define feature control for the delete operation on the carrier entity.
 Sample Code

...
{
update;
delete ( features : instance );

... }
Use the quick fix in the behavior definition to generate the method definition for the instance feature control
handler in the behavior pool.
The implementation is done in the method FOR INSTANCE FEATURES.

Develop PUBLIC 703
Read all the instances with the imported keys into an internal table and use the AirlineID to select the
corresponding AirlineIDs from the connection interface view /DMO/I_Connection to check if the airline
IDs in the carrier BO are used in flight connections.
Disable the delete operation in the result table of the method if the respective AirlineID exists in a flight
connection. If it doesn't exist, set the permission value to enabled.
Fill the reported table with an adequate information message that is returned in the response structure of the
feature control method.
 Expand the following code sample to view the source code of GET_INSTANCE_FEATURES.
 Sample Code
CLASS lhc_carrier DEFINITION INHERITING FROM cl_abap_behavior_handler.

PRIVATE SECTION.
...
IMPORTING keys REQUEST requested_features FOR Carrier RESULT result.
ENDCLASS.
CLASS lhc_carrier IMPLEMENTATION.
DATA: airline_ids TYPE SORTED TABLE OF /dmo/i_carrier WITH UNIQUE KEY
AirlineID.
READ ENTITIES OF /DMO/I_CarriersLockSingleton_S IN LOCAL MODE
ENTITY Carrier
FIELDS ( AirlineID )
RESULT DATA(Carrier)
FAILED failed.
airline_ids = CORRESPONDING #( Carrier DISCARDING DUPLICATES MAPPING
AirlineID = AirlineID EXCEPT * ).
IF airline_ids IS NOT INITIAL.
SELECT DISTINCT AirlineID
FROM /DMO/I_Connection
FOR ALL ENTRIES IN @airline_ids
WHERE AirlineID = @airline_ids-AirlineID
INTO TABLE @DATA(connections_db).
ENDIF.
LOOP AT Carrier ASSIGNING FIELD-SYMBOL(<carrier>).
" Delete is not allowed if any Connection exists
IF line_exists( connections_db[ AirlineID = <carrier>-AirlineID ] ).
APPEND VALUE #( %tky = <carrier>-%tky
%delete = if_abap_behv=>fc-o-disabled ) TO result.
%msg = NEW /dmo/cx_carriers_s(
textid = /dmo/
cx_carriers_s=>airline_still_used
severity =
if_abap_behv_message=>severity-information
airline_id =
<carrier>-AirlineID )
%path-carrierslocksingleton = CORRESPONDING
#( <carrier> )
) TO reported-carrier.
ELSE.
%delete = if_abap_behv=>fc-o-enabled ) TO result.
ENDIF.
ENDLOOP.
ENDMETHOD.

ENDCLASS.

704 PUBLIC Develop
4.2.5.2.2 Developing Validations
For the multi-inline-edit scenario, define and implement validations for value consistency checks.
Context
Carrier instances are only completely usable if the values for each field are supplied. An airline without a
name or currency code doesn't make any sense. It is therefore indispensable that the values are checked on
creating new instances and on editing. The fields of carrier instances must not be empty. By defining the key
field AirlineID to be mandatory on create and read-only on update, the RAP runtime engine ensures that
the value is supplied when creating a new instance and that it does not get changed during the modification
process. The other fields Name and CurrencyCode are the developer's responsibility. These fields must be
checked by validations. Before saving a draft instance to the persistent table, the validations are executed and
instances without all values are rejected.
The validations must have the trigger condition create and the corresponding field.
Procedure
Define validations to check the Name and the CurrencyCode when creating new carrier instances and editing
these fields on the carrier entity.
 Sample Code

...
{
validation validateName on save { create; field Name; }

... }
The messages of validations are only correctly presented on the UI, if the validations are defined for the draft
determine action Prepare on the root entity.
 Sample Code
define behavior for /DMO/I_CarrierLockSingleton_S alias Carrier

...
{
{
validation Carrier ~ validateName;
validation Carrier ~ validateCurrencyCode;
}

... }
Use the quick fix in the behavior definition to generate the method definition for the validation handler in the
behavior pool.

Develop PUBLIC 705
The implementation is done in the methods FOR VALIDATE ON SAVE.
Validation ValidateName
Read all the instances with the imported keys into an internal table. Pass the failed entries to the failed table
of the validation.
Loop over the internal table Carriers. To avoid duplicate state messages for the consumer, append an empty
message to the reported table to clear the state area. If the respective field is initial, write the instance identifier
to the failed table and append a corresponding message to the respective state area.
 Expand the following code sample to view the source code of validateName.
 Sample Code

PRIVATE SECTION.
METHODS validateName FOR VALIDATE ON SAVE
IMPORTING keys FOR Carrier~validateName.
ENDCLASS.
METHOD validateName.
ENTITY Carrier
FIELDS ( CarrierSingletonID Name )
RESULT DATA(Carrier).
" Raise message for empty Airline Name
%state_area = 'VALIDATE_NAME'
IF <carrier>-name IS INITIAL.
APPEND VALUE #( %tky = <carrier>-%tky ) TO
failed-carrier.
%msg = NEW /dmo/cx_carriers_s(
textid = /dmo/
cx_carriers_s=>name_required
severity =
airline_id =
%element-name = if_abap_behv=>mk-on
%state_area = 'VALIDATE_NAME'
#( <carrier> )
ENDIF.
ENDLOOP.
ENDMETHOD.

ENDCLASS.
Validation ValidateCurrencyCode
In addition to checking if the provided value for the carrier instance is not initial, it is also relevant here to check
whether the provided currency code actually exists.
Read all the instances with the imported keys into an internal table. Pass the failed entries to the failed table
of the validation.

706 PUBLIC Develop
Copy the entries to another internal table and delete duplicates. If the resulting table is not initial, select
the entries of /DMO/I_Currency with the given currency code. If there is no corresponding result entry, the
provided currency code is not valid.
Loop over the internal table Carriers. To avoid duplicate state messages for the consumer, append an empty
message to the reported table to clear the state area. If the respective field is initial, write the instance identifier
to the failed table and append a corresponding message to the respective state area. If the select from /DMO/
I_Currency does not return values for the provided currency code, write the instance identifier to the failed
table and append a corresponding message to the respective state area.
 Expand the following code sample to view the source code of validateCurrencyCode.
 Sample Code

PRIVATE SECTION.
METHODS validatecurrencycode FOR VALIDATE ON SAVE
IMPORTING keys FOR carrier~validatecurrencycode.
ENDCLASS.
DATA: currency_codes TYPE SORTED TABLE OF I_Currency WITH UNIQUE KEY
Currency.
ENTITY Carrier
FIELDS ( CarrierSingletonID CurrencyCode )
RESULT DATA(Carrier).
currency_codes = CORRESPONDING #( Carrier DISCARDING DUPLICATES MAPPING
Currency = CurrencyCode EXCEPT * ).
IF currency_codes IS NOT INITIAL.
SELECT FROM I_Currency FIELDS Currency
FOR ALL ENTRIES IN @currency_codes
WHERE Currency = @currency_codes-Currency
INTO TABLE @DATA(currency_codes_db).
ENDIF.
" Raise message for not existing Currency Codes
%state_area = 'VALIDATE_CURRENCY_CODE'
IF <carrier>-CurrencyCode IS INITIAL.
APPEND VALUE #( %tky = <carrier>-%tky )
TO failed-carrier.
%msg = NEW /dmo/
cx_carriers_s(
textid
= /dmo/cx_carriers_s=>currency_code_required
severity =
airline_id =
%state_area =
'VALIDATE_CURRENCY_CODE'
#( <carrier> )
ELSEIF NOT line_exists( currency_codes_db[ Currency = <carrier>-
CurrencyCode ] ).
APPEND VALUE #( %tky = <carrier>-%tky )
TO failed-carrier.

Develop PUBLIC 707
%msg = NEW /dmo/
cx_carriers_s(
textid
= /dmo/cx_carriers_s=>invalid_currency_code
severity
= if_abap_behv_message=>severity-error
currency_code
= <carrier>-CurrencyCode )
%state_area =
'VALIDATE_CURRENCY_CODE'
#( <carrier> )
ENDIF.
ENDLOOP.
ENDMETHOD.

ENDCLASS.
4.2.5.3 Projecting the BO for UI Exposure
For the multi-inline-edit scenario, create a business object projection for UI exposure.
The business object with the singleton mechanism is aimed to be used in a UI scenario. It defines basic
features that are essential for the UI use case of multi-inline-editing. To define the data model and its
functionality that is needed for the use case of a carrier UI service, the business object must be projected.
In this BO projection, you define value helps, search and UI layout specifics.
Create CDS projection views for the root and the child entity, see Projecting the BO Data Model [page 708].
Create a CDS projection behavior definition to define the behavior that is to be used in the UI service, see
Projecting the BO Behavior [page 712].
4.2.5.3.1 Projecting the BO Data Model
For the multi-inline-edit scenario, create and define the data model for the BO projection.
Context
The multi-inline-edit scenario provides one projection use case that reuses all elements that are defined in
the business object view entities to be exposed for a UI service. In the projection layer the data model is
enriched with UI functionality that is implemented via CDS annotations or keywords in the projection view and
manifested in the service metadata.

708 PUBLIC Develop
Procedure
Create a data definition for projection views for the two business object entities of the carrier BO. In ADT, use
the context menu on the underlying CDS view entity to open the wizard for creating a CDS data definition and
choose the template Define Projection View. For a detailed step-by-step description, see .
Projection View /DMO/C_CarrierLockSingleton_S

The projection view is a projection on /DMO/I_CarrierLockSingleton_S. Include the keyword root in the
projection view.
Use all elements of the underlying BO travel entity.
To indicate that CarrierSingleton is the semantic identifier of the BO entity, use the annotation
@ObjectModel.semanticKey: ['CarrierSingleton'] in the header of the projection view.
The CarrierSingleton is just used for the on-condition of the composition. It is not necessary on the UI
representation. Use the annotation @Consumption.hidden:true.
composition to child to the projection view of the carrier entity.
 Expand the following code sample to view the source code of the projection view /DMO/
C_CarrierLockSingleton_S.
 Sample Code
@EndUserText.label: 'Carrier Singleton Projection View'

@ObjectModel.semanticKey: ['CarrierSingletonID']
define root view entity /DMO/C_CarriersLockSingleton_S
as projection on /DMO/I_CarriersLockSingleton_S
{
key CarrierSingletonID,
@Consumption.hidden: true
LastChangedAtMax,
/* Associations */
_Airline : redirected to composition child /DMO/C_Carrier_S
}

Projection View /DMO/C_Carrier_S

The projection view is a projection on /DMO/I_Carrier_S.
projection view, except for the element representing the ETag master LocalLastChangedAt.
897]
To indicate that CarrierID is the semantic identifier of the BO entity, use the annotation
@ObjectModel.semanticKey: ['AirlineID] in the header of the projection view.

Develop PUBLIC 709
The CarrierSingletonID is just used for the on-condition of the composition. It is not necessary on the UI
representation. Use the annotation @Consumption.hidden:true.
Define a value help for the element CurrencyCode. For more information, see Providing Value Help [page
776].
association to the root entity to the respective projection view.
 Expand the following code sample to view the source code of the projection view /DMO/C_Carrier_S.
 Sample Code
@EndUserText.label: 'Projection View Carrier'

@ObjectModel.semanticKey: ['AirlineID']
define view entity /DMO/C_Carrier_S
as projection on /DMO/I_Carrier_S
{
key AirlineID,
@Consumption.hidden: true
CarrierSingletonID,
Name,

element: 'Currency' }, useForValidation: true }]
CurrencyCode,
LocalLastChangedAt,
/* Associations */
_CarrierSingleton : redirected to parent /DMO/C_CarriersLockSingleton_S
}

4.2.5.3.1.1 Adding UI Metadata for UI Consumption
For the multi-inline-edit scenario, define UI annotations in metadata extensions for the business object entities.
Context
The layout of a Fiori Elements UI can be mostly defined in the RAP BO with @UI annotations. These UI
annotation are then exposed with the metadata of the UI service and are applied for defining a UI. It is best
practice to maintain UI-relevant annotations in metadata extensions.

710 PUBLIC Develop
Procedure
Create a metadata extension for each projection view in the carrier BO. In ADT, right-click on the data definition
to open the creation wizard for metadata extensions. For more information, see .
Metadata Extension /DMO/C_CARRIERSLOCKSINGLETON_S

Define the metadata extension as extension of the CDS projection view /DMO/
C_CARRIERSLOCKSINGLETON_S.
Since the root view of the carrier business object has just one instance, the UI layout for the list report page of a
Fiori Elements has only limited layout requirements.
To specify the header texts for Fiori UIs, the annotation @UI.headerInfo is used at entity level. It specifies
the list title as well as the title for the object page.
The main building blocks of the UI are specified as UI facets. Define a facet for the root view using the
@UI.facet annotation and a navigation to the object page by defining the target elements.
For more information about UI layout configuration, see Defining CDS Annotations for Metadata-Driven UIs
[page 786].
 Expand the following code sample to view the source code of the metadata extension /DMO/
C_CarriersLockSingleton_S.
 Sample Code

@UI: { headerInfo: { typeName: 'Manage Carriers',
typeNamePlural: 'Carrier Singleton',
title: { type: #STANDARD, value:
'CarrierSingletonID' } } }
annotate entity /DMO/C_CarriersLockSingleton_S
with
{
@UI.facet: [
{
purpose: #STANDARD,
label: 'Carrier Multi Inline Edit',
position: 10,
targetElement: '_Airline'
}
]
@UI.lineItem: [{ position: 10 }]
CarrierSingletonID;

}
Metadata Extension /DMO/C_CARRIER_S

Define the metadata extension as extension of the CDS projection view /DMO/C_CARRIER_S.
Like in the metadata extension for the root view, specify the header information, a facet as
identification_reference, which indicates the list on the object page, and the position for the elements
as line item and identification.

Develop PUBLIC 711
For more information about UI layout configuration, see Defining CDS Annotations for Metadata-Driven UIs
[page 786].
 Expand the following code sample to view the source code of the metadata extension /DMO/C_Carrier_S.
 Sample Code

@UI: { headerInfo: { typeName: 'Carrier',
typeNamePlural: 'Carriers',
label: 'Airline',
value: 'AirlineID' } } }
annotate entity /DMO/C_Carrier_S
with
{
@UI.facet: [{ type: #IDENTIFICATION_REFERENCE }]
@UI.identification: [{ position: 10 }]
AirlineID;
Name;
CurrencyCode;

}
4.2.5.3.2 Projecting the BO Behavior
For the multi-inline-edit scenario, create a projection behavior definition for defining the projection behavior.
Context
In a behavior definition, you define the behavior characteristics and operations of the underlying behavior
definition that are to be used in the service the BO is exposed to. For the carrier business object, all behavior
that is defined in the base BO is used in the projection behavior definition.
Procedure
Create a projection behavior definition for the carrier business object. In ADT, use the context menu of the root
Use the complete behavior that was defined in the underlying behavior definition for the carrier BO.
 Expand the following code sample to view the source code of the projection behavior definition /DMO/
C_CarriersLockSingleton_S.

712 PUBLIC Develop
 Sample Code
projection;

strict;
use draft;
define behavior for /DMO/C_CarriersLockSingleton_S alias CarriersLockSingleton
{
use action Discard;
use action Edit;
use action Prepare;
use action Resume;
use association _Airline { create; with draft; }
}
define behavior for /DMO/C_Carrier_S alias Carrier
use etag
{
use update;
use delete;
use association _CarrierSingleton { with draft; }

}
4.2.5.4 Defining and Publishing a UI Service with Multi-

Inline-Edit Capabilities
For the multi-inline-edit, define a UI service and bind it to a protocol.
Context
The RAP BO with the singleton mechanism is designed to be exposed as UI service for consumption via Fiori
Elements UI with multi-inline-edit capabilities. For this to work, the carrier BO must be exposed as a business
service to OData. In the service definition, you define which artifacts are included in the service. The service
binding defines the protocol with which the service is addressed. In addition, it provides the means to activate
the service locally. The Fiori Elements App Preview can be used as soon as the service is activated.
Procedure
Create a service definition for the business service. For more information, see .
Include the projection views of the business object an all related CDS entities that are relevant for UI
 Expand the following code sample to view the source code of the service definition /DMO/UI_Carriers_S.
 Sample Code
@EndUserText.label: 'Carrier Multi-Inline-Edit Scenario'

@ObjectModel.leadingEntity.name: '/DMO/C_CarriersLockSingleton_S'

Develop PUBLIC 713
define service /DMO/UI_Carriers_S {
expose /DMO/C_CarriersLockSingleton_S as CarriersLockSingleton;
expose /DMO/C_Carrier_S as Carrier;

}
Based on the service definition, create a service binding. For more information, see .
test the service.
4.2.6  Cloud Developing a UI Service with Access to a

Remote Service
Based on a remote OData service, you create a new service that enhances the remote service with additional
information.
Introduction
In this scenario, you develop an OData service that consumes a Web API. This Web API represents a remote
service from which you retrieve data. This data is then enhanced with additional data. That means, the new
OData service has two data sources. One is the remote service, the other source is a database table in the
consuming development system. You build a new SAP Fiori UI application that consumes the remote service
from the provisioning tenant, and enhances the remote service with persistent data of the consuming tenant.
The data model for the new service is defined in a CDS custom entity, which enables you to retrieve data from
different sources. A CDS custom entity has an unmanaged query, which has to be implemented manually in a
related ABAP class, the query implementation class. In this ABAP class, data from different sources, including
from another system, can be retrieved.
With the help of the service consumption model, you can import the OData metadata of the remote service into
the consuming system and create proxy artifacts of the remote service. This gives you a local representation of
the remote data model in your tenant, which helps you to define a data model for the new service.
This guide also describes how you implement transactional behavior to modify the additional data on the local
database table.
The following image gives an overview of the architecture of the service consumption scenario.

714 PUBLIC Develop
Service Consumption Scenario Overview
To be able to get data from a remote service, you build an OData client proxy in your implementation to forward
and transform the requests for the remote service. The client proxy can only consume the remote service if a
connection to the provisioning tenant is established. The configuration of such a destination is a precondition
for developing this scenario.
Development Steps to Create a New Service to Consume a Remote Service
• Save the XML file of the remote service locally.

• Create proxy artifacts with the service consumption model wizard.
• Create a CDS custom entity as a data model for the new service.
• Implement the query in an ABAP class.
• Implement the transactional behavior for the local fields.
• Create an OData service.
Prerequisites


Develop PUBLIC 715
 Restriction
• You know the URL of the remote service that you want to consume or have access to the CSDL XML file of
the service.
In this demo scenario, the service /DMO/API_TRAVEL_U_V2 is used as remote service. You can download
the service as part of the ABAP Flight Reference Scenario, see Downloading the ABAP Flight Reference
Prerequisites for the Consumption of a Remote Service
• A cloud destination is configured in the Cloud Cockpit to connect to the provisioning system.
For more information, see Configure a Destination for the Sample Apps.
• A communication arrangement for the destination service instance in the ABAP environment has been
created in your consuming system (SAP_COM_0276).
Prerequisites to Consume a Remote Service from an S/4 HANA Cloud System

This scenario consumes a remote service from an S/4HANA Cloud System. You can consume any OData
service, but different prerequisites might apply.
The following prerequisites apply for this consumption scenario:
• The remote OData service has been published in a communication scenario.

For more information, see Consuming Services in the Context of API with Technical Users.
• A communication arrangement exists in the provisioning system.
For more information, see Implementation Steps in the SAP S/4HANA Cloud System.
4.2.6.1  Cloud Scenario Description
Starting Point: Remote OData Service

In this development guide, we reuse the service that was built in Develop Web APIs [page 765]. We only
use the root node from the remote service for our consumption and the transactional behavior is ignored.
The new service in the consuming system does not implement operations to create, update, or delete data
from the provisioning system. Instead, it retrieves the data from there and enriches the service with additional
fields. These additional fields, however, can be modified. Therefore, the new UI service contains transactional
capabilities for these additional fields.
A Web API service is the prototypical example for this consumption scenario. It contains all the required
information, but does not contain any metadata that is superfluous in the consumption scenario (for example,

716 PUBLIC Develop
UI-relevant annotations). However, it is also possible to consume an OData service that was published as a UI
service.
The available entity types of the remote service can be viewed in the metadata document when extended. We
only consume the root node Travel.
 Expand the following item to view the metadata of the remote service.
Metadata of the Remote Service
End Point: New OData Service with Additional Fields

We want to consume the remote service in the local system and extend it with additional fields for discounts.
The end user will be able to maintain possible discounts for each trip in an SAP Fiori application. These
discount fields are persisted on a local database table and retrieved together with the data of the remote
service. The end user UI does not show any difference between the persisted fields and the fields that are
retrieved remotely.
The discount fields are:
• Discount Percentage: The end user can maintain a proportional discount for the total price of travel.
• Discount Absolute: The end user can maintain an absolute value as discount for the total price of the travel
In our scenario, these fields are persisted in the database table /dmo/traveladd, which consists of the two
discount fields, the travel ID as the key, and administrative data to track changes.
In addition to the persistent fields, there is also a calculated field (Total Price with Discount) that displays the
new total price including the possible discount. This field, however, is not persisted in the database, but is
transient.
The following figure shows the end user UI with fields that are retrieved remotely from the provisioning system,
persistent fields, and the transient field.

Develop PUBLIC 717
Fiori Elements App for Managing Travel and Discounts
Procedure
To merge the locally and remotely retrieved data, the application developer must import the metadata of the
remote service into the consuming system. Abstract entities that mirror the original data model of the remote
service are generated by the service consumption wizard. It is then possible to access the service within the
local ABAP code. To build a new OData service based on the remote service including additional database
fields, a CDS custom entity is used to represent the data model, including both local and remote fields.
The program logic of a custom entity is not managed by ABAP runtime frameworks, but has to be implemented
manually. The implementation includes the query itself and every query option as well as the transactional
behavior for the local fields. The query is implemented in a query implementation class and the transactional
runtime behavior is defined via a behavior definition and implemented in the related behavior pool. To access
the data from the remote service, a destination to the provisioning system must be instantiated in the
implementation classes.
To create the OData service, we expose the custom entity in a service definition and create a service binding to
bind the service against a protocol. In our example case, this is a V2 UI service.
As a result, the existing remote read-only service and database fields with transactional capabilities are merged
within the same SAP Fiori Elements app.
Related Information
Developing Unmanaged Transactional Apps [page 481]

Develop Web APIs [page 765]

718 PUBLIC Develop
4.2.6.2  Cloud Preparing Access to the Remote OData
Service
In order to consume the remote service in your local system, you need a local representation of the remote
service.
Context
To be able to access the remote OData service, you need to generate proxy artifacts for it. These abstract
entities mirror the data model of the remote service.
The wizard that creates the proxy artifacts requires a CSDL XML document of the external service as a basis for
the abstract entities.
Service Consumption Model
4.2.6.2.1  Cloud Getting the OData Service Metadata
Context
A CSDL XML file can be retrieved from any service if the service URL is known. The following procedure
describes the steps for saving a CSDL XML document on your local machine.
Procedure
1. Open your browser.

2. Call the external OData service metadata document.
 Note
You get the metadata document by adding /$metadata to the service URL.
3. Save the metadata as an XML Document on your local machine.

Develop PUBLIC 719
Next Steps
You can now use this CSDL XML document in the service consumption wizard.
4.2.6.2.2  Cloud Generating Proxy Artifacts
Prerequisites
The metadata CSDL XML file of the service you want to consume is stored on your local machine.
Context
The proxy artifacts that represent the remote service in your system are required to access the remote service
in your ABAP code. A wizard generates these proxy artifacts.
Procedure
1. In your ABAP package, open the context menu and choose New Other ABAP Business Services
Service Consumption Model to launch the creation wizard.
2. In addition to the Project and Package, enter a Name for the new service consumption model and a
Description.

720 PUBLIC Develop
We use the name /DMO/TRAVEL_C_A in our example scenario. The suffix _C for consumption scenario and
_A for abstract.
 Note
This name is also used for the service definition that will be generated.
3. Browse your local machine for the Service Metadata File.

4. Choose Next.
5. On the Mapping Names screen, deselect all service entity sets, except for Travel and edit the ABAP artifact
name for this entity set to prevent name clashes with other artifacts.
In this example scenario, we only use the root node of the business object (Travel).
6. Choose Next.
On the ABAP Artifact Generation List screen, in addition to the selected entity set, the service definition
that is generated is listed.

Develop PUBLIC 721
7. Choose Next and assign a transport request.
8. Choose Finish.
The service consumption model editor is opened, in which you can see and verify the generated artifacts.
The wizard creates an abstract entity in your local system for each entity from the external service that you
have chosen. If the source service contains creatable, updatable, or deletable entities, a behavior definition
is created with the same name as the related abstract entity. These entities are found in the Core Data
Services folder in ADT. Additionally, the generated service definition is created in the Business Services
folder. It carries the same name as the service consumption model.
 Remember
We only use the root node of the external service, which is now represented as /DMO/TRAVEL_C_A.
You can access any of the development objects directly from this editor.
The service consumption model also generated code samples with placeholders for CRUD operations,
which facilitate your entity set consumption.
Results
The following codeblock displays the source code of the abstract entity /DMO/TRAVEL_C_A:
/********** Generation Administration Data**************/

@OData.entitySet.name: 'Travel'
@OData.entityType.name: 'TravelType'
define root abstract entity /DMO/TRAVEL_C_A
{
key TravelID : abap.numc( 8 );
AgencyID : abap.numc( 6 );
AgencyID_Text : abap.char( 80 );
CustomerID : abap.numc( 6 );
CustomerID_Text : abap.char( 40 );
BeginDate : abap.dats;
EndDate : abap.dats;
BookingFee : abap.dec( 17, 3 );
TotalPrice : abap.dec( 17, 3 );
CurrencyCode : abap.cuky( 5 );
Memo : abap.char( 1024 );
Status : abap.char( 1 );
LastChangedAt : tzntstmpl;
ETAG__ETAG : abap.string( 0 );

}
 Note
Element types, the semantics annotations, and the OData entity set name, which is referenced in the
annotation, are taken from the service metadata document of the remote service. If an ETAG is maintained
in the original service, an element for the ETAG is added. The text element for the elements that have a text
association in the original service are also added to the abstract entity. We will not use them in the service
consumption scenario.
This abstract entity serves as a template for the data model of the new service.

722 PUBLIC Develop
4.2.6.3  Cloud Creating a Database Table for the
Persistent Fields
Context
The remote service is enriched with discount fields (discount_pct and discount_abs). These enable the end
user to maintain discounts for trips. The discounts can be either absolute or relative to the total price of the
trip. These fields are used to calculate the new price (TotalPriceWithDiscount) in a transient field.
To create the database table for the discount fields, follow the steps.
Procedure
1. In the Project Explorer, select the relevant Package node, open the context menu, and choose New
Other ABAP Repository Object Dictionary .
2. Select Database Table to launch the creation wizard.
The Creation wizard opens.

3. Enter the necessary information for the wizard to create the database table /dmo/traveladd.
For a detailed description of how to use the wizard, see .
Once you have completed the wizard, the initially generated source code is displayed and ready for editing.
4. Define the fields for the database table.
@EndUserText.label : 'Travel Discount Information'

define table /dmo/traveladd {
key travel_id : abap.numc(8) not null;
discount_pct : abap.dec(3,1);
discount_abs : abap.dec(16,2);
lastchangedat : timestampl;

}
5. Save and activate.

Develop PUBLIC 723
4.2.6.4  Cloud Using a CDS Custom Entity for Data
Modeling
Custom entities are used for data models whose runtime is implemented manually.
Context
This service consumption scenario retrieves its data partly from a remote service and partly from a local
database table. In custom entities, you define the elements and type them to be used in the local OData
service. Custom entities do not come with a select on the data source. The implementation of the logic to
retrieve the data is implemented in an ABAP class that is referenced in an entity annotation.
For more information, see Unmanaged Query [page 285].
4.2.6.4.1  Cloud Creating a CDS Custom Entity
Procedure
1. In your ABAP project, select the relevant package node in the Project Explorer. Open the context menu and
choose New Other... Core Data Services Data Definition to launch the creation wizard.
2. Enter the necessary information for the wizard to create the CDS custom entity. Choose Define Custom
Entity with Parameters as the template.
A new data definition for a CDS custom entity is created and added to the Core Data Services folder of the
corresponding package node. In our scenario, the name of the custom entity is /DMO/I_TRAVEL_C_C (first
suffix for consumption scenario, the second for custom entity).
3. Delete the with parameters statement. Parameters are not needed in the current scenario.
Results
Unlike CDS views, custom entities do not have a select statement to retrieve the data from a data source. The
runtime of a custom entity must be implemented in a related ABAP class, which must be referenced using the
annotation @ObjectModel.query.implementedBy.

724 PUBLIC Develop
Next Steps
The elements can now be defined in the editor. At least one element must be key. It is also necessary to
determine a class for the query implementation in the annotation @ObjectModel.query.implementedBy.
4.2.6.4.2  Cloud Defining the Data Model in a CDS Custom

Entity
Context
As described in Cloud Scenario Description [page 716], the data for the new OData service is partly retrieved
from a foreign S/4HANA system and partly taken from a local database. As we have already generated
the proxy artifacts, we can copy the data structure and the data types from the abstract entity /DMO/
TRAVEL_C_A. In addition, the additional discount elements are included, which have the same data types
as declared in the database table /dmo/traveladd.
Procedure
1. If you have not already done so, open the new data definition for the CDS custom entity in the editor.
2. Define the data model for the new travel service. You can copy the elements from the abstract
entity /DMO/TRAVEL_C_A.
You do not have to use the same names as in the abstract entity, but if you do use a different name, you
have to map this manually in the query implementation. For example, the element Memo is renamed to
Description in the custom entity.
3. Delete ETAG_ETAG element and the text elements AgencyID_Text and CustomerID_Text.
 Note
You do not need the element ETAG_ETAG from the remote service. We use a calculated eTag in this
scenario, which contains the timestamp from the local database table and the time timestamp from
the remote service to ensure that no data has changed, neither on the local databse table nor in the
remote service.
4. Include the additional discount fields from /dmo/traveladd.
DiscountPct : abap.dec( 3, 1 );

DiscountAbs : abap.dec( 16, 3 );
5. Add the element for the transient field that calculates the total price with discount.
TotalPriceWithDiscount: abap.dec(17,3)
6. Add an element for the calculated eTag.
CalculatedEtag : abap.string( 0 );

Develop PUBLIC 725

7. Define the semantic relation between the amount and currency fields with the relevant annotation.
Results
The following codeblock displays the custom entity elements with the right types and the semantic
annotations.
@EndUserText.label: 'CE for Service Consumption Scenario'

define custom entity /DMO/I_TRAVEL_C_C
{
CurrencyCode : abap.cuky( 5 );
Description : abap.char( 1024 ); //renamed element
LastChangedAt : tzntstmpl;
DiscountPct : abap.dec( 3, 1 );
DiscountAbs : abap.dec( 16, 3 );
TotalPriceWithDiscount : abap.dec(17,3);
CalculatedEtag : abap.string( 0 );

}
Next Steps
Before you can activate the CDS custom entity, you need to create an ABAP class that implements
the interface IF_RAP_QUERY_PROVIDER. This class needs to be referenced in the entity annotation
@ObjectModel.query.implementedBy.
4.2.6.4.3  Cloud Creating the Query Implementation Class
Context
The runtime of a CDS custom entity must be implemented manually. Therefore, it requires an ABAP class that
implements the select method of the interface IF_RAP_QUERY_PROVIDER to handle query requests by the

726 PUBLIC Develop
client. This class is referenced by the custom entity and is dedicated to implementing the OData client data
requests.
Procedure
1. In the Project Explorer, select the relevant package node, open the context menu, and choose New
ABAP Class to launch the creation wizard.
2. Follow the steps of the creation wizard and enter the necessary information. In the example scenario, we
choose the name /DMO/CL_TRAVEL_C_Q for the query implementation class.
Once you have completed the wizard, the initially generated source code is displayed and ready for editing.
3. Implement the select method of the query provider interface IF_RAP_QUERY_PROVIDER.
The custom entity can only be activated once the select method of the interface
IF_RAP_QUERY_PROVIDER is implemented in the query implementation class.
CLASS /dmo/cl_travel_c_q DEFINITION

PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
INTERFACES if_rap_query_provider.
PROTECTED SECTION.
PRIVATE SECTION.
ENDCLASS.
CLASS /dmo/cl_travel_c_q IMPLEMENTATION.
METHOD if_rap_query_provider~select.
ENDMETHOD.

ENDCLASS.
4. In the custom entity /DMO/I_TRAVEL_C_C, add the entity annotation

@ObjectModel.query.implementedBy and reference the newly created query implementation
class /DMO/CL_TRAVEL_C_Q.
The reference to the ABAP class must start with ABAP:.
@ObjectModel.query.implementedBy: 'ABAP:/dmo/cl_travel_c_q'

define custom entity /DMO/I_TRAVEL_C_C
5. Activate the custom entity /DMO/I_TRAVEL_C_C.
4.2.6.5  Cloud Consuming the Remote OData Service
Address a remote service in your ABAP code and implement the query contract and the transactional behavior
for the business object to build a new OData service.
Our service consumption scenario includes the creation of a new OData service in the consuming tenant. You
have defined a data model for this service in a CDS custom entity, and now, the unmanaged query must be
implemented in a related ABAP class as the query is not managed by a framework.

Develop PUBLIC 727
Additionally, this scenario also illustrates how transactional behavior can be included for the new OData
service. To update the discount data, the business object (consisting only of the custom entity in this case)
must be equipped with the implementation of the transactional runtime in a behavior pool. This includes the
implementation of the interaction phase and save sequence.
Both, the query and the behavior implementation need to retrieve data from the remote service. With the
help of a remote client proxy, the connection to the provisioning system is established and read requests are
delegated to consume the remote service. The client proxy implementation is done in an auxiliary class for
reuse reasons.
 Remember
The consumption of a Web API requires the configuration of the involved systems (provisioning and
consuming system) to allow the communication between them.
See Prerequisites for the Consumption of a Remote Service [page 716].
The following sections guide you through the implementation steps to instantiate a remote client proxy to
reach the provisioning system, to implement the query for read access to the remote service and to implement
transactional access to the discount persistence layer.
• Cloud Creating a Remote Client Proxy [page 728]

• Cloud Implementing the Query for Service Consumption [page 731]
• Cloud Adding Transactional Behavior to the Business Object [page 747]
4.2.6.5.1  Cloud Creating a Remote Client Proxy
To enable data retrieval from a remote service, you must establish a connection to the provisioning system and
instantiate a client proxy that passes the OData requests to the remote service.
Prerequisites
To be able to address a remote service, make sure that you meet the Prerequisites for the Consumption of a
Remote Service [page 716].
Context
A remote client proxy is used when an OData service is consumed remotely using an HTTP request. For reuse
reasons, it is useful to instantiate the client proxy in a separate helper class.
Exception and Message Handling

In the service consumption scenario, several types of errors might occur. The execution of query or
transactional requests is quite complex, as one request must pass not only the consuming service but also
the provisioning service. In different parts of your coding, errors can happen. For example, while trying to

728 PUBLIC Develop
connect to the provisioning system, while instantiating the client proxy, while executing the unmanaged query,
during the execution of the application logic or during the modification of the discount values. Every kind of
error must be handled with a suitable exception and message. Therefore, it is convenient to unite all exceptions
and their related message in one exception class and one message class.
Before starting with the implementation of the consumption of the remote service, create an exception and a
message class. For more information about exception and message handling, see , , and .
The exception class must inherit from the superclass CX_RAP_QUERY_PROVIDER.
In the example scenario, the name of the exception class is CX_TRAVEL_SERV_CONS. The name of the
message class is CM_SERV_CONS.
1. Create an Auxiliary Class for the Client Proxy Implementation
• In the Project Explorer, select the relevant package node, open the context menu, and choose New
ABAP Class to launch the creation wizard.
• Follow the steps of the creation wizard and enter the necessary information. In the example scenario, we
choose the name /DMO/CL_TRAVEL_CP_AUX. Once you have completed the wizard, the initially generated
source code is displayed and ready for editing.
• Declare a static method in the public section of the auxiliary class for the creation of a client proxy:
create_client_proxy with a returning parameter ro_client_proxy and an exception to be raised if
there are errors. .
CLASS /dmo/cl_travel_cp_aux DEFINITION

PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
CLASS-METHODS:
get_client_proxy RETURNING VALUE(ro_client_proxy) TYPE REF TO /iwbep/
if_cp_client_proxy
RAISING /dmo/cx_travel_serv_cons.
PROTECTED SECTION.
PRIVATE SECTION.
ENDCLASS.
CLASS /dmo/cl_travel_cp_aux IMPLEMENTATION.
METHOD get_client_proxy.
ENDMETHOD.

ENDCLASS.
2. Get the destination to the provisioning system and create an HTTP client
To be able to access the provisioning tenant, you must maintain a cloud destination for the foreign system and
create an HTTP client. Use the code samples of the service consumption model for this.
• Call the method create_by_http_destination of the class CL_WEB_HTTP_MANAGER to create an

HTTP client.
• Call the public static method create_by_cloud_destination of the class
CL_HTTP_DESTINATION_PROVIDER to create a client proxy. Provide the name of the destination and

Develop PUBLIC 729
the name of the service instance name. In our scenario, the destination is set up under the name
TRAVEL_BASIC and the service instance name is OutboundCommunication.
The method has another input parameter, which relates to the authentication mode. If you do not fill this
input parameter, the default authentication is BasicAuthentication with the user of the destination. This
can be made explicit by using the parameter with the value if_a4c_cp_service=>service_specific.
• Include error handling. Use the exception class /DMO/CX_TRAVEL_SERV_CONS to raise adequate
exception message, for example Access to remote system failed. .
For information about how to work with exception classes and message classes, see .
" Getting the destination of foreign system

TRY.
" Getting the destination of foreign system
" Create http client
" Details depend on your connection settings
DATA(lo_http_client) =
cl_web_http_client_manager=>create_by_http_destination(
cl_http_destination_provider=>create_by_cloud_destination(
i_name =
'Travel_Basic'
i_service_instance_name =
'OutboundCommunication' ) ).
" Error handling
CATCH cx_http_dest_provider_error INTO DATA(lx_http_dest_provider_error).
RAISE EXCEPTION TYPE /dmo/cx_travel_serv_cons
EXPORTING
textid = /dmo/cx_travel_serv_cons=>remote_access_failed
previous = lx_http_dest_provider_error.
CATCH cx_web_http_client_error INTO DATA(lx_web_http_client_error).
EXPORTING
textid = /dmo/cx_travel_serv_cons=>remote_access_failed
previous = lx_web_http_client_error.

ENDTRY..
3. Instantiate the Client Proxy

To consume the remote service from the provisioning system, we need a client proxy that delegates the
requests to the remote service. Since our scenario works with OData V2, we need a V2 client proxy.
The service consumption model provides code templates for this.
• Create a client proxy by calling the method create_v2_remote_proxy of the class

CL_WEB_ODATA_CLIENT_FACTORY. The client proxy is instantiated with the service definition generated
by the service consumption model, the previously created HTTP client, and the URL path to the Web API.
• Use the exception class /DMO/CX_TRAVEL_SERV_CONS to raise adequate exception message, for example
Client Proxy could not be instantiated.
For information about how to work with exception classes and message classes, see .
" Instantiation of client proxy

TRY.
ro_client_proxy = cl_web_odata_client_factory=>create_v2_remote_proxy(
EXPORTING
iv_service_definition_name = '/DMO/TRAVEL_C_A'
io_http_client = lo_http_client
iv_relative_service_root = '/sap/opu/odata/DMO/API_TRAVEL_U_V2' ).
CATCH cx_web_http_client_error INTO lx_web_http_client_error.
EXPORTING
textid = /dmo/cx_travel_serv_cons=>client_proxy_failed
previous = lx_web_http_client_error.

730 PUBLIC Develop
CATCH /iwbep/cx_gateway INTO DATA(lx_gateway).
EXPORTING
textid = /dmo/cx_travel_serv_cons=>client_proxy_failed
previous = lx_gateway.

ENDTRY.
4.2.6.5.2  Cloud Implementing the Query for Service

Consumption
The following topics guide you through the implementation steps required to execute a query request in a
service consumption scenario.
Runtime Logic for the Query in the Service Consumption Scenario
Our scenario has two different data sources. One is a remote service from a possibly different system.
To retrieve data from this service, you must have an appropriate connection to the provisioning tenant
(see Prerequisites for the Consumption of a Remote Service [page 716]) and the select method in the
query implementation class must instantiate a client proxy that executes requests for the remote service.
Additionally, it must include the implementation of every query option you want to support. The other data
source is a database table in the consuming system that stores the additional discount fields. To retrieve the
data from this table, the select method includes an ABAP SQL SELECT.
The following figure illustrates how the query works in the service consumption scenario.

Develop PUBLIC 731
Query for Service Consumption Scenario
Apart from the simple data retrieval, the scenario also includes the query options filtering, selecting, sorting,
and paging. All of these capabilities must be implemented in the query implementation class.
The client proxy is a powerful means to pass on OData requests to the provisioning tenant. It must be
instantiated in the query implementation class. All the possible query options of the OData request in the
consuming system must then be added to the request for the client proxy. This needs to be done for every
query option separately. After the actual execution of the request and the data retrieval, the data set from the
remote service is extended with its matching discount data.
 Note
The query options can only be delegated to the client proxy if the query options only affect the elements
from the remote service. If the query options are operated on local database fields, they must be
implemented manually after the retrieval of the data set from the provisioning system. As this might
cause serious performance issues, it is not demonstrated in this example scenario. Consider performance
aspects for your use case, if you decide to implement this.
Structure of the Query
For every request that is sent to the remote service you need to instantiate the client proxy. The method to
create a client proxy. With this client proxy, you create a read request (as you only want to execute a query on
the remote service). Before sending this read request to the remote service, it must be equipped with all the
necessary query options. For example, whenever the count is requested by the UI, the query option for count
must be added to the read request. The interface IF_RAP_QUERY_PROVIDER provides methods to find out
which query options are requested by the UI and hence must be delegated to the remote service.

732 PUBLIC Develop
 Note
When choosing the GO button on the UI to retrieve data, it always requests the count and paging.
Therefore, the implementation for data retrieval must include at least counting and paging. Otherwise
you will get a runtime error.
When all necessary query options are added to the request, it can be executed and the result must be given
back to the UI.
The procedure for implementing the query implementation is described in the following in detail:
1. Cloud Implementing Data and Count Retrieval [page 733]

2. Cloud Implementing Filtering [page 739]
3. Cloud Implementing Column Selections [page 742]
4. Cloud Implementing Sorting [page 745]
Related Information
Query Implementation Types [page 284]
4.2.6.5.2.1  Cloud Implementing Data and Count Retrieval
To enable data retrieval from a remote service, you must establish a connection to the provisioning tenant and
instantiate a client proxy that passes the OData requests to the remote service. The data sets from the remote
service are then imported to the consuming tenant and can be merged with additional data.
Preview
Choosing the Go button on an SAP Fiori UI triggers the OData request for data and count retrieval. The UI
automatically includes a paging query option with usually 25 data records per page.

Develop PUBLIC 733
1. Instantiate the Client Proxy
To send requests to the provisioning system, you need a remote client proxy.
• In the query implementation class, call the method get_client_proxy of the auxiliary class /DMO/
CL_TRAVEL_CP_AUX in the select method.

"""Instantiate Client Proxy
DATA(lo_client_proxy) = /dmo/cl_travel_cp_aux=>get_client_proxy( ).
...

ENDMETHOD.
2. Create a Read Request
To execute a query request on the remote service, a read request for the relevant entity set must be created.
This read request will then be enhanced with query options.
• On the client proxy object, call the method create_resource_for_entity_set with the TRAVEL entity
set name as importing parameter.
 Note
The OData entity set name can be found in the relevant abstract entity:
In our scenario, the alias Travel is used.
 Note
Use uppercase for the OData entity set name of the entity for this method, since the internal ABAP
representation of entity sets is in uppercase.
This method returns an object for the entity set resource.

• Create a read request by calling the method create_request_for_read on the entity set resource.
• Surround the method call with a TRY-CATCH block and include error handling with a suitable error
message.
TRY.

"""Create Read Request
DATA(lo_read_request) = lo_client_proxy-
>create_resource_for_entity_set( 'TRAVEL' )->create_request_for_read( ).
EXPORTING
textid = /dmo/cx_travel_serv_cons=>query_failed

ENDTRY.

734 PUBLIC Develop
3. Request the Inline Count of the Remote Service
As a Fiori UI always requests the inline count of the service, this request must be delegated to the remote
service to get the total number of records from there.
• Within the try-catch Block, check whether the total number of records is requested by the UI by calling the
method is_total_numb_of_rec_requested of the interface IF_RAP_QUERY_REQUEST.
For more information about is_total_numb_of_rec_requested, see Method
is_total_numb_of_rec_requested [page 292].
.
 Note
The same exception as previously defined can be used for all methods called on the read request.
• Call the method request_count on the read request.
"""Request Count

IF io_request->is_total_numb_of_rec_requested( ).
lo_read_request->request_count( ).

ENDIF.
4. Implement Paging if Data is Requested
Whenever the UI requests paging, the query framework checks that the query does not return more data
records than requested. Therefore, you need to set the paging information for the read request the client proxy
sends to the remote service.
• Within the try-catch block, check whether data is requested. If data must be returned using the
method set_data, the requested paging must be applied. If data does not have to be returned, if
is_data_requested returns abap_false, paging is not relevant.
• Get the paging information of the UI request into a local variable (ls_paging) by calling the method
get_paging of the interface IF_RAP_QUERY_REQUEST.
For more information about get_paging, see Method get_paging [page 293].
• If the offset is >= 0, pass it to the read-request.
• Pass the page size to the read request if it is not unlimited.
 Note
If all data records are requested, the method returns the constant page_size_unlimited, which
has the value -1. If this constant is returned, the query option $skip must not be passed to the read
request.
"""Request Data

IF io_request->is_data_requested( ).
"""Request Paging
DATA(ls_paging) = io_request->get_paging( ).
IF ls_paging->get_offset( ) >= 0.
lo_read_request->set_skip( ls_paging->get_offset( ) ).
ENDIF.
IF ls_paging->get_page_size( ) <>
if_rap_query_paging=>page_size_unlimited.
lo_read_request->set_top( ls_paging->get_page_size( ) ).
ENDIF.

ENDIF.

Develop PUBLIC 735
5. Execute the Request
The read request for the remote OData service is now equipped with the query options for count
$inlinecount=allpages (if total number of records is requested) and for paging $skip and $top (if data is
requested). At least, these two query options should be implemented in the query implementation class if the
consuming service is a UI service.
 Remember
By default, the UI sends the query options for counting and paging.
Now, the request can be sent. In other words, it is executed on the remote service.
• Execute the request and write it into a local variable lo_response.
"""Execute the Request

DATA(lo_response) = lo_read_request->execute( ).

6. Provide the Count Result for the Response of the Unmanaged Query
The response parameter io_response of IF_RAP_QUERY_PROVIDER~select must be filled with the total
number of records that the count request to the remote service returns.
• Check if the total number of records is requested.

• Get the count from the response of the remote service by calling the method get_count on the remote
service response object.
• Set the returned number for the response to the unmanaged query by calling the method
set_total_number_of_records on the response object of the unmanaged query.
"""Set Count

io_response->set_total_number_of_records( lo_response->get_count( ) ).
ENDIF.

7. Provide the Result Data for the Response of the Unmanaged Query
The response parameter io_response of IF_RAP_QUERY_PROVIDER~select must be filled with the
requested data, which are returned by the remote service and enhanced with the local discount data.
• Check whether data is requested.

• Declare lt_travel with the same type as the generated abstract entity. The data from the remote service
will be written into that table.
• Declare lt_travel_ce with the type of the custom entity. This table is used to fill the output parameter of
the select method.
• Declare lt_traveladd with the type of the local database table. The data from the database table /dmo/
traveladd is read into this table.
• Get the data from the response object of remote service request by calling the method
get_business_data and write it into lt_travel.
• If lt_travel returns entries, provide a mapping for those elements in the custom entity that are not
identical with the names of the abstract entity elements. In our scenario, this concerns the element
Description.
• Select the local data (discounts) based on the entity sets that are retrieved from the remote service.
• Select the latest time stamp for the discount data.

736 PUBLIC Develop
• Calculate the eTag from the values of the lastChangedAt fields of the remote and local service.
 Note
The eTag is used to ensure that discount data has not changed. That is why, the retrieved value is
overwritten with the initial timestamp for the field.
• Calculate the amount for the field TotalPriceWithDiscount if a discount exists.

• If no discount is maintained, fill the field TotalPriceWithDiscount with the value of TotalPrice
without discount and set an initial value for the field lastchangedat.
• Set the returned data for the response to the unmanaged query by calling the method set_data on the
response object of the unmanaged query.
"""Set Data

DATA: lt_travel TYPE STANDARD TABLE OF /dmo/travel_c_a,
lt_travel_ce TYPE STANDARD TABLE OF /dmo/i_travel_c_c,
lt_traveladd TYPE STANDARD TABLE OF /dmo/traveladd.
lo_response->get_business_data( IMPORTING et_business_data =
lt_travel ).
IF lt_travel IS NOT INITIAL.
lt_travel_ce = CORRESPONDING #( lt_travel MAPPING description =
memo ).
SELECT * FROM /dmo/traveladd FOR ALL ENTRIES IN @lt_travel_ce WHERE
travel_id = @lt_travel_ce-travelid INTO TABLE @lt_traveladd.
LOOP AT lt_travel_ce ASSIGNING FIELD-SYMBOL(<fs_travel_ce>).
IF line_exists( lt_traveladd[ travel_id = <fs_travel_ce>-
travelid ] ).
<fs_travel_ce>-discountpct = lt_traveladd[ travel_id =
<fs_travel_ce>-travelid ]-discount_pct.
<fs_travel_ce>-discountabs = lt_traveladd[ travel_id =
<fs_travel_ce>-travelid ]-discount_abs.
<fs_travel_ce>-totalpricewithdiscount = <fs_travel_ce>-
totalprice * ( 1 - <fs_travel_ce>-discountpct / 100 ) - <fs_travel_ce>-
discountabs.
<fs_travel_ce>-lastchangedat = lt_traveladd[ travel_id =
<fs_travel_ce>-travelid ]-lastchangedat.
<fs_travel_ce>-calculatedetag = <fs_travel_ce>-
calculatedetag && '-' && lt_traveladd[ travel_id = <fs_travel_ce>-travelid ]-
lastchangedat.
ELSE.
totalprice.
<fs_travel_ce>-lastchangedat = '20000101120000' .
"initial value Jan 1, 2000, 12:00:00 AM
ENDIF.
ENDLOOP.
ENDIF.
io_response->set_data( lt_travel_ce ).

ENDIF.
Results
 Expand the following listing to view the source code of the query implementation for data retrieval and count:
Query Implementation Class
CLASS /dmo/cl_travel_c_q DEFINITION


Develop PUBLIC 737
PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
PROTECTED SECTION.
PRIVATE SECTION.
ENDCLASS.
CLASS /dmo/cl_travel_c_q IMPLEMENTATION.
"""Instantiate Client Proxy
DATA(lo_client_proxy) = /dmo/cl_travel_cp_aux=>get_client_proxy( ).
TRY.
"""Create Read Request
DATA(lo_read_request) = lo_client_proxy-
"""Request Count
lo_read_request->request_count( ).
ENDIF.
"""Request Data
"""Request Paging
DATA(ls_paging) = io_request->get_paging( ).
IF ls_paging->get_offset( ) >= 0.
lo_read_request->set_skip( ls_paging->get_offset( ) ).
ENDIF.
IF ls_paging->get_page_size( ) <>
if_rap_query_paging=>page_size_unlimited.
lo_read_request->set_top( ls_paging->get_page_size( ) ).
ENDIF.
ENDIF.
"""Execute the Request
DATA(lo_response) = lo_read_request->execute( ).
"""Set Count
io_response->set_total_number_of_records( lo_response->get_count( ) ).
ENDIF.
"""Set Data
DATA: lt_travel TYPE STANDARD TABLE OF /dmo/travel_c_a,
lt_travel_ce TYPE STANDARD TABLE OF /dmo/i_travel_c_c,
lt_traveladd TYPE STANDARD TABLE OF /dmo/traveladd.
lt_travel ).
memo ).
SELECT * FROM /dmo/traveladd FOR ALL ENTRIES IN @lt_travel_ce WHERE
travel_id = @lt_travel_ce-travelid INTO TABLE @lt_traveladd.
LOOP AT lt_travel_ce ASSIGNING FIELD-SYMBOL(<fs_travel_ce>).
travelid ] ).
<fs_travel_ce>-discountpct = lt_traveladd[ travel_id =
<fs_travel_ce>-travelid ]-discount_pct.
<fs_travel_ce>-discountabs = lt_traveladd[ travel_id =
<fs_travel_ce>-travelid ]-discount_abs.
discountabs.
<fs_travel_ce>-lastchangedat = lt_traveladd[ travel_id =
<fs_travel_ce>-travelid ]-lastchangedat.
ELSE.
totalprice.
ENDIF.

738 PUBLIC Develop
ENDLOOP.
ENDIF.
io_response->set_data( lt_travel_ce ).
ENDIF.
EXPORTING
textid = /dmo/cx_travel_serv_cons=>query_failed
ENDTRY.
ENDMETHOD.

ENDCLASS.
If you have defined a UI service for the custom entity (see Cloud Defining an OData Service [page 763]), you
can test your implementation with the SAP Fiori Elements Preview. When you open the app and choose the Go
button, you receive the data and the count from the remote service together with the matching discount data.
Related Information
Implementing an Unmanaged Query [page 917]

Implementing Paging in an Unmanaged Query [page 931]
4.2.6.5.2.2  Cloud Implementing Filtering
Filter options can be delegated to the remote service. Fill the request that is passed to the OData client proxy
with the query option $filter.
Preview
To retrieve the appropriate entries for the filter, you must implement a filter factory to get the filtered results
from the remote service.

Develop PUBLIC 739
This scenario only implements filtering by fields of the remote service. The service proxy API provides a filter
factory to delegate the filter to the remote service. Filtering by local fields is not supported in this scenario.
 Note
To filter by local fields, you would have to retrieve all available data sets of the remote service and merge
the local fields to these first, to be able to filter by discount values then. In this case, paging could not be
delegated to the remote service either and would have to be implemented after data retrieval manually.
Hence filtering for discount values might cause serious performance issues and is therefore not exemplified
in this scenario.
 Note
Filtering on an amount field only works if the end user also provides a filter on the unit field, in our
case a currency code. In our scenario, the fields TotalPrice and BookingFee are amount fields. If a
filter is entered for these fields, the currency code must be in the filter condition as well. Hence, the
implementation must also include the currency every time a filter for the field TotalPrice is supplied.
The filter information is relevant for data and count retrieval. Therefore the implementation for the filter must
be independent of the checks for data or count requests. The filter information must be added to the read
request for the remote service. So the filter implementation must be called before executing the read request.
• The unmanaged query API provides a method to get the filter conditions from the UI OData request into
a local variable. Use io_request->get_filter( )->get_as_ranges( ) to get the filter conditions as
ranges into a local variable lt_filter. Handle the exception if the filter cannot be converted into a ranges
table.
For more information about the unmanaged query filter API, see Interface IF_RAP_QUERY_FILTER [page
296].
• Loop over lt_filter.
 Remember
Some filter requests require special handling before sending them to the remote service:
• Filtering on local fields is not allowed.
• For filtering on an amount field, the unit must be provided in the filter.
• Raise an exception with an adequate message, for example Filtering on &1 is not allowed if filter
is requested for a local field.

740 PUBLIC Develop
For information about how to work with exception classes and message classes, see
and .
• Find out the currency code for filter requests on amount fields.
• Raise an exception if currency code is not provided, for example Currency code is not supplied
for &1.
• Create the filter property to be passed to the remote service. Map the element Description to Memo for
the remote service to match the data model of the remote service.
• Create a filter factory to provide the filter request for the client proxy.
• Create the filter ranges for the remote service by calling the method create_by_range of the filter
factory and export the filter property, the filter range and, if necessary, the currency code.
• If a filter is defined for more than one element, concatenate the filter condition.
• Set the filter for the request.
 Expand the following code sample to view the source code of Request Filtering.
 Sample Code
"""Request Filtering

TRY.
DATA(lt_filter) = io_request->get_filter( )->get_as_ranges( ).
CATCH cx_rap_query_filter_no_range INTO DATA(lx_no_range).
EXPORTING
textid = /dmo/cx_travel_serv_cons=>no_ranges
previous = lx_no_range.
ENDTRY.
LOOP AT lt_filter ASSIGNING FIELD-SYMBOL(<fs_filter>).
IF <fs_filter>-name = 'DISCOUNTPCT' OR
<fs_filter>-name = 'DISCOUNTABS' OR
<fs_filter>-name = 'TOTALPRICEWITHDISCOUNT' OR
<fs_filter>-name = 'CALCULATEDETAG'.
RAISE EXCEPTION TYPE /dmo/cx_travel_query
EXPORTING
textid = /dmo/cx_travel_query=>filtering_failed
element = <fs_filter>-name.
ENDIF.
"provide currency code, if filtering on amount field
IF <fs_filter>-name = 'TOTALPRICE' OR
<fs_filter>-name = 'BOOKINGFEE'.
IF line_exists( lt_filter[ name = 'CURRENCYCODE' ] ).
DATA(lv_currencycode) = VALUE waers_curc( lt_filter[ name =
'CURRENCYCODE' ]-range[ option = 'EQ' ]-low OPTIONAL ).
ELSE.
EXPORTING
textid = /dmo/cx_travel_serv_cons=>no_currencycode
element = <fs_filter>-name.
ENDIF.
ENDIF.
"map element names
DATA(lv_filter_property) = COND /iwbep/
if_cp_runtime_types=>ty_property_path( WHEN <fs_filter>-name ='DESCRIPTION'
THEN 'MEMO'
ELSE <fs_filter>-name ).
"create filter factory for read request
DATA(lo_filter_factory) = lo_read_request->create_filter_factory( ).
"
DATA(lo_filter_for_current_field) = lo_filter_factory-
>create_by_range( iv_property_path = lv_filter_property

Develop PUBLIC 741
it_range = <fs_filter>-range
iv_currency_code = lv_currencycode ).
"Concatenate filter if more than one filter element
DATA: lo_filter TYPE REF TO /iwbep/if_cp_filter_node.
IF lo_filter IS INITIAL.
lo_filter = lo_filter_for_current_field.
ELSE.
lo_filter = lo_filter->and( lo_filter_for_current_field ).
ENDIF.
ENDLOOP.
"set filter
IF lo_filter IS NOT INITIAL.
lo_read_request->set_filter( lo_filter ).

ENDIF.
Results
can test your implementation with the SAP Fiori Elements Preview. You can define filters and check that the UI
only retrieves data that matches the filter request.
Related Information
Implementing Filtering in an Unmanaged Query [page 925]

Interface IF_RAP_QUERY_FILTER [page 296]
4.2.6.5.2.3  Cloud Implementing Column Selections
Select options can be delegated to the remote service. Fill the request that is passed to the OData client proxy
with the query option $select.
Preview
The SAP Fiori UI allows you to select columns.

742 PUBLIC Develop
To retrieve the appropriate data, you must transfer the selected properties to the read request for the remote
service.
You can optimize the performance if you only select those elements from the remote service that are selected
on the UI. The local fields are selected separately. Therefore, you must exclude the local fields from the
requested elements as they are not delegated to the remote service.
Considering the requested elements from the UI when delegating the request to the remote service is only
necessary when data is requested. Therefore the implementation must only be called if data is requested
before the execution of the read request.
• The unmanaged query API provides a method to get those elements that are requested by the UI. Use
DATA(lt_req_elements) = io_request->get_requested_elements( ). to get the elements into
a local variable.
For more information about the unmanaged query API, see Interface IF_RAP_QUERY_REQUEST [page
291].
• Delete the local elements from the properties that are selected.
 Remember
Local fields are not delegated to the remote service. They are selected manually.
• Loop over lt_req_elements and map the element Description to Memo for the remote service to
match the data model of the remote service.

Develop PUBLIC 743
• Declare lt_select_properties and type it as a table of property paths. This table contains the
properties that are given to the client proxy for creating the select query option.
• Fill the table lt_select_properties that is given to the client proxy with the elements to be selected
from the remote service.
• Set the select properties for the OData request of the remote service.
"""Request Elements

DATA(lt_req_elements) = io_request->get_requested_elements( ).
"delete local fields out of the fields to be selected via OData Client
Proxy
DELETE lt_req_elements WHERE table_line = 'DISCOUNTPCT' OR
table_line = 'DISCOUNTABS' OR
table_line = 'TOTALPRICEWITHDISCOUNT' OR
table_line = 'CALCULATEDETAG'.
"map differing names
LOOP AT lt_req_elements ASSIGNING FIELD-SYMBOL(<fs_req_elements>).
DATA(lv_select_property) = COND /iwbep/
if_cp_runtime_types=>ty_property_path( WHEN <fs_req_elements> ='DESCRIPTION'
THEN 'MEMO'
ELSE <fs_req_elements> ).
DATA: lt_select_properties TYPE /iwbep/
if_cp_runtime_types=>ty_t_property_path.
APPEND lv_select_property TO lt_select_properties.
ENDLOOP.
"set select properties
IF lt_select_properties IS NOT INITIAL.
lo_read_request->set_select_properties( lt_select_properties ).

ENDIF.
Results
can test your implementation with the SAP Fiori Elements Preview. Trigger the selection by choosing columns
on the SAP Fiori UI and check whether the request works.
Related Information

Considering Requested Elements in an Unmanaged Query [page 935]

744 PUBLIC Develop
4.2.6.5.2.4  Cloud Implementing Sorting
Sorting options can be delegated to the remote service. Fill the request that is passed to the OData client proxy
with the relevant query option $orderby.
Preview
To retrieve the data in the appropriate order, you must add sorting information to the request for the OData
client proxy.
This scenario only implements sorting by fields of the remote service. The service proxy API provides the
method set_order_by to delegate the sorting order to the remote service.
 Note
To sort by local fields, you would have to retrieve all available data sets of the remote service and merge
the local fields to these first, to be able to sort by discount values then. In this case, paging could not be
delegated to the remote service either and would have to be implemented after data retrieval manually.
Hence, sorting by discount values might cause serious performance issues and is therefore not exemplified
in this scenario.
The sorting information is only relevant if you retrieve data. Therefore the implementation must only be called if
data is requested to equip the read request for the remote service with this information.
• The unmanaged query API provides a method to get the sorting information. Use DATA(lt_sort) =
io_request->get_sort_elements( ). to get the sorting information into a local variable.
For more information about the unmanaged query API, see Interface IF_RAP_QUERY_REQUEST [page
291].
• Loop over lt_sort.
 Remember
Sorting on local elements is not supported due to performance reasons.

Develop PUBLIC 745
• Raise an exception with an adequate message, for example Sorting on &1 is not allowed.
For information about how to work with exception classes and message classes, see
and .
• Declare lt_sort_properties. This table is passed to the client proxy with the elements to be sorted.
• Map the element Description to Memo for the remote service to match the data model of the remote
service.
• Fill the table lt_sort_properties that is given to the client proxy with the elements to be selected from
the remote service and map the columns.
• Set the sorting properties for the request by using the set_orderby.
"""Request Sorting

DATA(lt_sort) = io_request->get_sort_elements( ).
LOOP AT lt_sort ASSIGNING FIELD-SYMBOL(<fs_sort>).
IF <fs_sort>-element_name = 'DISCOUNTPCT' OR
<fs_sort>-element_name = 'DISCOUNTABS' OR
<fs_sort>-element_name = 'TOTALPRICEWITHDISCOUNT' OR
<fs_sort>-element_name = 'CALCULATEDETAG'.
RAISE EXCEPTION TYPE /dmo/cx_travel_query
EXPORTING
textid = /dmo/cx_travel_query=>sorting_failed
element = <fs_sort>-element_name.
ENDIF.
"map differing names
DATA: lt_sort_properties TYPE /iwbep/
if_cp_runtime_types=>ty_t_sort_order.
APPEND VALUE #( property_path = COND #( WHEN <fs_sort>-element_name
= 'DESCRIPTION' THEN 'MEMO'
ELSE <fs_sort>-element_name )
descending = <fs_sort>-descending )
TO lt_sort_properties.
ENDLOOP.
"set sorting properties
IF lt_sort_properties IS NOT INITIAL.
lo_read_request->set_orderby( lt_sort_properties ).
ENDIF.

ENDIF.
Results
can test your implementation with the SAP Fiori Elements Preview. Try out the sorting on different elements
and check whether the results are sorted or an exception is thrown.
Related Information

Implementing Sorting in an Unmanaged Query [page 933]

746 PUBLIC Develop
4.2.6.5.3  Cloud Adding Transactional Behavior to the
Business Object
The following steps guide you through the implementation steps to update a business object when a remote
service is merged with local data.
Like in Developing Unmanaged Transactional Apps [page 481], creating, updating, and deleting data requires a
transactional runtime implementation. The service consumption scenario is also a use case for the unmanaged
implementation type as the transactional logic is defined and implemented by the application developer. That
means, the transactional behavior must be defined in a behavior definition and has to be implemented in ABAP
classes of a behavior pool.
 Note
This scenario only supports transactional activities on the data that is persisted on a database table in the
consuming tenant. Transactional operations on the remote service are not supported.
In this example scenario, only the discount data can be manipulated by the end user. The fields on the database
table /dmo/traveladd that can be changed are discount_pct and discount_abs. The travel instance for
which the discount is maintained is identified by the travel ID, which is retrieved from the remote service.
Travel ID is a key field and therefore cannot be changed by the end user. For the eTag check, a distinct
field CalculatedeTag is used. Its value is concatenated with the timestamp of the remote service and the
timestamp from the local databse table.
The following tasks are relevant to include transactional behavior for the business object:
• Cloud Defining a Behavior for the Business Object [page 747]

• Cloud Implementing the Behavior Pool for the Business Object [page 750]
4.2.6.5.3.1  Cloud Defining a Behavior for the Business

Object
The transactional behavior of the travel business object must be defined in a behavior definition.
To get transactional access to the local data, the data model must be turned into a business object. The
custom entity /DMO/I_TRAVEL_C_C must be defined as root entity.
1. Open the custom entity /DMO/I_TRAVEL_C_C and insert the keyword root. A behavior definition can only
be created for a root entity.
define root custom entity /DMO/I_TRAVEL_C_C

2. Activate the root custom entity.

Develop PUBLIC 747
Creating a Behavior Definition /DMO/I_TRAVEL_C_C
By creating a behavior definition, the referenced root entity gains a transactional character. In the behavior
definition, you define the transactional capabilities of your business object. It is directly related to the root
custom entity and must therefore have the same name /DMO/I_TRAVEL_C_C.
1. In the Project Explorer, select the relevant node for the data definition that contains the CDS root
entity /DMO/I_TRAVEL_C_C, for which you want to create a behavior definition.
2. Open the context menu and select New Behavior Definition to launch the creation wizard.
3. Follow the steps of the creation wizard to create the behavior definition
 Note
The implementation type of a custom entity can only be unmanaged. That is why, the wizard only
allows this option.
Result
The created behavior definition object represents the root node of a new business object in ABAP RESTful
application programming model.
In the Project Explorer, the new behavior definition is added to the Core Data Services folder.
Defining the Behavior for the Travel Business Object with Discount Data
For the service consumption scenario, only the unmanaged implementation type is supported. That means,
you as an application developer must implement the essential components of the business object yourself.
 Remember
Our scenario is limited to modifying the data that is stored on the database table /dmo/traveladd.
For a detailed description on the unmanaged implementation type, see CDS BDL - implementation type (ABAP
- Keyword Documentation).
Looking at the data model of the custom entity and its data sources, that means that only the discount data
can be modified.

748 PUBLIC Develop
The description of modifying the data that is exposed by the remote service is out of scope of this document.
Nevertheless, each manipulation of the persistent data requires the retrieval of the remote data, as the
discount data can only be stored in conjunction with the travel ID to match the discount to the relevant travel
entry of the remote service. That is why, the creation of new discounts for a travel entry is considered as an
update on a certain travel instance of the business object. In the case of creating a data set of discount data,
you change the discount from the initial value but the key entry (TRAVEL_ID) is already there.
Compare the UI when retrieving the travel data merged with the discount data. The discount fields are
displayed with the initial values if no discount data is maintained for the relevant travel instances.
The modification of discount data is an UPDATE. Hence, we do not need to implement neither the CREATE nor
the DELETE operation to maintain discount data.
A distinct field must be indicated as ETag [page 35] in the behavior definition. The eTag checks that the data
the end user sees that on the UI is consistent with the data on the database and has not been changed in the
meantime. The element CalculatedEtag is used for this purpose and calculated with data from the database
table /dmo/traveladd and the remote service. This ensure that neither the remote data nor the local data
can be changed without the end user knowing the change.
The newly created behavior definition requires
• defining an update (delete the definitions of create and delete if they are generated)

Develop PUBLIC 749
• defining the field for the eTag
The following code block displays the behavior definition with the definitions that are relevant for the
transactional behavior of the business object.

define behavior for /DMO/I_TRAVEL_C_C alias Travel_CE
etag calculatedetag
{
update;

}
 Note
For better usability in the behavior implementation, you can define an alias for the business object in the
Related Information
Adding Behavior to the Business Object [page 509]
4.2.6.5.3.2  Cloud Implementing the Behavior Pool for the

Business Object
The implementation of behavior is done in the local types of an ABAP class.
Creating a Behavior Pool /DMO/BP_TRAVEL_C_C
A behavior pool for a behavior implementation is needed to implement the behavior that was defined in a
behavior definition. A behavior pool is a special ABAP class that is equipped with the extension FOR BEHAVIOR
OF and references the root entity of the relevant business object.
1. In the Project Explorer, select the relevant behavior definition for which you want to create a behavior
2. Open the context menu and select New Behavior Implementation to launch the creation wizard.
3. Follow the steps of the creation wizard and check if the suggested entries are correct.
Result
The generated global class pool provides you with the extension FOR BEHAVIOR OF with reference to
the behavior definition. This statement determines the connection to the business object. One behavior
implementation can only define the behavior for one business object.
In the local types, a handler class with an UPDATE method for modify [page 140] is generated. The generated
saver class contains the methods FINALIZE, CHECK_BEFORE_SAVE, and SAVE, the predefined standard
methods for the save sequence.

750 PUBLIC Develop
Runtime Logic for Transactional Behavior in the Service Consumption

Scenario
In a service consumption scenario, the transactional behavior for the business object (the updating of discount
data) must be implemented in the local types of a behavior pool. The implementation includes the data
retrieval from the remote service, merging the remote data with the local discount data and finally updating
the local discount data. Hence, the logic of how to access a foreign system also comes into play when updating
local data. To keep performance expenses on a low level, it is indispensable to work with a transactional buffer
and retrieve the remote data only once in one unit of work. Therefore we use a local buffer class to work actively
with a transactional buffer.
The runtime of an update operation of the discount data is displayed in the following diagram. It illustrates how
the methods for READ, MODIFY, and SAVE and the local buffer class interact with each other and how the OData
client proxy is used to request the necessary data from the remote service.
Transactional Runtime of the Travel BO
BUFFER
Due to performance reasons, it is useful to work with the transactional buffer in the service consumption
scenario. Retrieving data from the remote service is very costly. Therefore, the data from the remote service
should only be read once in one logical unit of work. We use the buffer as intermediate storage for data retrieval
and processing.
The READ, MODIFY, and SAVE methods call dedicated methods from the buffer to process data. These buffer
methods are:
• get_data
To receive data the Client Proxy is used. To instantiate the client proxy object, the method
get_client_proxy is called. With this request object, you can define the resource object of the entity

Develop PUBLIC 751
set and define the HTTP operation. After the execution, the data can be read from the response object
returned by the execution.
In case of an error, the FAILED table is filled and can be used to raise an application error.
• get_client_proxy
This method establishes a cloud destination to the provisioning tenant and instantiates the client proxy.
The destination is used at runtime for retrieving data from the remote service.
• put_data
This method calls get_data to retrieve the remote data. Additionally, it updates the local discount data for
the retrieved entity and calculates the total price with discount. Finally, the method merges the remote and
local data.
If there is an error, the FAILED table is filled and can be used to raise an application error.
A detailed step-by-step description for the implementation of the local buffer class is given in Cloud
Implementing the Buffer Class [page 753].
read_travel FOR READ
For the ETag check (which is necessary for the UPDATE operation), a method for the READ operation must be
implemented.
The latest timestamp of the field lastchangedat from /dmo/traveladd is used to compare with the data in
Last changed on that is displayed on the UI. Only if these timestamps are equal is the UPDATE triggered.
 Remember
The field lastchangedat is filled with the time stamp of the last modification of the discount data. In our
example scenario, only the timestamp from the database table /dmo/traveladd is relevant as only these
fields can be updated.
The eTag field is filled with the initial value if no discount is maintained for a certain travel instance.
 Note
The example implementation in this guide does not only retrieve the data from the relevant ETag fields,
but reads the whole data set when the READ operation is executed, including the merge with the persistent
data. This is done for performance reasons. To calculate the total price with discount, the value of the field
TotalPrice from the remote instance is needed. Therefore it is more convenient to read the whole data
set once, store it in the buffer and use this data set for the calculation on the update.
A detailed step-by-step description for the implementation of the READ is given in Cloud Implementing the
READ [page 758].
For general information about the READ method, see <method> FOR READ [page 145].
update_discount FOR MODIFY
The real update takes place during the MODIFY operation. The method update_discount calls the buffer
method put_data, which uses the method get_data to retrieve the data from the buffer (if available). The
discount data is updated and the entry for the transient field TotalPriceWithDiscount is calculated.
The method update_discount also calls the method _map_messages, which wraps the messages to write
them in the REPORTED table.

752 PUBLIC Develop
A detailed step-by-step description for the implementation of the MODIFY is given in Cloud Implementing the
MODIFY [page 759].
For general information about the MODIFY method, see <method> FOR MODIFY [page 140].
SAVE
The save method writes the updated data to the database. It uses the method get_data to retrieve the
updated data from the buffer. It generates a new time stamp to fill the field lastchangedat on the database
table /dmo/traveladd. At last, it persists the updated data on the database table.
A detailed step-by-step description is given in Cloud Implementing the SAVE [page 762].
For general information about the SAVE method, see SAVE [page 231].
In this service consumption scenario, the READ and the MODIFY method, including a _map_messages method
are treated in one handler class, as the retrieved data from the READ is reused in the MODIFY method. This
relies to the Best Practices for Modularization and Performance [page 514].
This guide starts with the implementation of the buffer and consequently describes calls of the buffer methods
from the predefined methods READ, MODIFY, and SAVE.
• Cloud Implementing the Buffer Class [page 753]

• Cloud Implementing the READ [page 758]
• Cloud Implementing the MODIFY [page 759]
• Cloud Implementing the SAVE [page 762]
4.2.6.5.3.2.1  Cloud Implementing the Buffer Class
The local buffer class serves as intermediate storage for the data processing in the service consumption
scenario. It is a separate local class in the behavior pool.
Creating a Buffer Class

The buffer must be accessed from the predefined methods READ, MODIFY, and SAVE.
1. Create a local buffer class lcl_buffer in the local types of the behavior implementation pool.
2. Set the local class to PRIVATE.
Listing: Local Buffer Class
CLASS lcl_buffer DEFINITION CREATE PRIVATE.

ENDCLASS.
CLASS lcl_buffer IMPLEMENTATION.

ENDCLASS.


Develop PUBLIC 753
Creating a Buffer Instance
When working with a transactional buffer to store and process data, an instance of the buffer must be created
at first. The singleton pattern is used to ensure that there is only one existing buffer instance of the application
buffer.
1. Declare the static method get_instance which returns a buffer instance in the public section of the
buffer class
2. Implement get_instance to receive a buffer instance if no instance exists
Listing: Declaration and Implementation of get_instance

PUBLIC SECTION.
CLASS-METHODS get_instance
RETURNING VALUE(ro_instance) TYPE REF TO lcl_buffer.
PRIVATE SECTION.
CLASS-DATA: go_instance TYPE REF TO lcl_buffer.

ENDCLASS.

METHOD get_instance.
IF go_instance IS NOT BOUND.
go_instance = NEW #( ).
ENDIF.
ro_instance = go_instance.
ENDMETHOD.

ENDCLASS.
Retrieving Data from the Remote Service
The following listing represents the signature and implementation of the method get_data that retrieves data
from the remote service, if it is not already in the buffer. The implementation of the method includes
1. checking whether the travel instance for which discount data is to be updated is already in the buffer
and writing it to the exporting parameter et_travel, if available in the buffer. If not in the buffer, the
travel_id has to be collected to retrieve the relevant data from the persistence.
2. the instantiation of a client proxy, by calling the method get_client_proxy of the auxiliary class /DMO/
CL_TARVEL_CP_AUX, see Cloud Creating a Remote Client Proxy [page 728].
3. a reading request for the client proxy with a filter for only requesting the data set for the specific travel ID
4. a select to get and calculate the matching discount data from the database table /dmo/traveladd and to
process the time stamp for the ETag field. A concatenated eTag from the fields lastchangedat of both,
the remote and the local service, is used.
5. calculating the TotalPriceWithDiscount and setting an initial time stamp if no discount data has
changed. .
 Remember
The eTag is used to ensure that discount data has not changed. That is why, the retrieved value is not
used for the eTag check but the concatenated value is passed to the UI.
6. filling the FAILED table if the travel id is not found.

and
7. error handling if the access to the remote system fails.

754 PUBLIC Develop
 Note
If you want to display a suitable message, you need to create a message class. For example, here, the
message Accesss to remote system cannot be established is convenient. It is retrieved from the
message class /DMO/CM_SERV_CONS.
For information about how to create a message class, see .
Listing: Declaration and Implementation of get_data Expand the following code sample to view the source
code of Declaration and Implementation of get_data.
 Sample Code

PUBLIC SECTION.
CLASS-METHODS get_instance
RETURNING VALUE(ro_instance) TYPE REF TO lcl_buffer.
"types used in get_data
TYPES: BEGIN OF ts_message,
travelid TYPE /dmo/i_travel_c_c-travelid,
symsg TYPE symsg,
fields TYPE string_table,
END OF ts_message,
tt_travel TYPE STANDARD TABLE OF /dmo/i_travel_c_c,
tt_travel_in TYPE TABLE FOR READ IMPORT /dmo/i_travel_c_c,
tt_travel_out TYPE TABLE FOR READ RESULT /dmo/i_travel_c_c,
tt_travel_failed TYPE TABLE FOR FAILED /dmo/i_travel_c_c,
tt_message TYPE STANDARD TABLE OF ts_message.
METHODS get_data
IMPORTING it_travel TYPE tt_travel_in OPTIONAL
EXPORTING et_travel TYPE tt_travel_out
et_travel_failed TYPE tt_travel_failed
et_message TYPE tt_message
RAISING /dmo/cx_travel_query.
PRIVATE SECTION.
CLASS-DATA: go_instance TYPE REF TO lcl_buffer.
DATA: mt_travel TYPE tt_travel.

ENDCLASS..

...
METHOD get_data.
DATA: lt_travel TYPE STANDARD TABLE OF /dmo/travel_c_a.
DATA: ls_result LIKE LINE OF et_travel.
DATA: lt_travel_id TYPE STANDARD TABLE OF /dmo/i_travel_c_c-travelid.
DATA: lt_filter TYPE RANGE OF /dmo/i_travel_c_c-travelid.
DATA: ls_filter LIKE LINE OF lt_filter.
DATA: lt_travel_ce TYPE STANDARD TABLE OF /dmo/i_travel_c_c.
DATA: lt_traveladd TYPE STANDARD TABLE OF /dmo/traveladd.
FIELD-SYMBOLS: <fs_travel_ce> LIKE LINE OF lt_travel_ce.
IF it_travel IS SUPPLIED.
LOOP AT it_travel ASSIGNING FIELD-SYMBOL(<fs_travel>).
IF line_exists( mt_travel[ travelid = <fs_travel>-travelid ] ).
ls_result = CORRESPONDING #( mt_travel[ travelid = <fs_travel>-
travelid ] ).
" collect from buffer for result
APPEND ls_result TO et_travel.
ELSE.
" collect to retrieve from persistence
APPEND <fs_travel>-travelid TO lt_travel_id.
ENDIF.
ENDLOOP.
IF lt_travel_id IS NOT INITIAL.

Develop PUBLIC 755
TRY.
DATA(lo_client_proxy) = /dmo/
cl_travel_cp_aux=>get_client_proxy( ).
DATA(lo_request) = lo_client_proxy-
lt_filter = VALUE #( FOR travel_id IN lt_travel_id ( sign = 'I'
option = 'EQ' low = travel_id ) ).
DATA(lo_filter) = lo_request->create_filter_factory( )-
>create_by_range( iv_property_path = 'TRAVELID'
it_range = lt_filter ).
lo_request->set_filter( lo_filter ).
DATA(lo_response) = lo_request->execute( ).
" get relevant data sets
lt_travel ).
" add local data
" map OData service to custom entity
memo ).
SELECT * FROM /dmo/traveladd FOR ALL ENTRIES IN @lt_travel_ce
WHERE travel_id = @lt_travel_ce-travelid INTO TABLE @lt_traveladd.
LOOP AT lt_travel_id ASSIGNING FIELD-SYMBOL(<fs_travel_id>).
IF line_exists( lt_travel_ce[ travelid = <fs_travel_id> ] ).
ASSIGN lt_travel_ce[ travelid = <fs_travel_id> ] TO
<fs_travel_ce>.
travelid ] ).
<fs_travel_ce>-discountpct =
lt_traveladd[ travel_id = <fs_travel_ce>-travelid ]-discount_pct.
<fs_travel_ce>-discountabs =
lt_traveladd[ travel_id = <fs_travel_ce>-travelid ]-discount_abs.
discountabs.
<fs_travel_ce>-lastchangedat =
lt_traveladd[ travel_id = <fs_travel_ce>-travelid ]-lastchangedat.
<fs_travel_ce>-calculatedetag = <fs_travel_ce>-
calculatedetag && '-' && lt_traveladd[ travel_id = <fs_travel_ce>-travelid ]-
lastchangedat.
ELSE.
totalprice.
ENDIF.
ls_result = CORRESPONDING #( <fs_travel_ce> ).
APPEND <fs_travel_ce> TO mt_travel.
APPEND ls_result TO et_travel.
ELSE.
APPEND VALUE #( travelid = <fs_travel_id> ) TO
et_travel_failed.
APPEND VALUE #( travelid = <fs_travel_id>
symsg-msgty = 'E'
symsg-msgid = '/DMO/CM_SERV_CONS'
symsg-msgno = '004'
symsg-msgv1 = <fs_travel_id> )
TO et_message.
ENDIF.
ENDLOOP.
ENDIF.
CATCH /iwbep/cx_gateway.
et_travel_failed = CORRESPONDING #( lt_travel_id MAPPING travelid
= table_line ).
et_message = CORRESPONDING #( lt_travel_id MAPPING travelid =
table_line ).
LOOP AT et_message ASSIGNING FIELD-SYMBOL(<fs_message>).

756 PUBLIC Develop
<fs_message>-symsg-msgty = 'E'.
<fs_message>-symsg-msgid = '/DMO/CM_SERV_CONS'.
<fs_message>-symsg-msgno = '001'.
ENDLOOP.
ENDTRY.
ENDIF.
ELSE.
et_travel = CORRESPONDING #( mt_travel ).
ENDIF.

ENDMETHOD.
Updating the Discount Data

With the preceding method, the data is retrieved from the remote service into the buffer. The essence of the
UPDATE operation, however, is done with the method put_data. It uses the data in the buffer, which is already
enriched with the additional discount data from the database table /dmo/traveladd, and writes the new
discount data in the buffer. This is done by
1. calling the method get_data to retrieve the data from the buffer
2. looping at it_travel_upd to identify the changed fields
3. overwriting the changed fields with the new discount data
4. calculating the data for TotalPriceWithDiscount
5. filling the FAILED table in case the total price with discount is negative after discount calculation.
 Note
If you want to display a suitable message, you need to add a message to the message class /DMO/
CM_SERV_CONS. In this case, an exception needs to be thrown if the Total Price with Discount is
negative. For example, here, the message Total Price with Discount must be greater than
0 is convenient.
For information about how to create a message class, see .
6. writing the updated data set to the buffer.
Listing: Declaration and Implementation of put_data Expand the following code sample to view the source
code of Declaration and Implementation of put_data.
 Sample Code

PUBLIC SECTION.
"types used in put_data
TYPES:
tt_travel_upd TYPE TABLE FOR UPDATE /dmo/i_travel_c_c,
tt_travel_mapped TYPE TABLE FOR MAPPED /dmo/i_travel_c_c.
METHODS put_data
IMPORTING it_travel_upd TYPE tt_travel_upd
EXPORTING et_travel_failed TYPE tt_travel_failed
et_message TYPE tt_message.
...

ENDCLASS.

...
METHOD put_data.
get_data(
EXPORTING it_travel = CORRESPONDING #( it_travel_upd mapping
%key = %key except * )

Develop PUBLIC 757
IMPORTING et_travel = data(lt_travel)
et_travel_failed = DATA(lt_travel_failed)
et_message = DATA(lt_message)
).
LOOP AT it_travel_upd ASSIGNING FIELD-SYMBOL(<fs_travel_upd>).
CHECK line_exists( lt_travel[ KEY entity COMPONENTS travelid =
<fs_travel_upd>-travelid ] ).
ASSIGN lt_travel[ KEY entity COMPONENTS travelid = <fs_travel_upd>-
travelid ] TO FIELD-SYMBOL(<fs_travel>).
IF <fs_travel_upd>-%control-DiscountAbs = if_abap_behv=>mk-on.
<fs_travel>-DiscountAbs = <fs_travel_upd>-DiscountAbs.
ENDIF.
IF <fs_travel_upd>-%control-DiscountPct = if_abap_behv=>mk-on.
<fs_travel>-DiscountPct = <fs_travel_upd>-DiscountPct.
ENDIF.
ENDLOOP.
" Postprocessing
LOOP AT lt_travel ASSIGNING FIELD-SYMBOL(<fs_traveladdinfo>).
DATA(lv_totalpricediscount) = <fs_traveladdinfo>-totalprice * ( 1 -
<fs_traveladdinfo>-discountpct / 100 ) - <fs_traveladdinfo>-discountabs.
IF lv_totalpricediscount >= 0.
<fs_traveladdinfo>-totalpricewithdiscount = lv_totalpricediscount.
ELSE.
APPEND VALUE #( travelid = <fs_traveladdinfo>-travelid ) TO
et_travel_failed.
APPEND VALUE #( travelid = <fs_traveladdinfo>-travelid
symsg-msgty = 'E'
symsg-msgid = '/DMO/CM_SERV_CONS'
symsg-msgno = '009'
symsg-msgv1 = <fs_traveladdinfo>-travelid
symsg-msgv2 = |{ lv_totalpricediscount NUMBER =
USER }|
fields = VALUE #( ( |discountpct| )
( |discountabs| )
)
)
TO et_message.
ENDIF.
ENDLOOP.
"save data in buffer
mt_travel = CORRESPONDING #( lt_travel ) .
ENDMETHOD.

ENDCLASS.
4.2.6.5.3.2.2  Cloud Implementing the READ
The READ is necessary for ETag check.
The READ method processes reading requests. Hence, it is necessary to retrieve the data from the field
lastchangedat.
This implementation does not only retrieve the time stamp, which is used for the eTag check, but the whole
data set to store it in the buffer and use it in the actual UPDATE phase without retrieving the data again. The
implementation must ensure that this data is retrieved and handed over to the framework, which handles the
comparison with the time stamp of the UI. It is also the framework that prevents the update if the time stamps
do not match.
See <method> FOR READ [page 145] for information about parameters of the READ.

758 PUBLIC Develop
Declaring a method for READ
A code template for the READ method is generated automatically if an update is declared in the behavior
definition.
1. Rename the method for read in the definition part of the handler class with the importing parameter
it_travel_read and the result parameter et_traveladdinfo, which is used for the ETag check. The
implementation.
CLASS lhc_travel_update DEFINITION INHERITING FROM cl_abap_behavior_handler.

PRIVATE SECTION.
METHODS read_travel FOR READ
IMPORTING it_travel_read FOR READ travel_ce
RESULT et_traveladdinfo.
...

ENDCLASS.
Implementing the method for READ

The actual READ is done by the method get_data in the buffer class. It either retrieves the data from the
remote system into the buffer or reads the data from the buffer. The data is provided with the result parameter
et_traveladdinfo. The method read_travel instantiates the buffer and calls the method get_data.
1. Instantiate the buffer with the method get_instance.

2. Call the get_data method of the buffer class to get the data into et_traveladdinfo.
If the READ does not return the requested instance, the key of the instance to be read must be written in
the failed table.
 Remember
The failed table is an implicit changing parameter of the READ method.
METHOD read_travel.

DATA(lo_buffer) = lcl_buffer=>get_instance( ).
lo_buffer->get_data(
EXPORTING
it_travel = it_travel_read
IMPORTING
et_traveladdinfo = et_traveladdinfo
et_travel_failed = failed-travel_ce
).

ENDMETHOD.
4.2.6.5.3.2.3  Cloud Implementing the MODIFY
The MODIFY updates data.
The MODIFY method is called by the framework when an UPDATE is defined in the behavior definition. It
modifies the data in the application buffer. In this consumption scenario, the buffer method put_data is called
to do this. To return adequate messages, the MODIFY method also includes a mapping method for messages.
Declaring a method for MODIFY

The declaration of the MODIFY method is generated by the template for the behavior implementation as the
UPDATE was declared in the behavior definition.

Develop PUBLIC 759
1. Change the name of the MODIFY method to the more transparent name update_discount.
Change the name of the importing parameter into it_travel_update.

PRIVATE SECTION.
...
METHODS update_discount FOR MODIFY
IMPORTING it_travel_update FOR UPDATE travel_ce.
...

ENDCLASS.
Implementing the method for MODIFY

The real update is done by the method put_data in the buffer class. This method firstly calls the method
get_data to retrieve the data from the buffer or get it from the remote service. Then it updates the discount
data for the selected travel instance and calculates the amount for TotalPriceDiscount.
For the processing of the appropriate messages if there is a fault event, the method _map_messages is called
within the method update_discount.
1. Instantiate the buffer with the method get_instance.

2. Call the put_data method of the buffer class to update the discount data for the selected travel ID.
If the UPDATE does not work, the key of the failed travel instance must be written in the failed table.
 Remember
The failed table is an implicit changing parameter of the method for MODIFY.
Write the messages of put_data into a local table lt_message.

3. Call the _map_messages method to map lt_message to the reported table.
 Remember
The reported table is an implicit changing parameter of the method for MODIFY.
METHOD update_discount.

lo_buffer->put_data(
EXPORTING
it_travel_upd = it_travel_update
IMPORTING
et_travel_failed = failed-travel_ce
et_message = DATA(lt_message)
).
_map_messages(
EXPORTING
it_message = lt_message
IMPORTING
et_travel_reported = reported-travel_ce
).

ENDMETHOD.

760 PUBLIC Develop
Message Handling
In case of failure, the issue has to be transferred to the REPORTED table, which includes all instance-specific
messages. For the processing of such messages, the method _map_messages is used. In the consumption
scenario, it is defined in the local handler class, as it is only used in the MODIFY method.
Declare _map_messages
1. Declare the method _map_messages with an importing parameter it_message that is compatible to the
type the method put_data returns for messages; and an exporting parameter et_travel_reported
that is compatible to the reported table of the travel entity.

PRIVATE SECTION.
...
TYPES: tt_travel_reported TYPE TABLE FOR REPORTED /dmo/
i_travel_ce.
METHODS: _map_messages
IMPORTING it_message TYPE lcl_buffer=>tt_message
EXPORTING et_travel_reported TYPE tt_travel_reported.
...

ENDCLASS.
Implement _map_messages
To write messages to the REPORTED table, they have to align with a fixed structure. Messages for this structure
are created via the method new_message, which is inherited from the interface IF_ABAP_BEHV_MESSAGE.
1. For each message in it_message, create a new message for the REPORTED table by calling the method
new_message.
2. Fill the relevant fields in ls_travel_reported with the travel_id of the message and change the flag
for the element which causes the message.
METHOD _map_messages.

DATA: ls_travel_reported LIKE LINE OF et_travel_reported.
FIELD-SYMBOLS: <fs_element> TYPE data.
LOOP AT it_message ASSIGNING FIELD-SYMBOL(<fs_message>).
CLEAR ls_travel_reported.
ls_travel_reported-%msg = new_message( id = <fs_message>-symsg-
msgid
number = <fs_message>-symsg-
msgno
severity =
v1 = <fs_message>-symsg-
msgv1
msgv2
msgv3
msgv4 ).
IF <fs_message>-travelid IS NOT INITIAL.
ls_travel_reported-%key-travelid = <fs_message>-travelid.
ls_travel_reported-travelid = <fs_message>-travelid.
LOOP AT <fs_message>-fields ASSIGNING FIELD-SYMBOL(<fs_field>).
ASSIGN COMPONENT <fs_field> OF STRUCTURE ls_travel_reported-
%element TO <fs_element>.
CHECK sy-subrc = 0.
<fs_element> = if_abap_behv=>mk-on.

Develop PUBLIC 761
ENDLOOP.
APPEND ls_travel_reported TO et_travel_reported.
ENDIF.
ENDLOOP.

ENDMETHOD.
4.2.6.5.3.2.4  Cloud Implementing the SAVE
The template for the behavior implementation provides you with the method declarations for redefinitions of
the save sequence.
CLASS lsc_travel DEFINITION INHERITING FROM cl_abap_behavior_saver.

PROTECTED SECTION.

ENDCLASS.
 Note
In this consumption scenario, we do not exemplify the implementation for finalize and
check_before_save as both of the implementations are optional and not required in our sample
scenario.
In the method SAVE, the transactional buffer is saved to the database. The following listing illustrates the
procedure for the SAVE implementation. The saving action includes
1. instantiating of the buffer instance

2. calling the method get_data to get the updated data set
3. retrieving the latest time stamp
4. modifying the database table /dmo/traveladd
CLASS lsc_travel_update IMPLEMENTATION.

METHOD finalize.
ENDMETHOD.
METHOD check_before_save.
ENDMETHOD.
METHOD save.
DATA: ls_traveladd TYPE /dmo/traveladd.
lo_buffer->get_data(
IMPORTING
et_travel = DATA(lt_travel)
).
LOOP AT lt_travel ASSIGNING FIELD-SYMBOL(<fs_traveladdinfo>).
ls_traveladd = CORRESPONDING #( <fs_traveladdinfo> MAPPING travel_id =
travelid
discount_pct =
discountpct
discount_abs =
discountabs ).
GET TIME STAMP FIELD ls_traveladd-lastchangedat.
MODIFY /dmo/traveladd FROM @ls_traveladd.
ENDLOOP.
ENDMETHOD..

ENDCLASS.

762 PUBLIC Develop
4.2.6.6  Cloud Defining an OData Service
In order to be able to consume the service with an SAP Fiori UI, you need to create an OData service.
1. Follow the development steps as described in Creating an OData Service [page 323].
Create a service definition and a service binding to expose the CDS custom entity including its query
implementation for a service. You only need to include the custom entity in the service definition, its
implementation is included implicitly.
You can then test the resulting UI service by using the Fiori Elements Preview in the service binding.
2. Follow the steps described in Designing the User Interface for a Fiori Elements App [page 332]
Use @UI annotations to define the UI of the SAP Fiori app. UI annotations are maintained in the CDS
custom entity in exactly the same way as in CDS views.
For this consumption scenario, it is convenient to label the element for line items and identification
annotations as the data element information is not retrieved from the remote service.
 Note
For selection fields, it is not possible to maintain a label in the @UI annotations. Use the
@EndUser.label annotation instead for elements with selection fields.
 Expand the following listing to view the source code of the travel CDS view.
@EndUserText.label: 'CE for Service Consumption Scenario'

@QueryImplementedBy: '/DMO/CL_TRAVEL_C_Q' //reference to query
implementation class
@UI.headerInfo:{ typeName: 'Trip',
typeNamePlural: 'Trips'}
define root custom entity /DMO/TRAVEL_C_C

{
@UI.facet : [
{ id : 'Travel',
purpose : #STANDARD,
type : #IDENTIFICATION_REFERENCE,
label : 'Travel',
position : 10 } ]
@UI : {lineItem: [ { position: 10, label: 'Travel
ID', importance: #HIGH } ],
selectionField: [ { position: 10 }],
identification: [{ position: 10 , label:
'Travel ID' }] }
@EndUserText.label : 'Travel ID'
@UI : {lineItem: [ { position: 20, label: 'Agency
identification: [{ position: 20, label:
'Agency ID' }] }
@EndUserText.label : 'Agency ID'
@UI : {lineItem: [ { position: 30, label: 'Customer
identification:[ { position: 30 , label:
'Customer ID'} ] }
@EndUserText.label : 'Customer ID'
@UI : {lineItem: [ { position: 40, label: 'Starting
Date', importance: #MEDIUM } ],

Develop PUBLIC 763
identification:[ { position: 40, label:
'Starting Date' } ] }
@UI : {lineItem: [ { position: 45, label: 'End
Date', importance: #MEDIUM } ],
'End Date' } ] }
@UI : {identification:[ { position: 60, label:
'Booking Fee' } ] }
@UI : {lineItem: [ { position: 70, label: 'Total
Price', importance: #MEDIUM } ],
'Total Price' } ] }
@UI : {lineItem: [ { position: 80, label: 'Discount
%', importance: #MEDIUM } ],
'Discount %' } ] }
DiscountPct :
abap.int1; //modifiable data
@UI : {lineItem: [ { position: 75, label: 'Discount
Absolute', importance: #MEDIUM } ],
'Discount Absolute' } ] }
DiscountAbs : abap.dec( 17,
3 ); //modifiable data
@UI : {lineItem: [ { position: 72, label: 'Total
Price with Discount', importance: #MEDIUM } ],
'Total Price with Discount' } ] }
TotalPriceWithDiscount : abap.dec( 17,
3 ); //calculated data
CurrencyCode : abap.cuky;
@UI : {lineItem: [ { position: 50, label: 'Comment',
'Comment' } ] }
Description :
abap.char( 1024 ); //renamed element
@UI : {lineItem: [ { position: 90, label: 'Status',
'Status' } ] }
@EndUserText.label : 'Last changed on'
LastChangedAt : timestampl;
}

3. Add static feature control for attributes to set them read-only or mandatory.
The only attributes that are modifiable are DiscountPct and DiscountAbs. They need to be filled with
values. Set all other attributes as mandatory. For further information, see Feature Control [page 128].
 Expand the following listing to view the source code of the behavior definition with the relevant feature
control additions.
unmanaged;

define behavior for /DMO/TRAVEL_C_C alias Travel_CE
etag LASTCHANGEDAT
{ update;
field (readonly) TRAVELID, AGENCYID, CUSTOMERID,
BEGINDATE, ENDDATE, DESCRIPTION,

764 PUBLIC Develop
BOOKINGFEE, TOTALPRICE, TOTALPRICEWITHDISCOUNT,
STATUS, CURRENCYCODE;
field (mandatory) DISCOUNTABS, DISCOUNTPCT;

}
Related Information
Creating an OData Service [page 323]

Designing the User Interface for a Fiori Elements App [page 332]
4.3 Develop Web APIs
An OData service can be published as a web API. This enables the consumption of the service by any client,
independent from a particular UI.
Introduction
A Web API is an OData service whose metadata does not entail any UI-specific annotations that are defined
for the data model. It is published for the purpose of providing an API to access the service by an unspecified
client. A Web API facilitates the exchange of business information between an application and any client,
including from a different system or server.
In this development guide you will reuse the service that you created in Developing Unmanaged Transactional
Apps [page 481] and publish a Web API for it. Since a Web API is not being used directly in a UI context, the
consumer of a service of this type only requires a reduced set of metadata. The metadata lacks any kind of
UI-relevant information.
The basis for the service remains identical to an OData service exposed for a UI. It is just the binding type in the
service binding that differs, which can be seen in the subsequent figure. It is even possible to expose a service
that was created originally as a UI service for API consumption. The metadata are automatically reduced to the
relevant information for Web API, which means without UI-related annotations or value helps.

Develop PUBLIC 765
 Cloud The procedure of consuming a remote Web API service like this from a foreign system is described in
the following development guide Cloud Developing a UI Service with Access to a Remote Service [page 714].
Prerequisites

 Restriction
• You have understood the development steps to create a transactional OData service for a UI as described
in Developing Unmanaged Transactional Apps [page 481].
In particular, you are able to reuse the data model including the behavior of the existing OData
service /DMO/TRAVEL_U to expose it for a Web API.
Via ABAPGit You can import the service /DMO/TRAVEL_U including the related development objects into
your development environment. So you do not have to build the service to test the publishing as Web API.
You find the service in the package /DMO/FLIGHT_UNMANAGED.

766 PUBLIC Develop
Example Scenario
As described above, the following guide reuses the data model and behavior of the service that was created in
the transactional guide. This means that the following artifacts must be available in your system to follow the
steps of this guide.
Artefact Description
CDS Entities
/DMO/I_TRAVEL_U The Travel entity defines general travel data, such as the
agency ID or customer ID, status of the travel booking, and
the price of travel. The entity represents the root node of the
business object
/DMO/I_Booking_U The Booking entity manages data for a booked flight for
a certain travel instance. It is a composition of the Travel
entity and is therefore dependent on its root.
/DMO/I_Agency The Agency defines general data about the responsible

agency for a travel. It is associated with the Travel entity.
/DMO/I_Customer The Customer defines personal data about the custom-

ers involved in travel and booking. It is associated with the
Travel entity and the Booking entity.
Behavior Artifacts
/DMO/I_TRAVEL_U The behavior definition defines the capabilities of the busi-

ness object involved.
/DMO/CL_TRAVEL_U The behavior is implemented in the special ABAP classes.
Business Service Artifact
/DMO/TRAVEL_U The service definition defines all the entities that are ex-
posed for the service.
4.3.1 Publishing a Web API
Prerequisites
You have an existing service definition for which you want to create a Web API service. In our example
scenario we reuse the service definition /DMO/TRAVEL_U, which was already exposed as a UI service in the
transactional scenario.
If no service definition is available, choose the entities that you want to expose as an API and create a service
definition for these entities. For a description on how to create a service definition, refer to Creating a Service
Definition for the Read-Only Service [page 324].

Develop PUBLIC 767
Context
You have defined the scope of the service that you want to expose in a service definition. The service must now
be bound to an OData protocol and published as a Web API.
Procedure
1. In your ABAP project, open the context menu for the existing service definition /DMO/TRAVEL_U and
choose New Service Binding to launch the creation wizard.
2. In addition to the Project and Package, enter the Name and the Description for the service binding you want
to create.
 Note
The maximum length for the name of a service binding is 26 characters.
3. Select the Binding Type ODATA V2 - Web API to bind the service to a V2 protocol and expose it as a Web
API.
4. Verify that the correct Service Definition is preset in the wizard to be used as a base for your service
binding.
5. Choose Next.
6. Assign a transport request and choose Finish.
The ABAP back end creates a service binding and stores it in the ABAP Repository.

768 PUBLIC Develop
In the Project Explorer, the new service binding is added to the Business Services folder of the
corresponding package node. As a result, the service binding form editor is opened and you can verify
the information of the service.
Service Binding Artifact Form Editor for a Web API

7. To expose the service, choose the button Activate.
The metadata document can be accessed by following the link Service URL. The UI preview is naturally not
available.
Results
Except for UI features, the service including all implemented features is now exposed as an API. In particular,
this means that the implemented behavior is also exposed in this API.
The difference to a service that is published for a UI client can best be seen in the service metadata. Whereas
the metadata of a UI service carries information about the UI representation of the service, the Web API service
does not contain any such information.
 Example
In our example scenario this difference can be seen when comparing the annotation section that refers to
the implemented value help.
The UI service lists every field of a value help provider view as ValueListParameter in the annotation
section. The Web API on the other hand lacks any UI specific information, although the value help
annotation is defined in the respective CDS views.

Develop PUBLIC 769
4.4 Develop APIs
Context
This chapter guides you through the necessary steps to develop an API for an existing business object. This
API decouples requirements for the stable consumption of your business object from its core data model and
behavior. In RAP, an API is implemented by means of a RAP BO interface.
For further information on RAP BO interfaces, see Business Object Interface [page 194].
Prerequisites
You can add a RAP BO interface to any existing business object. In this development guide, a RAP BO interface
is developed for the business object resulting from the draft reference scenario. So in order to follow the steps
described in this section, you should have completed the development guide Draft Reference Scenario [page
578] beforehand.
To add an interface to the business object, the following steps are relevant:
• Projecting the Draft BO Data Model [page 770]

• Projecting the Draft BO Behavior [page 773]
4.4.1 Projecting the Draft BO Data Model
For the managed scenario with draft, create and implement CDS projection views for the draft BO entities.
Create data definitions for projection views for all three BO entities Travel, Booking, and Booking Supplement.
In ADT, use the context menu on the underlying CDS view entities /DMO/R_Travel_D, /DMO/R_Booking_D
and /DMO/R_BookingSupplement_D to open the wizard for creating CDS data definitions. For a detailed
step-by-step description, see .
Documentation).
Projection View /DMO/I_Travel_D

770 PUBLIC Develop
Use the provider contract transactional_interface. This defines the projection view as part of the RAP
BO interface.
As the projection view will not be used for OData service consumption, no UI specific or semantic annotations
are required. The long texts for ID elements do not need to be denormalized either.
to-child composition to the projection view of the booking entity.
 Expand the following code sample to view the source code of Projection View /DMO/I_Travel_D.
 Sample Code
@EndUserText.label: 'Travel Interface Projection View'


define root view entity /DMO/I_Travel_D

provider contract transactional_interface


{
key TravelUUID,
TravelID,
AgencyID,
CustomerID,
BeginDate,
EndDate,
BookingFee,
TotalPrice,
CurrencyCode,
Description,
OverallStatus,
LocalLastChangedAt,
/* Associations */
_Agency,

_Booking: redirected to composition child /DMO/I_Booking_D,

_Currency,
_Customer,
_OverallStatus
}

Projection View /DMO/I_Booking_D
to-child composition to the projection view of the booking supplement entity and the association to the root
entity to the respective projection view.
 Expand the following code sample to view the source code of Projection View /DMO/I_Booking_D.

Develop PUBLIC 771
 Sample Code
@EndUserText.label: 'Booking Interface Projection View '


define view entity /DMO/I_Booking_D

as projection on /DMO/R_Booking_D {

key BookingUUID,
TravelUUID,
BookingID,
BookingDate,
CustomerID,
AirlineID,
ConnectionID,
FlightDate,
FlightPrice,
CurrencyCode,
BookingStatus,
LocalLastChangedAt,
/* Associations */
_BookingStatus,

I_BookingSupplement_D,

_Carrier,
_Connection,
_Customer,

_Travel: redirected to parent /DMO/I_Travel_D

}

Projection View /DMO/I_BookingSupplement_D
to-parent association to the projection view of the booking entity and the association to the root entity to the
I_BookingSupplement_D.
 Sample Code
@EndUserText.label: 'BookSupplement Interface Projection View'


define view entity /DMO/I_BookingSupplement_D

as projection on /DMO/R_BookingSupplement_D {

key BookSupplUUID,
TravelUUID,
BookingUUID,
SupplementID,
BookSupplPrice,
CurrencyCode,
LocalLastChangedAt,

772 PUBLIC Develop
/* Associations */

_Booking: redirected to parent /DMO/I_Booking_D,

_Product,
_SupplementText,

_Travel : redirected to /DMO/I_Travel_D

}

4.4.2 Projecting the Draft BO Behavior
For the managed scenario with draft, create an interface behavior definition to expose the behavior to be
provided via the API.
Create an interface behavior definition for the travel business object. In ADT, use the context menu of the
root interface projection view to open the wizard for creating behavior definitions. The implementation type is
prefilled with Projection. For a more detailed description, see .
Interface Behavior Definition /DMO/I_Travel_D
Use the complete behavior that was defined in the underlying behavior definition for the interface projection.
(The template does not include everything, some features must be added manually.)
I_Travel_D.
 Sample Code
interface;

use draft;

define behavior for /DMO/I_Travel_D alias Travel

use etag
{
use create;
use update;
use delete;
use action Edit;
use action Discard;
use action Prepare;
use action Resume;
use association _Booking { create; with draft; }
}

define behavior for /DMO/I_Booking_D alias Booking

use etag
{
use update;

Develop PUBLIC 773
use delete;
use association _BookingSupplement { create; with draft; }
}

define behavior for /DMO/I_BookingSupplement_D alias BookingSupplement

use etag
{
use update;
use delete;
use association _Booking { with draft; }

}
4.5 Develop UI-Specifics
This chapter explains how to optimize you data model for UI consumption using CDS annotations. The chapter
outlines the most important and most common UI layouting tasks to get you started.
• Adding Field Labels and Descriptions
End-user texts, such as field labels or field descriptions must be translated. Therefore, the CDS development
infrastructure is able to extract them from the source code and transfer the extracted texts to the actual
translation infrastructure of the corresponding delivery package.
• Providing Value Help
The implementation of a value help in CDS enables the end user to choose values from a predefined list for
input fields on a user interface.
• Develop UI-Specifics
How to solve the most common UI layout tasks with UI annotations in CDS.
4.5.1 Adding Field Labels and Descriptions
End-user texts, such as field labels or field descriptions, are taken from ABAP Dictionary data elements to
which the corresponding element is bound - unless you redefine the texts using CDS annotations. Unlike
technical element names, the header texts, field labels and descriptions are language-dependent. For
example, the field 'Airline'' would have a language-dependent label 'Airline Code'.
Such texts must be translated. Therefore, the CDS development infrastructure is able to extract them from
the source code and transfer the extracted texts to the actual translation infrastructure of the corresponding
delivery package.

774 PUBLIC Develop
Relevant Annotations
Annotation Effect
@EndUserText.label: This annotation is used to define translatable semantic short texts (with maxi-
'<text>' mum 60 characters) for an element of the CDS view (label text).
@EndUserText.quickInfo: The annotation defines a human-readable <text> that provides additional infor-
'<text>' mation about an element. The quick info is used for accessibility hints or the
mouse over function.
 Remember
The <text> specified in the source code should consist of text in the original language of the CDS source
code and will be translated into the required languages.
Example
The listing below demonstrates the usage of @EndUserText annotations at the view and element (field) level:

...
@EndUserText.label: 'Overview of available flights' -- Annotation at the view
level
DEFINE VIEW <CDS_view> as Flights {

...
-- Annotation at the field level

@EndUserText: { label: 'Airline Code',
quickinfo: 'Code to identify which airline operates the flight' }
carrier_id as CarrierID;
...

 Tip
Press F1 in the CDS source code editor for extended help content on @EndUserText annotation!
 Note
If @UI labeling annotations are used, they will be evaluated primarily. That means, they will overwrite the
text given with the @EndUserText annotations.
OData Metadata
To verify that the additional information of labels and descriptions is pushed correctly to the OData service, you
can check the OData metadata document. This can also be helpful to find out which label information is used if
you maintain @UI and @EndUserText in your CDS view.

Develop PUBLIC 775
If no UI annotations are used, the OData metadata document of the example above should contain the
annotations that are marked in the following image:
4.5.2 Providing Value Help
The implementation of a value help in CDS enables the end user to choose values from a predefined list for
input fields on a user interface.
Why and When to Use Value Help
You can define value helps in the CDS data layer for any input field on the UI (for example, selection fields,
parameters, or writable fields in transactional scenarios) . A value help is useful when the values for the input
field have to be taken from a predefined set of values. When you call the value help, it displays all the available
values from the value help provider. It appears on the UI when you choose the button in the input field
or press the F4 key. The end user can filter by related information to identify the correct value. This makes
it easier to find the desired value, especially if the value itself contains little or no identifying information, for
example, an ID number.
 Example
To help the end user to enter the right customer ID to create a new booking, the application developer
defines a value help that enables the user to enter the name or any other element from the value help
provider to help find the correct number. The value help provider view in this case is a CDS view that
manages customer information. As shown below, the end user is searching for a particular customer ID.
The value help offers to filter by the customer last name, so that the end user can choose from the available
entries. The value of the customer ID field is then transferred to the respective input field.
Expand the following figure to view the procedure of calling the value help on a Fiori Elements UI.

776 PUBLIC Develop
Value Help on a Fiori Elements UI
How are Value Helps Implemented?

Value helps are defined in CDS with an annotation on the element or parameter for which the value help dialog
is to appear on the UI. The annotation @Consumption.valueHelpDefinition allows you to reference the
value help provider without implementing an association. You simply assign a CDS entity as the value help
provider and provide an element for the mapping in the annotation. All fields of the value help provider are
displayed on the UI. When you choose one of the entries of the value help provider, the value of the referenced
element is transferred to the input field.
For the default implementation of the value help, you can use any CDS entity that contains the desired values
of the element for the input field. You do not need to explicitly define a CDS entity as the value help provider.
However, the value help provider must be exposed for the OData service to make use of the value help.
 Note
Any annotation that is maintained in the value help provider is evaluated. This means that associated
entities, value helps, and text associations of the value help provider view are also displayed and can be
used in the value help. This means that you can have a value help in the value help.
Simple Value Help [page 778]

A simple value help is convenient if you want to display values from the value help provider for an input
field.
Value Help with Additional Binding [page 783]

A preset filter condition can be established by an additional binding for the value help.

Develop PUBLIC 777
Related Information
Providing Value Help for the Selection Fields [page 365]

Consumption Annotations [page 1195]
4.5.2.1 Simple Value Help
A simple value help is convenient if you want to display values from the value help provider for an input field.
Context
You want to provide a value help for an input field on the UI.
The following steps implement a value help for a customer ID field, using a booking CDS view as an example.
Procedure
1. Create a data definition for a CDS view that serves as a value help provider. It must contain a field with the
available values for the input field in the source view.
 Example
The value help provider view contains the customer ID and fields to identify the customer ID, such as
the customer's name or address. The end user can then filter by these fields to find the right customer
ID.
define view entity /DMO/I_Customer_VH as select from /dmo/customer

{
key customer_id,
first_name,
last_name,
title,
street,
postal_code,
city,
country_code,
phone_number,
email_address

}
To retrieve the full value list when invoking the value help, annotate the value help view with the annotation
@Consumption.valueHelpDefault.fetchValues: #AUTOMATICALLY_WHEN_DISPLAYED. To
explicitly disable loading the full list, use @Consumption.valueHelpDefault.fetchValues:
#ON_EXPLICIT_REQUEST.

778 PUBLIC Develop
2. In your CDS source view, add the following annotation to the element for which you want to provide the
value help on the UI.
@Consumption.valueHelpDefinition: [{ entity: { name: 'entityRef' ,

element:
'elementRef' } }]
The annotation defines the binding for the value help to the value help providing entity. You must specify
the entity name and the element providing the possible values for the annotated element.
 Example
The following code example shows how an annotation is used on the element CustomerID in /DMO/
I_Booking. It references the value help provider view (/DMO/I_CUSTOMER_VH) for the customer ID
and the element providing the possible values (customer_id) in the value help provider view.
define view /DMO/I_Booking as select from /dmo/booking

{…
@Consumption.valueHelpDefinition: [{entity: { name: '/DMO/
I_CUSTOMER_VH',
element:
'customer_id' }}]

… }
Results
If you expose the source view in an OData service, the value help provider view is automatically exposed with it.
You do not have to list value help provider views in the service definition.
On a Fiori UI, choosing F4 in the selection field opens a search mask and the end user can filter by any field
in the value help provider view. Selecting an entry transfers the value of the element that is referenced in the
annotation to the annotated element in the source view.
The metadata of the OData service displays the value help implementation for the following properties:
• The property in the CDS source view for which a value help is implemented (sap:value-
list="standard")
• The value help provider entity type (sap:value-list="true")
• The value help provider entity is marked as Target in the Annotations property. The value list
enumerates every property in the value help provider that is exposed for the value help (Annotation
Term="Common.ValueList").
• The element that is defined in the mapping condition is marked as an inbound and outbound parameter
Record Type="Common.ValueListParameterInOut".
 Expand to view the extracts of the metadata document of a service exposing a booking CDS view and the
value help provider for the element CustomerID.

Develop PUBLIC 779
This value help provider is also search supported.
Metadata Document
 Restriction
If you associate the value help provider to your source view, the metadata of the value help provider view do
not have sap:value-list="true". As a result, the request <service_url>/$metadata?sap-value-
list=<service_namespace>.<entity>Type/<element> (where <element> is the element that is
referenced in the annotation @Consumption.ValueHelpDefinition in your CDS view) does not work.
This can lead to problems when invoking value helps.
To avoid this clash, separate your value help information in value help provider views that do not coincide
with other associated views, for example text provider views.

780 PUBLIC Develop
Other Value Help Options
Other Capabilities for the Value Help Provider
Any annotation that is maintained in the value help provider is evaluated. This means that the following
capabilities are possible for the value help:
• Associations: If the target of the association is included in the OData service, the elements of entities
associated with the value help provider are also displayed as additional input fields.
• Search Capabilities: Including search capabilities in your value help provider enables the end user to
search for any detail in an input field.
• Value Helps: The value help can itself contain value helps.
• Text: Text that is provided for the value help provider is also displayed.
Value Help as Dropdown List
If you want to show the possible values for the input field as a dropdown list only, instead of a search mask
with all other elements of the value help provider, annotate the value help provider with @ObjectModel :
{ resultSet.sizeCategory: #XS } on the view level.
For dropdown value lists, the OData $metadata document includes the annotation sap:value-list=
"fixed-values" instead of standard on the property in the source view for which the value help is
implemented.
The UI displays the possible values for the input field in a dropdown list. The following image shows a value help
list for the carrier ID field in the booking scenario.
Drop Down Value Help
Value Help Typeahead in the Selection Field
The entries of the value help provider view can be displayed while typing in the selection field. From the list that
opens you can choose an entry to fill the selection field with the desired value:

Develop PUBLIC 781
The UI displays the possible values for the input field while typing values from the value help provider:
Value Help Typeahead
To enable the typeahead functionality enable the value help provider entity with search capabilities. This is
done by using the annotation @Search.searchable: true at value help level. The value help typeahead only
finds values from the value help provider that are annotated with @Search.defaultSearchElement: true.
 Example
If you want to display customer information of customers with first names, last names and cities
starting with V, the corresponding elements in the value help provider entity must be annotated with
@Search.defaultSearchElement: true.
To limit the value help list to certain elements, annotate the elements that you want to display with
@UI.lineItem.importance: #HIGH. Then, the other elements with lower importance are not taken into
consideration for the value help list.
 Home Value Help Via Association

If the value help provider is already associated with the source entity, you can use the association
@Consumption.valueHelpDefinition.association: 'Assoc' and reference the association instead
of the entity. The binding condition is then already given in the on-condition of the association.
 Example
The following code example shows how the annotation is used on the element CustomerID in /DMO/
I_Booking. It references the association to the value help provider view (_Customer).
define view /DMO/I_Booking as select from /dmo/booking

association [0..1] to /DMO/I_Customer_VH as _Customer on
$projection.CustomerID = _Customer.customer_id
{…
@Consumption.valueHelpDefinition.association: '_Customer'
…

782 PUBLIC Develop
_Customer

}
 Note
When using the option of consuming value helps via an association, it is not ensured that the value help
works properly, see Restriction [page 780].
4.5.2.2 Value Help with Additional Binding
A preset filter condition can be established by an additional binding for the value help.
Context
You use an additional binding to define more than one binding condition between the source view and the value
help provider. The value help is then automatically filtered by the additional binding. It proposes only entries
that match the additional binding. This additional binding can either be another element or a parameter. These
need to be present in the source view and in the value help provider view. When an entry is selected in the value
help provider, the values of both binding elements are transferred to the input fields of the source CDS view.
 Example
In our booking scenario, we can apply the value help with an additional binding on the field ConnectionID.
The value help provider is a view that manages connections. This value help provider contains not only
the field for the connection IDs, but also a field for carrier IDs, which is also in the consumer view. We can
establish a second binding condition so that the value help provider only displays connections with the
prechosen carrier ID.
Value Help with Additional Binding on Booking Scenario

Develop PUBLIC 783
Procedure
1. Create a data definition for a CDS view that serves as a value help provider. It must contain a field with
the available values for the input field in the source view. In addition, it must contain the field for which the
additional binding is established.
The value help provider view contains the connection ID and the carrier ID, for which a mapping condition
is defined.
define view /DMO/I_Connection_VH as select from /dmo/connection

{
key carrier_id,
key connection_id,
airport_from_id,
airport_to_id,
departure_time,
arrival_time,
distance,
distance_unit
}

2. In your CDS source view, add the following annotation to the element for which you want to provide the
value help on the UI.
@Consumption.valueHelpDefinition: [{ entity: {name: 'entityRef', element:

'elementRef'} ,

additionalBinding: [{ element: 'elementRef' | parameter:
'paramRef', localElement: 'elementRef' | localParameter: 'paramRef', usage:
#FILTER | #RESULT | #FILTER_AND_RESULT }] }]

The additional binding defines a second condition for the value help on the same target value help provider
entity for filtering the value help result list and/or returning values from the selected value help record. The
additional binding can be defined for an additional element or parameter. Depending on the value provided
in usage, the additional binding works as a filter, result or filter and result condition:
• #Filter: The value of the referenced element or parameter in localElement or localParameter is
used as a filter for the value help. The value help only displays filtered results.
 Note
For numerical data types of local elements, the value help is always filtered for 0 (initial value) if the
local elements are empty.
• #Result: The referenced element or parameter in localElement or localParameter is filled with

the value provided by the value help. When creating an instances, you can fill various fields with this
option.
• #Filter_and_Result: The value help works in both directions. It filters the value help and takes
over the values for the corresponding fields.
#Filter_and_Result is the default if no usage type is specified.
The following code example shows the usage of the annotation on the element ConnectionID in /DMO/
I_Booking. It references the value help provider view (/DMO/I_Connection_VH) and the element
providing the possible values (connection_id) in the value help provider view, as well as the matching

784 PUBLIC Develop
condition on the elements CarrierID and carrier_id in the consumer view and the value help provider
view, respectively.
define view /DMO/I_Booking_VH as select from /dmo/booking

{…
@Consumption.valueHelpDefinition: [{ entity: {name: '/DMO/
I_Connection_VH' , element: 'connection_id' },
additionalBinding: [{ localElement: 'CarrierID', element:
'carrier_id', usage: #Filter }]
}]

… }
Results
Choosing F4 in the selection field opens a search mask and the end user can display all available entries in the
value help provider or filter by a field, for example, the destination airport. If the carrier ID is already filled in the
consumer view, the value help provider is prefiltered by that value. Selecting an entry in the value help transfers
the connection ID as well the carrier ID to the CDS consumer view.
The metadata of the OData service displays the value help implementation on the following properties:
• The property in the CDS source view for which a value help is implemented (sap:value-
list="standard")
• The value help provider entity type (sap:value-list="true")
• The value help provider entity is marked as Target in the Annotations property. The value list
enumerates every property in the value help provider that is exposed for the value help (Annotation
Term="Common.ValueList").
• The elements that are defined in the mapping conditions are marked as inbound and outbound parameters
Record Type="Common.ValueListParameterInOut".
 Restriction
If you associate the value help provider to your source view, the metadata of the value help provider view do
not have sap:value-list="true". As a result, the request <service_url>/$metadata?sap-value-
list=<service_namespace>.<entity>Type/<element> (where <element> is the element that is
referenced in the annotation @Consumption.ValueHelpDefinition in your CDS view) does not work.
This can lead to problems when invoking value helps.
To avoid this clash, separate your value help information in value help provider views that do not coincide
with other associated views, for example text provider views.

Develop PUBLIC 785
4.5.3 Defining CDS Annotations for Metadata-Driven UIs
How to solve the most common UI layout tasks with UI annotations in CDS.
Prerequisites
In order to use this help chapter, you should be familiar with:
• CDS Views and CDS DDL (Data Definition Language)

• Setting up Data Definitions, Service Bindings and Service Definitions
• Using ABAP Development Tools (ADT)
In order to use the example code, download the ABAP Flight Reference Scenario [page 309].
Context
For a UI to work, you do not need to implement everything yourself. The barebones of the UI will be taken
care of automatically by RAP if you use the Fiori Elements App Preview (FEAP) in the service binding. For
example the root page will have a header and a list report (table) facet with sorting and filtering capabilities,
even without you implementing any UI annotations in CDS. Furthermore the UI will include a Share-Button and
a basic view manager.
 Note
To view the entries of your database on the UI without implementing any UI annotations, click on the gear
icon on the UI and select at least one column.
FAQ
This FAQ directs you to the correct topics for questions that often arise when working with Metadata-Driven UIs
for the first time.
• What are fields? [page 789]

• How can I overwrite default labels of fields? [page 790]
• How can I define the positioning of fields? [page 793]
• How can I filter my data by specific fields? [page 800]
• How can I manipulate the Object Page Layout? [page 806]
• How can I hide fields on the Object Page? [page 812]
• How can I visualize my data? [page 815]

786 PUBLIC Develop
Source Code Structure
You can use UI annotations both in Data Definition or Metadata Extension files.
 Note
We recommend that you use a Metadata Extension file for all UI annotations because this will improve the
legibility of the source code in the Data Definition and also simplify the development and maintenance of
the CDS view. Metadata Extensions also allow for layering of multiple Metadata Extensions, which is useful
if your BO is used by customers, partners and industries at the same time with different customization
needs.
Your code will have the following sections:
1. Header section
2. Annotate/define view section
3. Facet Definitions
4. Element List
1. Fields
2. Associations
See the code snippet below for a complete overview of all sections and the correct syntax.
Find the Metadata Extension files for the Travel Scenario in the Complete UI Annotations Example Code [page
821].
 Sample Code
// HEADER SECTION

@Metadata.layer: ...
@UI.headerInfo: ...
// ANNOTATE VIEW SECTION
annotate/define view ...
{
// FACET DEFINITIONS
// Header Facets (Object Page):
@UI.facet: [ { purpose: #HEADER, ... },
// Body Facets (Object Page)
{ ... } ]
// ELEMENT LIST
// FIELDS
@UI: { lineItem: [ { ... } ],

identification: [ { ... } ],
selectionField: [ { ... } ],
fieldGroup: [ { ... } ] }
element_1;
@UI: { lineItem: [ { ... } ],
identification: [ { ... } ],
selectionField: [ { ... } ],
fieldGroup: [ { ... } ] }
element_2;
...
// ASSOCIATIONS
_Association1

}

Develop PUBLIC 787
User Interface
The screenshots in this guide are taken from the Fiori Elements App Preview (FEAP), which can be started from
The Fiori UI serves as an example for how your UI might look like and how changes in the code influence the UI.
In this guide, we use the two most common page layouts, also called Fiori floorplans, namely:
1. List Reports and

2. Object Pages.
Find more information about Fiori in the Introduction to SAP Fiori Elements .
List Report Page
The list report is used to display all the entries of a dataset in one list or table. You can specify which columns to
display and which ones to hide or omit.
A – List Report Header

B – List Report Table Header
C – List Report Columns
D – List Report Entries
To navigate from the list report to the object page of an entry, click anywhere on the row of that entry.
Object Page
The object page is mostly used to show more details about one entry of the dataset. Again, you can choose
which details shall be displayed on the object page.

788 PUBLIC Develop
A – Object Page Title Section
B – Header Facet
C – Facet Navigation Tab and Chart Facet
4.5.3.1 Fields on the UI
Use UI annotations to rearrange, label and manipulate fields on your UI.
Fields are elements from the CDS view that are displayed on the UI screen. Fields can be table columns of list
reports or single items within facets on the object page, such as “Customer ID: …”. In other words: whenever
you annotate a CDS element to be displayed on the UI, it will appear on the UI as a field.
In this chapter, you will be guided through the following tasks:

Develop PUBLIC 789
• Overwriting Default Field Labels [page 790]
• Positioning Fields [page 793]
• Grouping Fields [page 795]
• Hiding Fields on the Object Page [page 812]
• Adding Selection Fields [page 800]
4.5.3.1.1 Overwriting Default Field Labels
How to use UI annotations in CDS to overwrite default field labels on your UI.
Quick Info
@UI.identification: [{label: '<new label

Annotation Syntax name>'}]
Description Defines the displayed field label.

Overrules default labels of identification derived from
CDS annotation @EndUserText.label or from data
elements in the ABAP dictionary.
Use To be placed in the element list section, preceding each

respective element.
Related Topics Fields on the UI [page 789]

@UI.lineItem: [{label: '<new label

Annotation Syntax name>'}]
Description Defines the displayed field label.

Overrules default labels of columns of a list report derived
from CDS annotation @EndUserText.label or from
data elements in the ABAP dictionary.
Use To be placed in the element list section, preceding each

respective element.


790 PUBLIC Develop
Preview on Fiori UI
Labeled UI Identification Fields on the Object Page
Labeled UI Line Item Fields on the List Report
Context and Use
The labels of exposed CDS elements are derived by default from the data element labels in the ABAP
dictionary, or, if defined, from the CDS annotation @EndUserText.label. You can overwrite both, data
element labels and labels defined by @EndUserText.label, with the subannotation label on the UI.
Labels of UI annotations are only used in UI contexts, whereas labels from the ABAP dictionary or
@EndUserText.label are used in the service document of any service. The subannotation label can be
used with several UI annotations, e.g. @UI.identification or @UI.LineItem (see Quick Info above or UI
Annotations [page 1260]).
Place the annotation within the element list section, right before the respective element that you want to label.
Code Snippet
In this example, we use the annotation @UI.identification.label to label the fields that are displayed
on the object page in the facet with type #IDENTIFICATION_REFERENCE as can be seen in the first figure
of the preview above. Similarly we label the fields (i.e. columns) of the list report with the annotation
@UI.lineItem.label as can be seen in the second figure of the preview above.
821].
 Expand the following code sample to view the source code to annotate view Z_C_TRAVEL_R.
 Sample Code
...

Develop PUBLIC 791

annotate view Z_C_TRAVEL_R with
{
...
...
// Facet 3
{ id: 'Facet3-ID',
purpose: #STANDARD,
type: #IDENTIFICATION_REFERENCE, // Refers to
elements annotated with '@UI.identification' in the element list below
label: 'Facet 3 - Overview and Comments',
position: 30 }
]
// ELEMENT LIST
// No label defined.
TravelID;
@UI: { lineItem: [ { label: 'Agency' } ],
identification: [ { label: 'Agency' } ]
}
AgencyID;
@UI: { lineItem: [ { label: 'Customer' } ],
identification: [ { label: 'Customer' } ]
}
CustomerID;
@UI: { lineItem: [ { label: 'Start of Travel' } ],
identification: [ { label: 'Start of Travel' } ]
}
BeginDate;
@UI: { lineItem: [ { label: 'End of Travel' } ],
identification: [ { label: 'End of Travel' } ]
}
EndDate;
@UI: { hidden: true }
BookingFee;
// No label defined.
TotalPrice;
// Label only defined for identification field
@UI: { identification: [ { label: 'Comment' } ]
Memo;
// Label only defined for line item field
@UI: { lineItem: [ { label: 'Set to Booked' } ]
Status;

}

792 PUBLIC Develop
4.5.3.1.2 Positioning Fields
How to rearrange fields using UI annotations in CDS.
Quick Info
@UI.identification: [{position:
Annotation Syntax <value>}]
Description Sorts fields in the order of position values.
Use To be placed in the element list section of the code,

preceding each respective element.
Annotation Syntax @UI.lineItem: [ { position: <value> } ]
Description Sorts fields (i.e. table columns) in the order of

'position' values.
preceding each respective element.
Preview on Fiori UI
UI Identification Fields sorted in order of the position values on the Object Page

Develop PUBLIC 793
UI Line Item Fields sorted in order of the position values on the List Report
Context and Use
Place the annotation in the element list section of your CDS Data Definition or Metadata Extension, directly
preceding the respective element. The value for position is relative, meaning that the order of the elements
on the UI is defined by the relative order of the values for position of each element.
We recommend that you leave gaps between the respective values for position. This will make it easier to add
an element between two other elements retroactively, as you will not need to change the values of position
for all other elements.
The subannotation position can be used in a similar way with the following annotations:
UI.facet
UI.fieldGroup
UI.identification
UI.lineItem
UI.selectionField
UI.statusInfo
You can find more details about this in UI Annotations [page 1260].
Code Snippet
In this example we use @UI.identification.position to define the order of the identification fields in the
facet with type #IDENTIFICATION_REFERENCE on the object page. Similarly we define the order of the fields
(i.e. columns) of the list report with the annotation @UI.lineItem.position.
You can find the Metadata Extension files for the Travel Scenario in the Complete UI Annotations Example Code
[page 821].
 Expand the following code sample to view the source codefor the annotations of the view Z_C_TRAVEL_R.
...

{
...
...
// Facet 3
{ id: 'Facet3-ID',
purpose: #STANDARD,
type: #IDENTIFICATION_REFERENCE, // Refers to elements
annotated with '@UI.identification' in the element list below

794 PUBLIC Develop
position: 30 }
]
// ELEMENT LIST
@UI: { lineItem: [ { position: 10 } ],

identification: [ { position: 10 } ]
}
TravelID;
}
AgencyID;
}
CustomerID;
}
BeginDate;
}
EndDate;
@UI: { hidden: true,
BookingFee;
TotalPrice;
@UI: { identification: [ { position: 70,
label: 'Comment' } ]
}
Memo;
label: 'Set to Booked' } ]
Status;

}
4.5.3.1.3 Grouping Fields
How to use fieldgroups to structure the content on your UI using UI annotations in CDS.
Quick Info
@UI.fieldGroup: [ { qualifier: '<group

Annotation Syntax name>', position: <value>} ]
Description Arranges fields in groups within other sections, like headers

or facets.
Use To be placed in the element section of the code, preceding

the respective element.

Develop PUBLIC 795
@UI.fieldGroup: [ { qualifier: '<group
Annotation Syntax name>', position: <value>} ]
Use qualifier to assign a field to the

targetQualifier of a facet. Use position to define
the order of the fields.
Related Topics Using Facets to change the Object Page Layout [page 806]
Fields on the UI [page 789]

Preview on Fiori UI
Two Fieldgroups, Collected in One Facet
Context and Use
You can arrange fields to be displayed as a group within a facet.
1. Create a facet type #FIELDGROUP_REFERENCE in the element section.

2. Define a 'targetQualifier' for that facet. 'targetQualifier' is used as a reference to this facet
when defining elements.
3. Place the UI.fieldGroup annotation in the element section, directly preceding each element you want to
include in the group.
4. Use 'qualifier' to assign the element to the 'targetQualifier' of the facet you created before.
Facets can also collect fieldgroup items from other data definitions. In the example below, 'Fieldgroup1-ID'
assigns items from _Customer to the parent Facet1-ID in the travel CDS view. The items are described in the
Metadata Extension for _Customer. 'Fieldgroup2-ID' assigns items from the travel CDS view to the same
parent Facet1-ID.
You will find more details in the UI Reference.

796 PUBLIC Develop
Code Snippet
821].
1. Metadata Extension for TRAVEL (Data Definition for list report table)
 Sample Code

{
...
@UI.facet: [
...
// Facet 1 - Parent (collection) for Fieldgroup 1 and Fieldgroup 2
{ id: 'Facet1-ID',
type: #COLLECTION,
label: 'Facet 1 - Customer & Travel Data',
position: 10 },
// Facet for Fieldgroup 1 - nested inside Facet 1
{ id: 'Fieldgroup1-ID',
type: #FIELDGROUP_REFERENCE,
label: 'Fieldgroup 1 - Customer Data',
parentId: 'Facet1-ID', // Places this facet into
'Facet 1'
targetElement: '_Customer', // Specifies where the data is
retrieved from - UI annotations must be defined in the respective target
targetQualifier: 'Fieldgroup1',
position: 10 },
label: 'Fieldgroup 2 - Travel Data',
parentId: 'Facet1-ID', // Places this facet into
'Facet 1'
targetQualifier: 'Fieldgroup2', // No targetElement defined.
Default target is the entity in which the facet is defined.
position: 20 }
]
// ELEMENT LIST
// FIELDS
fieldGroup: [ { qualifier: 'Fieldgroup2',
position: 10 } ] }
CustomerID;
qualifier: 'Facet2' } ],
identification: [ { position: 40 } ] ,
position: 10 } ] }
BeginDate;
importance: #MEDIUM,
position: 10 } ] }
EndDate;
@UI: { identification: [ { position: 42 } ] ,

Develop PUBLIC 797
position: 10 } ] }
BookingFee;
position: 10 } ],
dataPoint: { title: 'Total Price',
targetValueElement: 'TotalPrice' } }
TotalPrice;
label: 'Comment' } ] ,
position: 10 } ] }
Memo;
position: 10 } ] }
Status;
}

2. Metadata Extension for _Customer
 Sample Code
...

annotate view Z_C_CUSTOMER_R with
{
@UI.fieldGroup: [{qualifier: 'Fieldgroup1', position: 05}]
Street;

CustomerID;

FirstName;

LastName;

Title;

PostalCode;

City;

CountryCode;

PhoneNumber;

EMailAddress;
/* Associations */
//Z_UI_CUSTOMER
_Country;

798 PUBLIC Develop
}

4.5.3.1.4 Prioritizing Fields
How to prioritize fields on the UI
Quick Info
@UI.lineItem: { importance: [#LOW,

Annotation Syntax #MEDIUM, #HIGH] }
Description Expresses importance of a field (i.e. table column). The

value of importance is used to determine which fields are
dynamically hidden if the UI is displayed on a small screen.

@UI.identification: { importance: [#LOW,

Annotation Syntax #MEDIUM, #HIGH] }
Description Expresses importance of an identification field. The value

of importance is used to determine which fields are
dynamically hidden if the UI is displayed on a small screen.

Context and Use
To make sure that the most relevant info is displayed even on small screens, you can define the priority of
fields on the UI. The assigned priority is recognized by Fiori Elements and used to decide which fields will be
dynamically hidden in case the UI is displayed on a smaller screen, e.g. a smartphone.

Develop PUBLIC 799
Code Snippet
In this example we use the annotation @UI.lineItem.importance to make sure that the TravelID,
AgencyID and CustomerID columns on the list report have high priority.
You can find the Metadata Extension files for the Travel Scenario in the Complete UI Annotations Example Code
[page 821].
...

{
...
@UI: { lineItem: [ { importance: #HIGH } ]
TravelID;
AgencyID;
CustomerID;
...

}
4.5.3.1.5 Adding Selection Fields
How to add selection fields for filtering lists or tables on your UI using UI annotations in CDS.
Quick Info
@UI.selectionField: [ { position:
Annotation Syntax <value> } ]
Description Adds selection fields for the corresponding columns in the

list report.
Useful for filtering long lists or tables for specific values.
Not to be confused with search fields (see: Adding Search

Capabilities [page 368]).

preceding the respective element.
Related Topics Adding Search Capabilities [page 368]

Fields on the UI [page 789]

800 PUBLIC Develop
Preview on Fiori UI
Selection Field with Applied Filter “Customer ID = 594”
Context and Use
The annotation displays selection fields for the corresponding colums of the list report. The subannotation
@UI.selectionField.position defines the order of the selection fields on the UI. Labels of selection fields
are derived from the data elements in the ABAP Dictionary. If you want to use different labels one the UI, define
labels with the @EndUserText.label annotation. Selection fields enable the user to filter a long list or table
for specific values, such as Customer ID and/or Agency ID (see example).
Place the annotation in the element list section of your CDS Data Definition or Metadata Extension, preceding
each respective element that you want to filter your table for.
You will find more details in the UI Annotations [page 1260].
Code Snippet
821].
annotate view Z_C_TRAVEL_R

{
…
// FIELDS
TravelID;
AgencyID;
CustomerID;
…

Develop PUBLIC 801

}
4.5.3.2 Tables
How to use UI annotations in CDS to design the layout of lists and tables on the UI.
The following topics apply to tables both on the list report and on the object page. Note that list reports always
use tables, while object pages may integrate tables.
Find more information about Fiori UI floorplans on Introduction to SAP Fiori Elements .
You will be guided through the following tasks:
• Defining the Table Header of a List Report [page 802]

• Labeling Table Columns [page 790]
• Positioning Table Columns [page 793]
 Note
The table header of a table can only be defined on a list report. Tables on object pages do not have a table
header.
4.5.3.2.1 Defining the Table Header of a List Report
How to define the table header of a list report of your UI using UI annotations in CDS.
Quick Info
@UI.headerInfo: { typeNamePlural: '<List

Annotation Syntax Report - Table Header>' }
Description Defines the table header of a list report.
Use To be placed in the header section of the code.
Related Topics Defining the Title Section of an Object Page [page 804]

802 PUBLIC Develop
Preview on Fiori UI
Defined Table Header of the List Report Page
Context and Use
Place the annotation UI.headerInfo.typeNamePlural in the header section of your CDS Data Definition or
Metadata Extension.
Code Snippet
821].
// METADATA EXTENSION - HEADER SECTION

@UI: { headerInfo: { typeNamePlural: 'List Report - Table Header' } }

...
4.5.3.3 Object Page
Use UI annotations to influence the design of the object page on your UI.
The object page is mostly used to show details about one entry of a data table. On an object page you can
gather information for one entry from different CDS views in different layouts. Click on a row of the list report
page to navigate to the object page of the corresponding entry.
Find more information about the object page in Defining CDS Annotations for Metadata-Driven UIs [page 786]
or in the Introduction to SAP Fiori Elements .
You will be guided through the following tasks:
• Defining the Title Section of an Object Page [page 804]

Develop PUBLIC 803
• Using Facets to change the Object Page Layout [page 806]
• Hiding Fields on the Object Page [page 812]
• Visualizing Data with Charts [page 815]
• Labeling Fields on the Object Page [page 790]
• Positioning Fields on the Object Page [page 793]
4.5.3.3.1 Defining the Title Section of an Object Page
How to use UI annotations in CDS to define the title of the object page of your UI.
Quick Info
@UI.headerInfo: { typeName: '<Object

Page Title>', title: { value:
Annotation Syntax '<field>' }
Description Defines the title section of an object page.
Use To be placed in the header section of the code.
Related Topics Defining the Table Header of a List Report [page 802]

804 PUBLIC Develop
Preview on Fiori UI
Title Section of the Object page comprising of a title and a value
Context and Use
Place the annotations @UI.headerInfo.typeName to define the Object Page title and
@UI.headerInfo.title.value to define the Object Page title value in the header section of your CDS Data
Definition or Metadata Extension.
 Note
You can display another value in the title section with the annotation
@UI.headerInfo.description.value.
Code Snippet
821].
// METADATA EXTENSION - HEADER SECTION

@UI: { headerInfo: { typeName: 'Object Page - Title' },
title: { value: 'TravelID' }

Develop PUBLIC 805
}
}

...
4.5.3.3.2 Using Facets to change the Object Page Layout
How to manipulate the basic layout of your UI using facets in CDS.
Quick Info
@UI.facet: [ { id: '…', label:

'…', parentId: '…', position:
<value>, purpose: #…, qualifier: '…',
targetElement: '…', targetQualifier:
Annotation Syntax '…', type: #…, hidden: true } ]
Description Defines facets for the object page.
Use To be placed in the facet definition section of the code.
Related Topics Defining CDS Annotations for Metadata-Driven UIs [page

786]
Complete UI Annotations Example Code [page 821]

806 PUBLIC Develop
Preview on Fiori UI

Develop PUBLIC 807
1 - Header Facet (purpose: #HEADER)
2 - Facet Navigation Tabs
3 - Chart facet (type: #CHART_REFERENCE)
4 - Parent Facet (type: #COLLECTION), Containing Two Child Facets, namely Fieldgroup 1 and Fieldgroup 2
(type: #FIELDGROUP_REFERENCE)
5 - Facet with Table (type: #LINEITEM_REFERENCE)
6 - Facet with Array (type: #IDENTIFICATION_REFERENCE)
Context and Use
Facets are useful for organizing the basic layout of a page, on the object page for example. @UI.facet can be
refined with a variety of subannotations. Place the annotation in the facet section of your CDS Data Definition
or Metadata Extension.
Purpose and Type of UI Facets
The annotation @UI.facet.purpose defnes whether the facet is a header or a standard facet. On the other
hand, the annotation @UI.facet.type defines the format of a facet and the types of fields that will be
displayed in a facet.
purpose: #HEADER Displays the facet and its content in the header section of
the object page.
purpose: #STANDARD Use this for standard facets. Can be omitted in most cases.
type: #COLLECTION The facet serves as parent (or container) for other facets.
Child facets reference the parent facet by 'parentId'.
type: #FIELDGROUP_REFERENCE Reference to elements assigned to a fieldgroup.
type: #IDENTIFICATION_REFERENCE Reference to elements annotated with

UI.identification. The facet will display the refer-
enced elements in a list format.
type: #LINEITEM_REFERENCE Reference to elements annotated with UI.lineItem. The

facet will display the referenced elements in a table format.
type: #CHART_REFERENCE Reference to charts annotated with UI.chart annotation.

The facet will display the referenced charts. For more infor-
mation, see Visualizing Data with Charts [page 815]
hidden: true Used to hide facets from a page view. The fields are not
displayed but still available for calculations for example.

808 PUBLIC Develop
Connecting Parent and Child Facets
Parent facets are annotated with type: #COLLECTION. To nest another facet into a parent facet, you must use
the annotations below.
id: '...' Unique identifier. Needed when child facets are nested into
#COLLECTION facets. The value of id is referenced by
parentID.
parentID: '...' Needed for child facets to be nested into #COLLECTION

facets.
Connecting Facets to Fieldgroups and Other Targets
To retrieve data from a source, you must define the targetElement in the facet. If there is no
targetElement defined, the default target is the entity in which the facet is defined. To nest field into a
fieldgroup, you must define the targetQualifier of the facet. The value of targetQualifier is referenced
by fields with the annotation @UI.fielgroup.qualifier.
targetElement: '…' Needed for retrieving data from associated Data Definitions,
e.g. _Customer
targetQualifier: '…' Unique identifier. Needed for elements to be nested into a

fieldgroup.
Facet Header and Position
To further customize the layout, you can define the label and position of each facet. By default, the position
of facets will be the order in which they are defined in the source code.
label: '…' Label displayed in the facet header and navigation tabs.
position: <value> Sorts facets in the order of the 'position' values. For
more information, see Positioning Fields [page 793].
For more details, see UI Annotations [page 1260].
Code Snippet
821].
 Expand the following code sample to view the source code to annotate the view Z_UI_TRAVEL.

Develop PUBLIC 809
 Sample Code
...

annotate view Z_UI_TRAVEL with
{
//FACET SECTION
@UI.facet: [
// Header Facet (Object Page):
{ id: 'HeaderFacet',
purpose: #HEADER,
label: 'Object Page - Header Facet',
targetQualifier: 'Fieldgroup:HeaderItems', // Refers to
lineItems with @UI.fieldGroup: [{qualifier: 'Fieldgroup:HeaderItems'}]
position: 10 },
// Facet for chart - charts can only be displayed in facets
{ id: 'Chart1-ID', // Facet for our Chart with type

"#CHART_REFERENCE"
purpose: #STANDARD,
type: #CHART_REFERENCE,
label: 'Chart facet',
targetQualifier: 'Chart1',
targetElement: '_Booking', // Specifies where the data is
retrieved from
position: 1
},
{ id: 'Facet1-ID',
type: #COLLECTION,
position: 10 },

parentId: 'Facet1-ID', // Places this facet into 'Facet
1'
position: 10 },

1'
targetQualifier: 'Fieldgroup2', // No targetElement defined.
Default target is the entity in which the facet is defined.
position: 20 },
// Facet 2
{ id: 'Facet2-ID',
type: #LINEITEM_REFERENCE, // Facet shows the
referenced items in a list report
label: 'Facet 2 - Bookings',
targetQualifier: 'Facet2',
position: 20,

810 PUBLIC Develop
targetElement: '_Booking'},
// Facet 3
{ id: 'Facet3-ID',
purpose: #STANDARD,
label: 'Facet 3 - Administration Data',
position: 30 }
]
// ELEMENT LIST
@UI: { identification: [ { position: 10 } ],

fieldGroup: [ { qualifier: 'Fieldgroup:HeaderItems',
position: 10 } ] }
TravelID;
@UI: { identification: [ { position: 20} ],
position: 20 } ] }
AgencyID;
@UI: { identification: [ { position: 30 } ],
position: 10 } ] }
CustomerID;
position: 10 } ] }
BeginDate;
importance: #MEDIUM,
position: 10 } ] }
EndDate;
position: 10 } ] }
BookingFee;
position: 10 } ] }
TotalPrice;
position: 10 } ] }
Memo;
@UI: { fieldGroup: [ { qualifier: 'Fieldgroup2',
position: 10 } ] }
Status;

}

Develop PUBLIC 811
4.5.3.3.3 Hiding Fields on the Object Page
How to use UI annotations in CDS to hide fields from the UI without deleting them.
Quick Info
Annotation Syntax @UI.hidden: true
Description Hides fields from the object page without deleting them.

Context and Use
In general, all fields that are exposed by the OData service are available to the client, regardless of whether the
fields are exposed explicitly using UI annotations. To enable end-user personalization, the client may offer the
possibility to add fields that are hidden for UI consumption, for example in facets on the object page. Use the
annotation @UI.hidden to prevent fields from being displayed on the UI and in the personalization dialog, but
leaving the field available for a WebAPI client.
You can also use this annotation if, for example, a CDS view contains technical keys, for example GUIDs, that
must be exposed to the OData service to work. These keys are usually not supposed to be displayed on the UI.
@UI.hidden: true is also useful if fields are required in calculations, but not supposed to be displayed on the
UI. Hiding fields is especially useful if you want to hide fields dynamically, e.g. if you want to show fields only
when they have positive values.
Note that you can annotate fields of list reports with @UI.hidden: true as well. However, this will only
deselect the annotated fields as columns, not hide them completely. It is effectively the same as if you hadn't
annotated the element with @UI.lineItem in the first place.
Place the annotation in the element list section of your CDS Data Definition or Metadata Extension, directly
For more details, see UI Annotations [page 1260].
Code Snippet
In this example, the Booking Fee shall not be displayed to the user, but might be necessary to calculate the total
price.

812 PUBLIC Develop
821].
annotate view ...

{
...
// ELEMENT LIST
...
@UI: { hidden: true }
BookingFee;
position: 10 } ] }
TotalPrice;
...

}
4.5.3.3.3.1 Hiding Fields Dynamically on the Object Page
How to use the hidden annotation to hide fields dynamically on the object page of your application.
Quick Info
@UI.identification: [{hidden:#('virtual
Annotation Syntax Element') }]
Description You can use the UI.identification annotation in

combination with a virtual element to enable or disable the
visibility of a field on the object page.
Use You can define a condition for the field visibility with a virtual
element. Depending on the condition, the field is visible or
not.
Related Topics • Modeling Virtual Elements [page 911]

• Implementing the Calculation of Virtual Elements
[page 912]
• UI Annotations [page 1260]
Context and Use
You can use the hidden annotation in combination with a virtual element to show or hide fields dynamically on
the UI depending on a boolean value. If the return value corresponds to true, the respective field is hidden and

Develop PUBLIC 813
if the value corresponds to false the respective field is shown on the user interface. You require the following
steps to enable dynamic field hiding with a virtual element:
1. Define a virtual element in the behavior definition projection. For more general information about how to
implement a virtual element, see Using Virtual Elements in CDS Projection Views [page 910].
2. Create an ABAP class to determine the return value for the virtual element.
3. Annotate the field you want to dynamically hide the respective field on the object page.
In the following you can see sample snippets of all components and below you can find an a sample
implementation for a particular use case.
Code Snippet
In the following definition, the extracted field is checked for its numeric value, if the value of FieldToCheck
is greater than 1000 then the method returns abap_true and the Field is hidden on the object page. If the
contained value is less then 1000, the methord returns abap_false and the Field is displayed on the user
interface. You can check any value against any condition and determine the visibility of the respective field
dynamically.
Example Definition: /DMO/Projection_View
define root view entity /DMO/Projection_View

as projection on /DMO/Root_View
{
@UI: {
identification: [ { position: 40, hidden: #(testField)} ] }
Field as Field,
@UI: {
FieldToCheck as FieldToCheck
@ObjectModel.virtualElementCalculatedBy: 'ABAP:Z_ShowField'
virtual testField :abap_boolean,

}
Example Definition: CLASS Z_ShowField
CLASS Z_ShowField DEFINITION

PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
INTERFACES IF_SADL_EXIT_CALC_ELEMENT_READ.
ENDCLASS.
CLASS Z_ShowField IMPLEMENTATION.
METHOD IF_SADL_EXIT_CALC_ELEMENT_READ~CALCULATE.
* Check the field for your condition and return either abap_true or abap_false
for the
* virtual field.
DATA LT_ORIGINAL_DATA TYPE STANDARD TABLE OF Z_FD_C_Travel_Processor_M WITH
DEFAULT KEY.
LT_ORIGINAL_DATA = CORRESPONDING #( IT_ORIGINAL_DATA ).
LOOP AT LT_ORIGINAL_DATA ASSIGNING FIELD-SYMBOL(<FS_ORIGINAL_DATA>).
<FS_ORIGINAL_DATA>-testField = COND ABAP_BOOLEAN( WHEN
<FS_ORIGINAL_DATA>-FieldToCheck > 1000 THEN ABAP_TRUE ELSE ABAP_FALSE ).
ENDLOOP.

814 PUBLIC Develop
CT_CALCULATED_DATA = CORRESPONDING #( LT_ORIGINAL_DATA ).
ENDMETHOD.
METHOD IF_SADL_EXIT_CALC_ELEMENT_READ~GET_CALCULATION_INFO.
* Extract the field you want the field visibility to depend on
*
IF IV_ENTITY <> '/DMO/Projection_View'.
RAISE EXCEPTION TYPE /dmo/cx_virtual_elements
EXPORTING
TEXTID = /dmo/cx_virtual_elements=>ENTITY_NOT_KNOWN
ENTITY = IV_ENTITY.
ENDIF.
LOOP AT IT_REQUESTED_CALC_ELEMENTS ASSIGNING FIELD-SYMBOL(<FS_CALC_ELEMENT>).
CASE <FS_CALC_ELEMENT>.
WHEN 'testField'.
APPEND 'FieldToCheck' TO ET_REQUESTED_ORIG_ELEMENTS.
...
ENDCASE.
ENDLOOP.
ENDMETHOD.

ENDCLASS.
4.5.3.3.4 Visualizing Data with Charts
Use Charts to visualize data on object pages.
Quick Info
@UI.facet: [ { id: '…', label: '…',

position: <value>, purpose: #STANDARD,
targetElement: '…', targetQualifier:
'…', type: #CHART_REFERENCE, hidden:
Annotation Syntax '…' } ]
Description Defines a facet for charts on the object page.
Use To be placed in the facet definition section of the code.
Annotation Syntax @Aggregation.default: #…
Description Aggregates data of a given element.
Use To be placed in the CDS view, above the element that you
want to aggregate.
 Note
You must aggregate data, otherwise your chart won't display meaningful data, i.e. will only display data of
one instance. For more information on aggregating data, see Using Aggregate Data in SAP Fiori Apps [page
901].

Develop PUBLIC 815
@UI.Chart: [ { title: '…', qualifier:
'…', chartType: '…', dimensions:
'…', measures: '…',measureAttributes:
[ { measure: '…', role: #… } ],
dimensionAttributes: [ { dimension: '…',
Annotation Syntax role: #… } ], description: '…'} ]
Description Defines the chart itself.
Use To be placed in the targetElement or its respective met-

adata extension of the @UI.facet annotation.
Preview on Fiori UI
Chart on the Object Page
Use in context
To succesfully implement a chart on your object page, you need to:
1. Define a facet for the chart in the parent CDS view

2. Aggregate data with @Aggregate.default annotation.
3. Define the chart itself with @UI.chart annotation.

816 PUBLIC Develop
Defining a facet for the chart
You must define a facet for your chart to define a spot for the chart on the object page and the data source of
the chart. See the sample code below for a better look on how a facet for a chart is defined.
annotate view Z_UI_TRAVEL with

{
...
@UI.facet: [
{ id: 'Chart1-ID',
position: 10,
purpose: #STANDARD,
targetElement: '_Booking'
}
]
...

}
Subannotation Syntax Description
id Defines a unique identifier for the facet, which you can

freely choose.
label Defines the name of the facet. The facet will not have a
name on the UI if you don't define a label.
position Defines the position of the facet.
purpose: #STANDARD Defines the purpose of the facet. Can be omitted in most
cases.
type: #CHART_REFERENCE Defines the type of the facet. Charts can only be displayed
in facets of type: #CHART_REFERENCE.
targetQualifier Unique identifier. Referenced by subannotation

qualifier of @UI.chart annotation in
targetElement.
targetElement Specifies where the data for the chart is retrieved from.
 Note
Charts can only be displayed in facets with purpose: #STANDARD. Charts are not supported in facets with
purpose: #HEADER.
Aggregating Data for the Chart
To aggregate data, you have to use the @Aggregation.default annotation. In our example, we use this
annotation to aggregate all flight prices and to convert them accordingly. We also use the annotation to
aggregate the number of distinct bookings. For more information on aggregating data, see Using Aggregate
Data in SAP Fiori Apps [page 901].

Develop PUBLIC 817
define view Z_C_BOOKING_R
as select from /dmo/booking as Booking
...
@Semantics.amount.currencyCode: 'TargetCurrency'
@Aggregation.default: #SUM
CURRENCY_CONVERSION(
amount => Booking.flight_price,
source_currency => Booking.currency_code,
target_currency => cast( 'EUR' as abap.cuky ),
exchange_rate_date => cast( '20200420' as abap.dats ),
error_handling => 'SET_TO_NULL' ) as
ConvertedFlightPrice,
_Customer.CountryCode as CountryCode,
@Aggregation.referenceElement: ['BookingID']
@Aggregation.default: #COUNT_DISTINCT
cast( 1 as abap.int4 ) as
DistinctBookings,

...
 Note
@Aggregation annotations are not permitted in metadata extensions. Therefore you have to place these
annotations directly into your CDS view.
Defining the Chart itself
See the sample code below for a better look on how the chart itself is defined. Note that you must place this
annotation in the entity previously specified by targetElement or its respective metadata extension.

@UI.chart: [{
qualifier: 'Chart1', //refers to targetQualifier defined in chart facet in
Z_C_TRAVEL_UI
title: 'Flight Prices of this Travel by Airline',
chartType: #COMBINATION_DUAL,
dimensions: [ 'AirlineID'],
measures: [ 'ConvertedFlightPrice', 'DistinctBookings'],
measureAttributes: [ {measure: 'ConvertedFlightPrice', role: #AXIS_1},
{measure: 'DistinctBookings', role: #AXIS_2} ],
dimensionAttributes: [ {dimension: 'AirlineID', role: #SERIES} ],
description: 'Chart shows flight prices of travel by the airlines used per
each booking.'
}
]
...
annotate view Z_UI_BOOKING_U with {

...
title Defines the title of the chart.
qualifier References the targetQualifier we set in the facet.
chartType Defines the type of the chart. There is a wide variety of chart
types available. For more information on chart types, see
Chart Types [page 819].

818 PUBLIC Develop
dimensions Defines the dimensions of the chart. Different chart

types require different quantities of dimensions. For more
information on dimensions and corresponding chart types,
see Chart Types [page 819].
measures Defines the measures of the chart. Different chart

types require different quantities of measures. For more
information on measures and corresponding chart types,
see Chart Types [page 819].
measureAttributes Defines which measure will be shown on which axis.

#AXIS_1 is the left axis, #AXIS_2 is the right axis.
dimensionAttributes Defines which dimension will be the primary on the UI.

#CATEGORY is the primary dimension, #CATEGORY2
is the secondary dimension. Note that we do not use
dimensionAttributes in this example, because we
only use one dimension.
description Internal description of the chart.
4.5.3.3.4.1 Chart Types
Get an overview of all currently supported chart types within CDS and their required dimension/measures.
Chart Types for Data Visualization
Chart Type Required Dimensions Required Measures
COLUMN Dimensions: 1+ Measures: 1+
Axis: x Axis: y
COLUMN_STACKED
Note: AREA, AREA_STACKED and
COLUMN_STACKED_100 AREA_STACKED_100 have the same re-
sult as COLUMN, COLUMN_STACKED
AREA
and COLUMN_STACKED_100 on the UI.
AREA_STACKED
AREA_STACKED_100
LINE
BAR Dimensions: 1+ Measures: 1+
Axis: y Axis: x
BAR_STACKED
Note: HORIZONTAL_AREA, HORIZON-
BAR_STACKED_100 TAL_AREA_STACKED and HORIZON-
TAL_AREA_STACKED_100 have the
HORIZONTAL_AREA

Develop PUBLIC 819
HORIZONTAL_AREA_STACKED same result as BAR, BAR_STACKED

and BAR_STACKED_100 on the UI.
HORIZONTAL_AREA_100
PIE Dimensions: 1+ Measures: 1+
Note: Determines by what the sections Note: Determines size of segment

DONUT
are segmented
SCATTER Dimensions: 1+ Measures: 2+
BUBBLE Dimensions: 1+ Measures: 3+
COMBINATION Dimensions: 1+ Measures: 2+

COMBINATION_STACKED
Axis: x Axis: y
COMBINATION_DUAL
COLUMN_DUAL
COLUMN_STACKED_DUAL
COLUMN_STACKED_DUAL_100
COMBINATION_STACKED_DUAL
LINE_DUAL
HORIZONTAL_COMBINATION Dimensions: 1+ Measures: 2+

HORIZONTAL_COMBINA-
Axis: y Axis: x
TION_STACKED
HORIZONTAL_COMBINATION_DUAL
BAR_DUAL
BAR_STACKED_DUAL
BAR_STACKED_DUAL_100
HORIZONTAL_COMBINA-
TION_STACKED_DUAL
HEAT_MAP Dimensions: 1+ Measures: 1+
Note: Determines the shade of color
BULLET Dimensions: 1+ Measures: 1+
Axis: y Axis: x
VERTICAL_BULLET Dimensions: 1+ Measures: 1+
Axis: x Axis: y
WATERFALL Directions: 1+ Measures: 1+
Axis: x Axis: y

820 PUBLIC Develop
HORIZONTAL_WATERFALL Directions: 1+ Measures: 1+
Axis: y Axis: x
4.5.3.4 Complete UI Annotations Example Code
Working Example Code for the use of UI annotations in CDS.
Metadata Extension for Main CDS View
Z_C_TRAVEL_R
 Sample Code

@UI: { headerInfo: { typeName: 'Object Page - Title',
title: { value: 'TravelID' }, // Defines the value shown
in title section
typeNamePlural: 'List Report - Table Header'
}
}

{
// FACET SECTION
@UI.facet: [
// Header Facet (Object Page):
{ id: 'HeaderFacet',
purpose: #HEADER,
label: 'Object Page - Header Facet',
targetQualifier: 'Fieldgroup:HeaderItems', // Refers to
lineItems with @UI.fieldGroup: [{qualifier: 'Fieldgroup:HeaderItems'}]
position: 10 },
// Facet for chart - charts can only be displayed in facets
{ id: 'Chart1-ID', // Facet for our Chart with type

"#CHART_REFERENCE"
purpose: #STANDARD,
targetElement: '_Booking', // Specifies where the data is
retrieved from
position: 1

Develop PUBLIC 821
},
{ id: 'Facet1-ID',
type: #COLLECTION,
position: 10 },

1'
position: 10 },

1'
targetQualifier: 'Fieldgroup2', // No targetElement defined -
Default target is the entity in which the facet is defined
position: 20 },
// Facet 2
{ id: 'Facet2-ID',
type: #LINEITEM_REFERENCE, // Facet shows the
referenced items in a list report
label: 'Facet 2 - Bookings',
targetQualifier: 'Facet2',
position: 20,
targetElement: '_Booking'},
// Facet 3
{ id: 'Facet3-ID',
purpose: #STANDARD,
position: 30 }
]
// ELEMENT LIST

position: 10 } ] }
TravelID;
importance: #HIGH,
label: 'Agency' } ],
identification: [ { position: 20,
label: 'Agency'} ],
position: 20 } ] }
AgencyID;
importance: #HIGH,
label: 'Customer' } ],

822 PUBLIC Develop
label: 'Customer' } ],
position: 10 } ] }
CustomerID;
label: 'Start of Travel' } ],
label: 'Start of Travel' } ],
position: 20 } ] }
BeginDate;
label: 'End of Travel',
label: 'End of Travel' } ],
position: 10 } ] }
EndDate;
position: 10 } ] }
BookingFee;
position: 10 } ],
dataPoint: { title: 'Total Price',
targetValueElement: 'TotalPrice' } }
TotalPrice;
@UI: { identification: [ { position: 70,
position: 10 } ] }
Memo;
position: 10 } ] }
Status;

}
Metadata Extension for _Customer
Z_C_CUSTOMER_R
 Sample Code

annotate view Z_C_CUSTOMER_R
with
{
Street;

Develop PUBLIC 823
@UI.fieldGroup: [{qualifier: 'Fieldgroup1', position: 10}] // Using gaps
between position numbering for easier modification later on
CustomerID;

FirstName;

LastName;

Title;

PostalCode;

City;

CountryCode;

PhoneNumber;

EMailAddress;
/* Associations */
_Country;

}
Metadata Extension for _Booking
Z_C_BOOKING_R
 Sample Code

@UI.chart: [{
qualifier: 'Chart1', //refers to targetQualifier defined in chart facet
in Z_C_TRAVEL_UI
title: 'Flight Prices of this Travel by Airline',
chartType: #COMBINATION_DUAL,
dimensions: [ 'AirlineID'],
measures: [ 'ConvertedFlightPrice', 'DistinctBookings'],
measureAttributes: [ {measure: 'ConvertedFlightPrice', role: #AXIS_1},
{measure: 'DistinctBookings', role: #AXIS_2} ],
dimensionAttributes: [ {dimension: 'AirlineID', role: #SERIES} ],
description: 'Chart shows flight prices of travel by the airlines used
per each booking.'
}
]
annotate view Z_C_BOOKING_R with
{
@UI.lineItem:
[{ qualifier: 'Facet2',

824 PUBLIC Develop
position: 10,
label: 'Travel No.',
hidden: true }]
TravelID;
@UI.lineItem:
position: 20,
label: 'Booking No.' }]
BookingID;
@UI.lineItem:
position: 30,
label: 'Date of Booking' }]
BookingDate;
@UI.lineItem:
position: 40,
label: 'Customer' }]
CustomerID;
@UI.lineItem:
position: 50,
label: 'Airline' }]
AirlineID;
@UI.lineItem:
position: 60,
label: 'Connection No.' }]
ConnectionID;
@UI.lineItem:
position: 70,
label: 'Date of flight' }]
FlightDate;
@UI.lineItem:
position: 80,
label: 'Flight Price' }]
FlightPrice;
@UI.lineItem:
position: 90,
label: 'Currency' }]
CurrencyCode;

}
4.5.3.5 Further Options for Metadata-Driven UIs
4.5.3.5.1 Field Manipulation
Get information about what UI annotations to use to manipulate fields for SAP Fiori UIs.
This chapter describes annotations that influence the appearance exposed fields. When a field is marked with
these annotations, it is manipulated no matter in what other annotations the field is used. The reason for this is
that annotations for manipulation are self-contained annotations and not properties of other annotations.
For example, when a field is marked with the @UI.masked [page 1329] annotation, the field is masked
regardless if it is used in a @UI.lineItem [page 1335]annotation or a @UI.identification [page 1342] annotation.

Develop PUBLIC 825
To manipulate the appearance of fields on SAP Fiori UIs, you can use the annotations explained in the following
sections:
• Multi-Line Text [page 826]

Here you get information about what UI annotations to use to display fields as multi-line text on SAP Fiori
UIs.
• Field Masking [page 827]
Here you get information about what UI annotations to use to mask fields.
• Interaction with Other Annotations [page 827]
Here you get information about how to provide interaction between annotations.
4.5.3.5.1.1 Multi-Line Text
Get information about what UI annotations to use to display fields as multi-line text on SAP Fiori UIs.
You can use the following annotation to mark a field to be displayed by a control that supports multi-line input,
for example a text area:
• @UI.multiLineText [page 1329]
 Sample Code
...

define view Product as select from ... {
@UI.identification: [ { position: 10 } ]
key ProductID,
ProductName,
@UI.multiLineText: true
Description,
...
}

Related Information
Field Manipulation [page 825]

Field Masking [page 827]
Interaction with Other Annotations [page 827]
Hiding Fields on the Object Page [page 812]

826 PUBLIC Develop
4.5.3.5.1.2 Field Masking
Get information about what UI annotations to use to mask fields, for example for password input, on SAP Fiori
UIs.
In some cases, data of fields need to be consumed by the client, but must not be visible on the UI. This field
behavior is required when users need to enter passwords, for example.
You can use the following annotation to mark a field to not to be displayed in clear text by the client because, for
example, it contains sensitive data:
• @UI.Masked [page 1329]

This annotation does not influence how data is transferred. If a field is marked with the @UI.masked [page
1329] annotation, the data belonging to this field is still transferred to the client like any other property in
clear text.
 Sample Code
...

define view Destination as select from ... {
key DestinationID,
...
AuthType, -- None, Basic, SSO, ...
BasicAuthUserName,
@UI.masked
BasicAuthPassword,
...
}

Related Information

Multi-Line Text [page 826]
Interaction with Other Annotations [page 827]
4.5.3.5.1.3 Interaction with Other Annotations
Get information about how to provide interaction between annotations.
In addition to UI annotations, you can use model-specific annotations that affect the desired client
behavior. You can implement, for example, unit-currency-mappings or ID-text-mappings. These model-specific
annotations can be evaluated by the client and no additional UI annotations are required.

Develop PUBLIC 827
Example of interaction between CDS annotations
 Example
In the following example, the field CurrencyCode is marked with a @Semantics.currencyCode [page 1253]
and is referenced by field GrossAmount. This means that the field GrossAmount is always displayed with
the corresponding currency. The field CurrencyCode does not need to be exposed explicitly.
 Sample Code
...

define view ZExample_SalesOrder as select from sepm_cds_sales_order as so
{
key so.sales_order_id as SalesOrder,
so.currency_code as CurrencyCode,
@UI.identification: [ { position: '20' } ]
so.gross_amount as GrossAmount,

Related Information

Multi-Line Text [page 826]
Field Masking [page 827]
4.5.3.5.1.4 Inheritance of Annotations
Get information about what property to use to prevent elements from being inherited from an underlying CDS
view.
By default, all UI annotation elements are inherited from the underlying CDS view. You can explicitely disable
this behavior. You can use the following property to prevent a UI annotation element from being inherited:

828 PUBLIC Develop
• exclude
The following sample code depicts the CDS view ZP_SalesOrder that inherits elements from the
underlying CDS view SEPM_CDS_SALES_ORDER, and uses the UI annotation @UI.identification [page 1342]:
 Sample Code
...

define view ZP_SalesOrder as select from sepm_cds_sales_order as so {
so.customer.company_name as CompanyName,
...

}
The following sample code depicts the CDS view ZI_SalesOrder that inherits elements from
the underlying CDS view ZP_SalesOrder. In this view, the element key SalesOrder is inherited
from the underlying CDS view as UI annotation @UI.identification [page 1342] by default. The
element so.customer.company_name as CompanyName, however, is not inherited as UI annotation
@UI.identification [page 1342] because of the property exclude:
 Sample Code
...

define view ZI_SalesOrder as select from ZP_SalesOrder as so {
key SalesOrder,
@UI.identification: [ { exclude } ]
...

}
4.5.3.5.2 Data Points
Get an overview of how to use data points to display criticality, trends, and references to people and time
periods on SAP Fiori UIs.
In some cases, you want to visualize a single point of data that typically is a number that can be enriched with
business-relevant data but may also be textual, for example a status value.

Develop PUBLIC 829
Example of data points
You can use the following UI annotation to define a single point of data:
• @UI.dataPoint [page 1300]

You can, for example, express if a high or a low value is desired, or if a value is increasing or decreasing. The
simplest variant of the UI annotation @UI.dataPoint [page 1300] consists of the title property.
Example of simple variant of data point
In the following example, only the title is exposed to the UI.
 Sample Code
...

define view ZExample_SalesOrdersByCustomer as select from ... as so {
key so.buyer_guid as BuyerGuid,
@UI.dataPoint: { title: 'Gross Amount' }

so.actual_amount as ActualAmount
}

Related Information

830 PUBLIC Develop
Criticality [page 831]
Trends [page 832]
Trend-Criticality Calculation [page 834]
Person Responsible and Reference Period [page 837]
DataField Type: #AS_DATAPOINT [page 839]
4.5.3.5.2.1 Criticality
Get information about how to use data points to display criticality on SAP Fiori UIs.
A more usable variant of the UI annotation @UI.dataPoint [page 1300]also contains information about the
criticality, the trend, and the name of a person responsible.
You can use the sub-annotation @dataPoint.criticality [page 1305] to express if a value is positive or negative,
for example.
You can use the sub-annotation @dataPoint.trend [page 1307] to express if a value has decreased or increased,
for example.
In this case, the properties targetValue, criticality, and trend are already evaluated in the CDS view.
In the CDS view, the target value is already calculated, and if the current value thus is negative or positive,
and if the current value has improved or declined, for example. These values are only referred to from the
@UI.dataPoint [page 1300] annotation.
Data can be defined as being either positive, critical, or negative. These data can be statuses, for example.
You can use the following sub-annotation to highlight criticality:
• UI.dataPoint.criticality [page 1305]

You define this UI annotation at view level. It refers to the elements that are to be used in the chart.
Additionally, you can provide a title and description.
The table below lists the values that are valid for the UI annotation @UI.dataPoint.criticality [page 1305],
and shows how these values are visualized on the UI:
Values and Visualization of Criticality
Value Description Visualization in Color
1 Negative Red
2 Critical Yellow
3 Positive Green
 Sample Code
...


Develop PUBLIC 831
@UI.dataPoint: {
title: 'Gross Amount',
targetValueElement: 'TargetAmount', -- Reference to element
criticality: 'AmountCriticality', -- Reference to element
trend: 'AmountTrend', -- Reference to element
}
so.actual_amount as ActualAmount,
so.target_amount as TargetAmount,
so.criticality as AmountCriticality,
so.trend as AmountTrend
}

Related Information
Data Points [page 829]

Trends [page 832]
4.5.3.5.2.2 Trends
Get information about how to use data points to display trends on SAP Fiori UIs.
Data can be defined as being either increasing, decreasing, or stable. These data can be measured over a
certain period of time and visualized on the UI.
You can use the following sub-annotations to highlight trends:
• @UI.dataPoint.trend [page 1307]
 Example
For an example, see the example code in section Criticality linked below.
• @UI.dataPoint.trendCalculation [page 1308]
 Example
The table below lists the values that are valid for the UI annotation @UI.dataPoint.trendCalculation
[page 1308], and shows how these values are visualized on the UI:

832 PUBLIC Develop
Values and Visualization of Trend
Value Description Visualization
1 Strong up
2 Up
3 Sideways
4 Down
5 Strong down
For the trend calculation, the flag isRelativeDifference indicates whether the absolute or the relative
difference between the actual value and the reference value is used to calculate the trend.
Visualization of trend calculation
 Sample Code
...

@UI.dataPoint: {
//...
trendCalculation: {
referenceValue: 'ReferenceAmount', -- Reference to element
isRelativeDifference: true, -- Comparison of ratio
strongUpDifference: 1.25,
upDifference: 1.1,
downDifference: 0.9,

Develop PUBLIC 833
strongDownDifference: 0.75
}
}
so.reference_amount as ReferenceAmount
}

Related Information

4.5.3.5.2.3 Trend-Criticality Calculation
Get information about how to use data points to calculate and display trend-criticality relations.
Another way to specify properties of criticality and trend is to define rules for criticality and trend within the UI
annotation @UI.dataPoint [page 1300].
Example of visualization of trend-criticality calculation
You can use the following sub-annotations to calculate trends and derive from these calculation the criticality of
data:

834 PUBLIC Develop
• @UI.dataPoint.trendCalculation [page 1308]
• @UI.dataPoint.criticalityCalculation [page 1307]
 Sample Code
...

@UI.dataPoint: {
targetValue: 9216,
criticalityCalculation: {
improvementDirection: #TARGET,
toleranceRangeLowValue: 9200,
toleranceRangeHighValue: 9300,
deviationRangeLowValue: 8800,
deviationRangeHighValue: 9700
},
trendCalculation: {
referenceValue: 'ReferenceAmount', -- Reference to element
isRelativeDifference: false, -- Comparison of difference
strongUpDifference: 100,
upDifference: 10,
downDifference: -10,
strongDownDifference: -100
}
}
so.reference_amount as ReferenceAmount
}

For the criticality calculation, the value of the property improvementDirection is crucial because this
value determines what further properties are needed. If, for example, the value is #MINIMIZE, the properties
ToleranceRangeHighValue and DeviationRangeHighValue are relevant.
Example of improvementDirection: #TARGET

Develop PUBLIC 835
Example of improvementDirection: # MINIMIZE
Example of improvementDirection: # MAXIMIZE
The properties of the sub-annotation @UI.dataPoint.criticalityCalculation [page 1307] can have either constant
values or derive values from referencing to other elements. If a property references to another element, the
suffix Element must be added to the name of the property.
 Note
This also applies to the properties of the sub-annotation @UI.dataPoint.trendCalculation [page 1308],
except for the property referenceValue. This property always references to another element.
 Example
toleranceRangeLowValue becomes toleranceRangeLowValueElement.

836 PUBLIC Develop
Related Information

Trends [page 832]
4.5.3.5.2.4 Person Responsible and Reference Period
Get information about how to use data points to display references to persons responsible and to reference
periods on SAP Fiori UIs.
You can add the following properties to the UI annotation @UI.dataPoint [page 1300]:
• referencePeriod
• responsibleName
You can define both properties either in the UI annotation directly, or in another element and reference from
the UI annotation to this element.
 Example
In the following example, the data point has a static reference period and a static person responsible. The
value of the gross amount is formatted with the valueFormat property. The value is thus scaled with
factor 1000 and is displayed with one decimal place, this is the value 34500 EUR would be displayed as
34.5 kEUR.
Example of visualization of person responsible, reference period, and value format

Develop PUBLIC 837
 Sample Code
...

@UI.dataPoint: {
description: 'Gross Amount per Customer',
longDescription: 'The gross amount per customer ...',
valueFormat: {
scaleFactor: 1000,
numberOfFractionalDigits: 1
},
referencePeriod: { description: '2015 Q3' },
responsibleName: 'John Doe'
}
}

 Example
In the following example, a dynamic reference period is used that is supplied by the following parameters:
• start
• end
These parameters have to be aliased in the element list before they can be used in the @UI.dataPoint [page
1300] annotation. The responsible property must refer to a to-one-association. The target entity of this
association should contain the contact data of the person responsible.
 Sample Code
...

define view ZExample_SalesOrdersByCust
with parameters p_StartDate : abap.dats,
p_EndDate : abap.dats
as select from ... as so
association [0..1] to Employees as _PersonResponsible
on _PersonResponsible.EmployeeId = $projection.PersonResponsible
{
...
$parameters.p_StartDate as StartDate, -- Alias is required for
annotation
$parameters.p_EndDate as EndDate, -- Alias is required for
annotation
so.person_responsible as PersonResponsible,
@UI.dataPoint: {
referencePeriod: {
start: 'StartDate', -- Reference to element
end: 'EndDate' -- Reference to element
},
responsible: '_PersonResponsible' -- Reference to association
}

838 PUBLIC Develop
@DefaultAggregation: #SUM
so.actual_amount as ActualAmount,
_PersonResponsible
}
where so.validity_date >= $parameters.p_StartDate
and so.validity_date <= $parameters.p_EndDate

 Sample Code
For a definition of element list, see section Glossary linked below.
Related Information

Trends [page 832]
4.5.3.5.2.5 DataField Type: #AS_DATAPOINT
Get information about how to use the type #AS_DATAPOINT to refer to other annotations.
The type #AS_DATAPOINT maps to DataFieldForAnnotation. DataFieldForAnnotation is used to refer to other

annotations using the Edm.AnnotationPath abstract type. The annotation path must end in vCard.Address or
UI.dataPoint.
You can use the following type to reference an exposed data point from dataField-like annotations:
• #AS_DATAPOINT
You use this type to include a microchart in the UI annotation @UI.lineItem [page 1335], for example.
 Example
In this example, the UI annotation @UI.lineItem [page 1335] has to be defined at the same CDS element as
the UI annotation @UI.dataPoint [page 1300] itself.
 Sample Code
...

...
@UI.dataPoint: { title: 'Gross Amount' }

@UI.lineItem: [ { type: #AS_DATAPOINT } ]

Develop PUBLIC 839
}

Related Information

Trends [page 832]
4.5.3.5.3 Actions
Get information about how to use dataField types to provide means of executing actions on SAP Fiori UIs.
Actions are directly related to items that you can see in a table on a master-detail floorplan, for example. Users
can select items and execute certain actions on the selected items.

840 PUBLIC Develop
Example of action 'Copy' on master-detail floorplan
You can use the following dataField type to expose actions to the client:
• #FOR_ACTION
This property has to be assigned to some arbitrary element. It is thereby irrelevant if the property refers to
the element to which the property is assigned.
 Sample Code
...

define view ZExample_SalesOrder as select from sepm_cds_sales_order as so {
@UI.lineItem: [
-- Standard Lineitem
{ position: 10 },
-- Action Lineitem
{ type: #FOR_ACTION, dataAction: 'Copy', label: 'Copy' }
]
...

Develop PUBLIC 841
}

4.5.3.5.4 Navigation
Get an overview of how to use dataField types to provide means of navigation on SAP Fiori UIs.
It often is not sufficient to stay on one screen. Users might need to navigate between screens or even to web
sites outside an application. You can use the following dataField types ton include navigation concepts:
• #WITH_NAVIGATION_PATH [page 842]

Used for navigation within an application.
• #WITH_URL [page 844]
Used for navigation from an application to an external web site.
• #FOR_INTENT_BASED_NAVIGATION [page 846]
Used for navigation based on an action that is related to a semantic object.
4.5.3.5.4.1 With Navigation Path
Get information about how to provide navigation between UI screens and pages on SAP Fiori UIs.
This navigation type contains either a navigation property or a term cast. The term either is of type
Edm.EntityType, a concrete entity type, or a collection of these types.

842 PUBLIC Develop
Example of dataField of type #WITH_NAVIGATION_PATH
You can use the following dataField type to expose a link to other pages of a UI:
• #WITH_NAVIGATION_PATH
 Example
In the following example, CompanyName is displayed as link referring to the association

_BusinessPartner.
 Sample Code
...

define view ZExample_SalesOrder as select from sepm_cds_sales_order as
so
association [0..1] to sepm_cds_business_partner as _BusinessPartner
on $projection.buyer_guid = _BusinessPartner.business_partner_key
{
so.buyer_guid,
...
@UI.lineItem: [ {
position: 20,

Develop PUBLIC 843
type: #WITH_NAVIGATION_PATH,
targetElement: '_BusinessPartner' -- Reference to association
} ]
...
_BusinessPartner
}

Related Information
Navigation [page 842]

With URL [page 844]
Based on Intent [page 846]
4.5.3.5.4.2 With URL
Get information about how to provide navigation from SAP Fiori UIs to external web sites, for example.
This type navigation type contains a reference to a URL to navigate to specific web sites, for example.

844 PUBLIC Develop
Example of dataField of type #WITH_URL
You can use the following dataField type to display links to external websites:
• #WITH_URL
 Example
In the following example, CompanyName is displayed as link referring to the CDS element WebsiteUrl.
 Sample Code
...

so
{
...
@UI.lineItem: [ {
position: 20,
type: #WITH_URL,
url: 'WebsiteUrl' -- Reference to element
} ]

Develop PUBLIC 845
so.customer.web_address as WebsiteUrl,
...
}

Related Information

With Navigation Path [page 842]
Based on Intent [page 846]
4.5.3.5.4.3 Based on Intent
Get information about how to provide navigation related on actions that are executed on SAP Fiori UIs.
This navigation type contains an action that is related to a semantic object. This combination of action
and semantic object is an intent. The annotation @Consumption.semanticObject [page 1198] is required for
navigation based on intent. The client decides how to react when this navigation is triggered.

846 PUBLIC Develop
Example of dataField of type #FOR_INTENT_BASED_NAVIGATION
You can use the following dataField type to expose the intent to navigate without specifying how this navigation
is to be resolved:
• #FOR_INTENT_BASED_NAVIGATION
 Example
In the following example, the intent 'Show' (action) 'BusinessPartner' (semantic object) is
expressed. The client can, for example, open a separate application to display the details of the
corresponding business partner.
 Sample Code
...

so
{

Develop PUBLIC 847
...
@UI.lineItem: [ {
position: 20,
label: 'Show customer-details',
type: #FOR_INTENT_BASED_NAVIGATION,
semanticObjectAction: 'Show' -- Action
} ]
@Consumption.semanticObject: 'BusinessPartner' -- Semantic Object
...
}

Related Information

With Navigation Path [page 842]
With URL [page 844]
4.5.3.5.5 Contact Data
Get information about what UI annotations to use to display contact data on SAP Fiori UIs.
In some cases users of an application need to see contact data, for example, of business partners, customers,
or employees.
You can use the following annotation set to inform a client that an entity contains contact information and map
the CDS elements to the corresponding address field:
• @Semantics
This annotation set contains annotations to inform about telephone numbers, email addresses, names,
addresses, and contacts.
 Example
The following example contains sub-annotations belonging to the annotation set @Semantics. For a
complete list, see section Semantics Annotations linked below.
 Sample Code
...

define view Employees as select from ...
{
key EmployeeId,
@Semantics.name.givenName
FirstName,
@Semantics.name.additionalName
MiddleName,

848 PUBLIC Develop
@Semantics.name.familyName
LastName,
GenderCode,
@Semantics.telephone.type: [#WORK, #PREF]
PhoneNumber,
@Semantics.telephone.type: [#FAX]
FaxNumber,
@Semantics.telephone.type: [#CELL]
MobilePhoneNumber,
@Semantics.eMail.address
EmailAddress,
PreferredLanguage,
@Semantics.contact.birthDate
BirthDate
}

Related Information
Semantics Annotations [page 1247]
4.6 Develop Individual BO Capabilities
This chapter outlines how to develop individual RAP BO capabilities like for example numbering scenarios or
message exposure.
• Using Type and Control Mapping

Whenever existing legacy code and data types are to be reused in behavior pools of business objects, then
you need to perform a mapping between CDS field names and types and corresponding legacy field names
and types.
• Exposing Messages on the UI and Message Mapping

Well-designed messages help to recognize, diagnose, and resolve issues. That's why it's important to
always use messages consistently and optimize the interaction as a whole.
Editing Language-Dependent Fields [page 854]

You can behavior-enable denormalized text elements in business objects by augmenting incoming
requests with modify requests for the denormalized elements. This topic guides you through the steps
to enable end users to maintain language-dependent texts in their log-on language.
Using Type and Control Mapping [page 861]

Whenever existing legacy code and data types are to be reused in behavior pools of business objects,
then you need to perform a mapping between CDS field names and types and corresponding legacy
field names and types.
Exposing Messages on the UI and Message Mapping [page 865]
Working with Large Objects [page 882]
Creating RAP Business Events [page 884]

Develop PUBLIC 849
This topic explains how you can use events in a RAP BO to enable asynchronous communication
between the RAP BO as event provider and an event consumer, such as an application in a cross-
system landscape.
Modeling Parameters for Non-Standard Operations [page 887]

This topic explains how you model parameters and use their representations in ABAP.
4.6.1 Numbering
4.6.1.1 Automatically Drawing Primary Key Values in

Managed BOs
In managed scenarios with UUID keys, the values for primary key fields can be automatically generated by the
managed runtime framework.
Context
Values for primary key fields can be generated automatically for managed business objects. This so-called
Managed Internal Early Numbering [page 26] is defined in the behavior definition of the business object.
During the CREATE operation, the managed runtime framework draws the UUID automatically for the defined
key fields. The newly created BO instance is immediately uniquely identifiable after the CREATE operation and
saved with the given key during the save sequence.
For more information, see Numbering [page 23].
Prerequisites
• The primary key field has the ABAP type raw(16) (UUID).
• The implementation type of the RAP BO is managed.
For details about the syntax for defining managed early numbering for primary key fields in the behavior
definition, see CDS BDL - field numbering (ABAP- Keyword Documentation)
The key field must be read-only if you intend the key fields to be filled internally only. If you do not set the
key field to read-only, the key value can also be given by the consumer. However, use cases for this optional
external numbering [page 24] are rare, as it is untypical for the consumer to fill in a UUID value.
Example
The following simplified BO exemplifies the use case to have the framework generate a UUID key for a managed
BO.

850 PUBLIC Develop
1. Database table /dmo/travel_uuid
The basis for the data model is a database table similar to /DMO/travel (that is included in the ABAP
Flight Reference Scenario [page 309]). To demonstrate managed numbering, we need a key field with
UUID type (raw(16)) .

define table /dmo/travel_uuid {
travel_id : /dmo/travel_id;
@Semantics.amount.currencyCode : '/dmo/travel_uuid.currency_code'
@Semantics.amount.currencyCode : '/dmo/travel_uuid.currency_code'
created_by : syuname;
last_changed_by : syuname;
last_changed_at : timestampl;

}
2. CDS root view /DMO/I_TRAVEL_UUID

The data model for the simplified travel scenario is defined in a CDS view that is similar to /DMO/
I_TRAVEL_M. The difference in the UUID scenario is that the UUID key field is obligatory. In addition
to the UUID key field, the travel CDS view also defines the non-key field travel_id, which assigns an
additional semantic identifier. This semantic key is not a key element in the scenario. It simply serves as an
additional, more simple, identifier that is easier to read by consumers. The value for this field is assigned
via a determination in the behavior pool.  Expand the following code sample to view the source code
 Sample Code
@AbapCatalog.sqlViewName: '/dmo/itraveluuid'

@AbapCatalog.compiler.compareFilter: true
@AbapCatalog.preserveKey: true
@EndUserText.label: 'Root View with Travel UUID'
define view /dmo/i_travel_uuid as select from /dmo/travel_uuid
{ ///dmo/travel_uuid
key travel_uuid,
travel_id,
agency_id,
customer_id,
begin_date,
end_date,
booking_fee,
total_price,
@semantics.currencyCode: true
currency_code,
description,
overall_status,

Develop PUBLIC 851
created_by,
created_at,
last_changed_by,
last_changed_at

}
3. Behavior Definition /DMO/I_TRAVEL_UUID

For the root CDS view /DMO/I_TRAVEL_UUID, the following behavior definition defines managed
numbering for the UUID key field travel_uuid.
The key UUID field is defined as read only. Not setting the key field to read only causes optional
external numbering [page 24], in which it is also possible for the consumer to set the value manually.
In this scenario, we want to set the value for the additional identifier travel_id by a determination.
Therefore, this field is also set to read-only.
 Sample Code
managed;

define behavior for /dmo/i_travel_uuid alias Travel
implementation in class /dmo/bp_i_travel_uuid unique
persistent table /DMO/TRAVEL_UUID
lock master
{
field ( read only, numbering : managed ) travel_uuid;
field ( read only ) travel_id;
create;
update;
delete;
//** optional determination to determine the travel ID
determination CreateKeys on modify { create; }

}
4. Optional: Determination to determine the value for semantic travel identifier

The value for the travel_id field is assigned via a determination. In this way, the consumer does not have
to enter the semantic identifier manually. It is assigned on CREATE.
The determination is defined in the behavior definition and implemented in the behavior pool. For more
information, see Determinations [page 119].
For the implementation, get a new travel id and execute an EML modify on the newly created instance to
assign the new travel ID to the instance. To make sure that the determination result does not change in
case it is executed twice under the same circumstances, we have to make sure that a new travel id is only
assigned if the the travel id field is initial.
 Note
To ensure that one travel ID is only assigned once, you can use a number range object.
The following code example does not show how to get this new travel ID. It is just suggested by the
method call of get_number.

852 PUBLIC Develop
 Sample Code
CLASS lhc_Travel_UUID DEFINITION INHERITING FROM cl_abap_behavior_handler.

PRIVATE SECTION.
METHODS CreateKeys FOR DETERMINATION Travel~CreateKeys
IMPORTING keys FOR Travel.
ENDCLASS.
CLASS lhc_Travel IMPLEMENTATION.
METHOD CreateKeys.
" Read entity to check if travel id is initial
READ ENTITIES OF zmv_i_travel_uuid IN LOCAL MODE
ENTITY travel
FIELDS ( travel_id )
RESULT DATA(lt_travel_result).
" only modify entities where no travel_id is given

DELETE lt_travel_result WHERE travel_id IS NOT INITIAL.
LOOP AT lt_travel_result ASSIGNING FIELD-SYMBOL(<fs_travel>).
" get a new travel ID
DATA(lv_travel_id_new) = get_number( ).
<fs_travel>-travel_id = lv_travel_id_new.
ENDLOOP.
MODIFY ENTITIES OF zmv_i_travel_uuid IN LOCAL MODE
ENTITY travel
UPDATE FROM VALUE #( FOR travel IN lt_travel_result
( travel_uuid = travel-%key-travel_uuid
travel_id = travel-travel_id
%control-travel_id = if_abap_behv=>mk-on ) ).
ENDMETHOD.

ENDCLASS.
5. UI Preview
The following figure shows the creation of a new travel instance when using managed numbering for the
UUID key field and a determination to assign the semantic identifier on CREATE.
For this example to run like it is shown below, you must add UI annotations to the elements in the CDS view.
 Note
This example scenario to automatically draw UUID values for primary key fields is highly simplified.
Basic important elements of a travel scenario, such as eTag or BO projection, are left aside to focus on
the principle of managed early numbering.

Develop PUBLIC 853
Managed Numbering in UUID Scenario
Related Information
Numbering [page 23]
4.6.2 Editing Language-Dependent Fields
You can behavior-enable denormalized text elements in business objects by augmenting incoming requests
with modify requests for the denormalized elements. This topic guides you through the steps to enable end
users to maintain language-dependent texts in their log-on language.
Context
Language-dependent text is usually stored in a separate text table that contains the same text in different
languages. One data set is only uniquely identifiable if the field that determines the language is part of the
key. The ABAP RESTful Application Programming Model offers an option to expose language-dependent text
elements for a Fiori UI in the log-on language of the browser.
The exposure of such a language-dependent fields is usually done by denormalizing the text field in the
projection view and adding the syntax element localized. This reduces the cardinality of the one-to-many
association to a one-to-one relationship, as the text provider view is filtered by the log-on language and the
result set of the association is reduced to data sets of one language. The structure of such a scenario is
illustrated in Getting Language-Dependent Text in Projection Views [page 895].

854 PUBLIC Develop
For business objects that maintain entities with language-dependent text fields, you can behavior-enable
denormalized text elements to enable an end user to create and update the corresponding text in the log-on
language; even if this text is taken from a separate text view.
To include denormalized fields, for example language-dependent text fields, into transactional handling, you
must modify-enable them in the projection behavior definition. Such fields can then also be defined with field
characteristics and dynamic field control.
For more information about the syntax, see CDS BDL - field characteristics, projection BDEF (ABAP - Keyword
Documentation) .
Example Scenario
To illustrate the functionality of editing language-dependent text by using an augmentation implementation,

we use an example from the ABAP Flight Reference Scenario. We use a business object that maintains
supplements that an end user can book for a flight booking in a travel business object. The following diagram
shows the structure of the supplement business object.
 Restriction
Structure of Supplement BO for Editing Text Fields
Runtime Aspects
Text elements are stored in a separate database table and managed by a separate CDS view to be able to store
texts in multiple languages. Due to the filtering of localized in the projection view, the one-to-n-relationship
is reduced to a one-to-one relationship; and as the text field is denormalized in the main CDS view, it can be
displayed together with the fields of the main view on the UI. Thus, the end user cannot differentiate between
fields of the main view and text elements that derive from a separate CDS view. Consequently, the end user
must be able to create and update fields from a text provider view in the same manner as other text fields.
During runtime, this means, that a create request for an instance that has a denormalized text field must be
transformed to two requests: A CREATE request for the main view and a CREATE_BY_ASSOCIATION for the
associated text provider view.

Develop PUBLIC 855
The RESTful Application Programming Model offers the option to implement such a transformation before
the CREATE request reaches the application buffer. The relevant operations in the projection business object
are augmented. The logic of the augmentation must be implemented in the corresponding behavior pool in
the method for augmentation. The following diagram illustrates the runtime process for the above mentioned
example scenario.
Runtime for Editing Denormalized Text Fields
When an UPDATE request is sent, the augmentation method must transform the request in an UPDATE request
for the main entity and in an UPDATE request for the text provider entity.
 Note
The behavior pool for a projection behavior definition generates two separate methods, if both, the CREATE
and the UPDATE operation, are augmented in the behavior definition. However, it is best practice to
implement the logic for both operations in one single method for augmented operations. The reason for
this is to support requests that create and update an instance in one logical unit of work. In such cases, the
%cid_ref must be used to refer to a newly created instance in the implementation.
A step-by-step description for such an augmentation implementation is provided in Editing Text for
Supplements [page 857].

856 PUBLIC Develop
4.6.2.1 Editing Text for Supplements
By using an example of the ABAP Flight Reference Scenario, this topic guides you through the steps to enable
end users to maintain language-dependent product descriptions for supplements in their log-on language.
The example in this topic is taken from the ABAP Flight Reference Scenario, which you can download from
GitHub, see ABAP Flight Reference Scenario [page 309].
 Restriction
The supplement business object in package /DMO/FLIGHT_REUSE is modeled with the CDS root view
entity /DMO/I_Supplement and its projection view /DMO/C_Supplement. The text provider view is in
a compositional relationship and contains the text element and the language field. The text element is
denormalized in the projection view and the logic on how to edit this denormalized is implemented in the
behavior pool for the projection behavior definition.
Prerequisites
• You have modeled language-dependent text elements as described in Getting Language-Dependent Text in
• The view with the denormalized text and the text provider view are in a parent-child relationship in your
business object.
• The business object is create- and update-enabled.
Procedure
1. In your projection behavior definition, define augmentation for the create and the update operation.
projection implementation in class /dmo/bp_c_supplement unique;

strict;
use draft;
define behavior for /DMO/C_Supplement alias Supplement
{
use create ( augment );
use update ( augment );
use delete;

}
2. To behavior-enable the denormalized text field, add it to the projection behavior definition as a modifiable
field.
projection implementation in class /dmo/bp_c_supplement unique;

strict;
use draft;
define behavior for /DMO/C_Supplement alias Supplement
{

Develop PUBLIC 857
use create ( augment );
use update ( augment );
use delete;
field ( modify ) SupplementDescription;

}
3. In the behavior pool for the projection business object, add a method for the augmentation
implementation with an importing parameter for CREATE and one for UPDATE.
 Note
If you don't have an implementation class for the projection behavior definition yet, you will receive a
warning that prompts you to create one. The behavior pool for the projection BO must be indicated
in the projection behavior definition with implementation in class ProjectionBehaviorPool
unique;. Once you add this to the projection behavior definition, you can create the behavior pool by
using the quick fix that is provided in the projection behavior definition.
The behavior pool is generated including two methods to implement the augmentation logic for
CREATE and UPDATE separately. To be able to reference a newly created instance in an UPDATE logic,
the implementation for CREATE and UPDATE must be done in one method.
CLASS lhc_Supplement DEFINITION INHERITING FROM cl_abap_behavior_handler.

PRIVATE SECTION.
METHODS augment FOR MODIFY
IMPORTING entities_create FOR CREATE Supplement
entities_update FOR UPDATE Supplement.
ENDCLASS.
CLASS lhc_Supplement IMPLEMENTATION.
METHOD augment.
ENDMETHOD.

ENDCLASS.
4. The augmentation implementation must handle all possible incoming request options for the behavior-
enabled field:
Incoming Request Augmentation for Supplement Text Entity
CREATE of a new supplement instance including new CREATE_BY_ASSOCIATION of a new supplement text
product name. instance.
 Note
The CBA uses the incoming %CID as %CID_REF to

reference the parent instance.
UPDATE of a supplement instance with already existing UPDATE of an already existing supplement text instance.
product name.
 Note
The link table of a READ_BY_ASSOCIATION is used

to check if entry for product name already exists.

858 PUBLIC Develop
Incoming Request Augmentation for Supplement Text Entity
UPDATE of a newly created supplement instance that has UPDATE of a supplement text instance that only exists in
not yet been saved to the database. the transactional buffer.
 Note
The %CID_REF of the incoming UPDATE refers to

the %CID of the possibly newly created supplement
instance.
UPDATE of an already existing supplement instance with- CREATE_BY_ASSOCIATION of a supplement text in-
out entry for product name. stance for already existing supplement instance.
Implement the logic for augmenting the operations CREATE and UPDATE:
1. Handle the importing parameters of CREATE and UPDATE separately.
2. Loop at the importing parameter for CREATE to check for incoming create requests. Fill the
relating table for modify augmenting requests and create an internal table with the values for the
CREATE_BY_ASSOCIATION of supplement text. Augment the incoming CREATE request with an EML
MODIFY AUGMENTING statement.
3. If the incoming request is an UPDATE, read the associated supplement text instances for the requested
supplement instances. Loop at all imported instances where the field SupplementDescription is to
be updated and handle the previously described cases for augmenting the incoming UPDATE request.
Depending on the use case an internal for CREATE BY ASSOCIATION or an internal table for UPDATE
must be filled. Augment the incoming UPDATE request with an EML MODIFY AUGMENTING statement
for the supplement and the supplement text entity.
 Expand the following code sample to view the source code of method augment.
 Sample Code
METHOD augment.

DATA: suppltext_for_new_suppl TYPE TABLE FOR CREATE /DMO/
I_Supplement\_SupplementText,
suppltext_for_existing_suppl TYPE TABLE FOR CREATE /DMO/
I_Supplement\_SupplementText,
supplementtext_update TYPE TABLE FOR UPDATE /DMO/
I_SupplementText.
DATA: relates_create TYPE abp_behv_relating_tab,
relates_update TYPE abp_behv_relating_tab,
relates_cba TYPE abp_behv_relating_tab.
DATA: suppl_text_tky_link TYPE STRUCTURE FOR READ LINK /DMO/
I_Supplement\\Supplement\_SupplementText,
suppl_text_tky LIKE suppl_text_tky_link-target.

"Handle create requests including SupplementDescription
LOOP AT entities_create INTO DATA(supplement_create).
"Count Table index for uniquely identifiably %cid on creating
supplementtext
APPEND sy-tabix TO relates_create.
"Direct the Supplement Create to the corresponding SupplementText

Create-By-Association using the current language
APPEND VALUE #( %cid_ref = supplement_create-%cid
%is_draft = supplement_create-%is_draft
%key-supplementid = supplement_create-%key-

Develop PUBLIC 859
SupplementID
CREATETEXTCID{ sy-tabix }|
%is_draft =
supplement_create-%is_draft
%key-supplementid =
supplement_create-SupplementID
languagecode =
sy-langu
description =
supplement_create-SupplementDescription
%control =
VALUE #( supplementid = if_abap_behv=>mk-on
languagecode = if_abap_behv=>mk-on
description = supplement_create-%control-SupplementDescription )
) )
) TO suppltext_for_new_suppl.
ENDLOOP.

ENTITY Supplement
FROM suppltext_for_new_suppl
RELATING TO entities_create BY relates_create.

IF entities_update IS NOT INITIAL.
READ ENTITIES OF /DMO/I_Supplement
ENTITY Supplement BY \_SupplementText
FROM CORRESPONDING #( entities_update )
LINK DATA(link)
FAILED DATA(link_failed).
"Handle update requests

LOOP AT entities_update INTO DATA(supplement_update) WHERE %control-
SupplementDescription = if_abap_behv=>mk-on.
CHECK NOT line_exists( link_failed-supplement[ KEY draft %tky =

CORRESPONDING #( supplement_update-%tky ) ] ).
DATA(tabix) = sy-tabix.
"Create variable for %tky for target entity instances
suppl_text_tky = CORRESPONDING #( supplement_update-%tky ) .
suppl_text_tky-LanguageCode = sy-langu.
"If a suppl_text with sy-langu already exists, perform an update.
Else perform a create-by-association.
IF line_exists( link[ KEY draft source-%tky = CORRESPONDING
#( supplement_update-%tky )
target-%tky = CORRESPONDING
#( suppl_text_tky ) ] ).
APPEND tabix TO relates_update.
APPEND VALUE #( %tky = suppl_text_tky
%cid_ref = supplement_update-%cid_ref
description = supplement_update-
SupplementDescription
%control = VALUE #( description =
supplement_update-%control-SupplementDescription )
) TO supplementtext_update.
"If suppl_text was created in the current LUW, perform an update
based on %cid
ELSEIF line_exists( suppltext_for_new_suppl[ KEY cid %is_draft =
supplement_update-%is_draft
%cid_ref =
supplement_update-%cid_ref ] ).
APPEND tabix TO relates_update.
APPEND VALUE #( %tky = suppl_text_tky
%cid_ref =
suppltext_for_new_suppl[ %is_draft = supplement_update-%is_draft

860 PUBLIC Develop
%cid_ref = supplement_update-%cid_ref ]-%target[ 1 ]-%cid
description = supplement_update-
SupplementDescription
%control = VALUE #( description =
supplement_update-%control-SupplementDescription )
) TO supplementtext_update.
"If suppl_text with sy-langu does not exist yet for
corresponding supplement
ELSE.
APPEND tabix TO relates_cba.
"Direct the Supplement Update to the corresponding
SupplementText Create-By-Association using the current language
APPEND VALUE #( %tky = CORRESPONDING #( supplement_update-
%tky )
%cid_ref = supplement_update-%cid_ref
UPDATETEXTCID{ tabix }|
languagecode = sy-langu
%is_draft =
suppl_text_tky-%is_draft
description =
supplement_update-SupplementDescription
%control = VALUE
#( languagecode = if_abap_behv=>mk-on
description = supplement_update-%control-SupplementDescription )
) )
) TO suppltext_for_existing_suppl.
ENDIF.
ENDLOOP.
ENDIF.
ENTITY SupplementText
UPDATE FROM supplementtext_update
RELATING TO entities_update BY relates_update
ENTITY Supplement
FROM suppltext_for_existing_suppl
RELATING TO entities_update BY relates_cba.

ENDMETHOD.
4.6.3 Using Type and Control Mapping

Whenever existing legacy code and data types are to be reused in behavior pools of business objects, then you
need to perform a mapping between CDS field names and types and corresponding legacy field names and
types.
Use Case
You can use this kind of mapping in applications that include unmanaged or managed business objects based
on CDS entities on the one hand, and legacy data types (ABAP Dictionary types) (and functionality) that are
generally older.
This is particularly significant for the unmanaged implementation type, which essentially represents a kind of
wrapper for existing legacy functionality.

Develop PUBLIC 861
Also with the managed implementation type, it can happen that, for example, the code for a determination or
validation already exists, but is based on "old" (legacy) data types.
When accessing the legacy code, the developer would normally have to use "corresponding with mapping" in
many places to map input derived types (type table for create, type table for action import)
to legacy types and vice versa to map legacy results to output derived types (type table for action
result, type table for read result, failed).
In addition, the types used to represent the control information also can differ significantly in the legacy code
and the current ABAP programming model:
In some legacy scenarios (especially the ones using BAPIs), in addition to the dictionary type directly
corresponding to the entity, there is another one that contains (ideally) the same fields as that type, but
these all have the type C(1) (like the control structures in BAPIs). This type has the same function as the
%CONTROL [page 155] structure in derived types, which indicates that fields in the main structure that are
accessed by an operation (update, read, and so on) Such type pairs are often used in BAPIs, for example
BAPIAD2VD/BAPIAD2VDX. The control data element is BAPIUPDATE with the type C(1).
The solution is now to introduce a central, declarative mapping within the behavior definition instead of many
individual corresponding statements. This improves maintainability of the application's source code.
Defining Type and Control Mapping in the Behavior Definition
A mapping sets the entity in relation to any other structured ABAP Dictionary type (legacy type). It is
introduced in the behavior definition for an unmanaged or managed implementation type with the keyword
mapping for.
Syntax: Mapping statement in the behavior definition

[implementation] unmanaged|managed [implementation in class ABAP_ClASS [unique]];


...
{
mapping for ...
...

}
Variant 1: Field Mapping
For details about the syntax for field mapping with corresponding, see CDS BDL - type mapping (ABAP -
Keyword Documentation)
The addition corresponding automatically maps fields of the same name to each another. The
corresponding fields of different names can be specified through explicitly listed field pairs.
The corresponding addition can also be omitted, which is not recommended in general, because then the
automatic mapping of fields with the same name is lost.

862 PUBLIC Develop
If no renaming of the fields is required, the short form can be used:
Syntax (short form):

mapping for LegacyType corresponding;

 Note
Mapping can be partial (legacy type contains fields that do not match any fields in CDS).
Variant 2: Field and Control Type Mapping

Using the following syntax, a mapping definition can be made simultaneously for a main field type LegacyType
and a control type ControlType:
Syntax: Field type and control mapping with corresponding

mapping for LegacyType control ControlType corresponding
{
EntityField1 = LegacyField1;
...
}

If no renaming of the fields is required, the short form can be used:
Syntax (short form):

mapping for LegacyType control ControlType corresponding;

Usually, it is assumed that the fields in the main and control type have the same name.
A different field mapping in { … } is specified as:
EntityField = LegacyField control ControlField;
 Note
For all control type fields, the type C(1) or X(1) is expected.
Using Type Mapping in ABAP
The reference to mappings that are defined in a behavior definition is done by some special variants of the
ABAP corresponding operator.
Syntax: Input mapping (entity type to legacy type)
data:

legacy_var type LegacyType,
entity_var type strucure|table for create|update|delete entity.
...

Develop PUBLIC 863
legacy_var = corresponding #( entity_var mapping from entity ).

The addition from entity assigns entity_var field-wise to data object legacy_var according to the
mapping definition for LegacyType in the behavior definition.
This mapping works fine if the type of entity_var is an input derived type, or the entity type itself, or the table
type of the entity.
Syntax: Output mapping (from legacy type to entity type)
data:

legacy_var type LegacyType,
entity_var type table for read result entity.
...
entity_var = corresponding #( legacy_var mapping to entity ).

The addition to entity assigns legacy_var field-wise to data object entity_var according to the mapping
definition for LegacyType in the behavior definition.
This mapping works fine if the type of entity_var is an output derived type, or the entity type itself, or the
table type of the entity.
Using Control Type Mapping in ABAP
Control mapping is about supporting the actual semantics of the %control fields: They indicate which of the
fields should be, for example, changed by an update or read by a read operation.
For the move between an input derived type (type table for create, type table for action
import) and a target structure, this means that only the fields for which the corresponding control field is set
should be moved.
Syntax: Using control

target = corresponding #( source using control ).

The structure or table source must be a derived type that also includes the %control structure.
For example, if the source has a field amount, then %control-amount decides whether to move the value
of amount to the corresponding field of target – only if the value of the corresponding control field is
non-initial.
By combining with the additional mapping from entity described above, also field mapping specified in the
behavior definition is effective:
Syntax: Using control with field mapping

target = corresponding #( source mapping from entity using
control ).


864 PUBLIC Develop
Conversely, there is an addition changing control that allows the %control fields of a derived type to
be set from a %control-less source structure - based on the criterion of whether the corresponding field is
non-initial.
Syntax: Changing control

target = corresponding #( source changing control ).

Related Information

4.6.4 Exposing Messages on the UI and Message Mapping
Messages
Messages offer an important way to guide and validate consumer and user actions, and help to avoid and
resolve problems. Thus, messages are important to communicate problems to a consumer or user. Well-
designed messages help to recognize, diagnose, and resolve issues. That's why it's important to always use
messages consistently and optimize the interaction as a whole. Consequently, errors and warnings that require
action should be clearly stated and described in a way that helps to resolve the issue quickly and efficiently. It’s
recommended to provide a message for each entry in the fail structure to provide additional information.
Example Business Object Structure [page 866]

This topic explains end-to-end how to receive and adapt messages from a different business object.
Related Information
Transition Messages [page 264]

Example Business Object Structure [page 866]
Creating a Message Exception Class [page 869]
Exposing Messages for a Sample Business Object with Draft Capabilities [page 875]

Develop PUBLIC 865
4.6.4.1 Example Business Object Structure
Example
The data model for the following message implementation examples is based on the data model for business
objects with draft capabilities, but was reduced to highlight the important points regarding messages. The
business object model for this example contains the two entities Travel and Booking. For more contextual
information about annotations and syntax, refer to Creating CDS View Entities [page 585]. This example
focuses on the relevant points for messages.
Data Definition: /DMO/I_Travel_Messages
The data source for the travel root view is the database table /DMO/A_TRAVEL_D. All fields from the database
 Expand the following code sample to view the source code Of /DMO/I_Travel_Messages.
 Sample Code
@EndUserText.label: 'Travel View Entity for Messages.'

define root view entity /DMO/I_Travel_Messages
as select from /dmo/a_travel_d
composition [0..*] of /DMO/I_BOOKING_Messages as _Booking
{ ///dmo/a_travel_d

866 PUBLIC Develop
//Associations
_Booking,
_Agency,
_Customer,
_Currency
}

Data Definition: /DMO/I_Booking_Messages
The data source for the booking view is the database table /DMO/A_BOOKING_D. All fields from the database
 Expand the following code sample to view the source code of /DMO/I_Booking_D.
 Sample Code
@EndUserText.label: 'Booking View Entity for Messages'

define view entity /DMO/I_Booking_Messages
as select from /dmo/a_booking_d
association to parent /DMO/I_Travel_Messages as _Travel
on $projection.TravelUUID = _Travel.TravelUUID

and
{ ///dmo/a_booking_d
key booking_uuid as BookingUUID,
parent_uuid as TravelUUID,
booking_id as BookingID,
carrier_id as AirlineID,

//Associations
_Travel,
_BookingSupplement,
_Customer,
_Carrier,
_Connection
}


Develop PUBLIC 867
Behavior Definition: /DMO/I_Travel_Messages
This data model focuses on illustrating how messages work in different contexts. Consequently, the behavior
definition uses a reduced function scope for both entities. Each entity implements an action and a validation to
illustrate state messages and transition message behavior for each of these cases.
Travel
The travel entity implements:
• Validation validateCustomer: Checks if the customer ID that is entered by the consumer is valid
• Action setToBooked: Changes the booking status from N(new) to B (booked)
Booking
The booking entity implements:
• Validation validateDates: Checks if the entered BookingDate is valid

• Determination validateBookingDate: Checks whether the selected booking date is between the
StartDate and EndDate of the parent travel entity.
 Expand the following code sample to view the source code of /DMO/I_Travel_Messages.
 Sample Code

managed;
with draft;
define behavior for /DMO/I_Travel_Messages alias Travel
implementation in class dmo_travel_messages_demo unique
persistent table /dmo/a_travel_d
draft table zfdtravelmessage
lock master
total etag LocalLastChangedAt
//authorization master ( instance )
{
create;
update;
delete;
association _Booking { create; with draft; }
validation validateCustomer on save { field CustomerID; }
action setToBooked result [1] $self;
{
validation booking~validateDates ;
determination booking~setBookingDate;
}
mapping for /dmo/a_travel_d
EndDate = end_date;

868 PUBLIC Develop
}
define behavior for /DMO/I_Booking_Messages_DEMO alias Booking
implementation in class DMO_i_booking_messages_demo unique
persistent table /dmo/a_booking_d
draft table zfdbookinmessage
{
update;
delete;
validation validateDates on save { field BookingDate; create; }
mapping for /dmo/a_booking_d
}

4.6.4.2 Exposing Messages on the UI
4.6.4.2.1 Creating a Message Exception Class
This topics explains end-to-end how to create a message-wrapper class using a specific implementation
example.
Context
You want to provide and expose messages on the UI. The procedure is identical for business objects of all
types, however the message behavior of state messages may vary if your business object doesn't have draft
capabilities. For more information about how state messages behave in different contexts, refer to State
Messages [page 268].
Fore more information about the example business object structure, refer to Example Business Object
Structure [page 866].

Develop PUBLIC 869
Procedure
1. Create your messages in a T100-message class as described in . This example

uses the following T100-messages from the message class /DMO/CM_TRAVEL_MESSAGES:
2. Create an ABAP-class as message-wrapper to wrap the T100-messages as message constants. This

wrapper-class takes care of formatting message variables in accordance with their data type, especially
date and time types. The date and time formatting is dervived from backend user settings. If front-
and backend user settings differ, messages always reflect the backend user settings. The wrapper-class
inherits from CX_STATIC_CHECK which takes care of the type formatting. For more information about
CX_STATIC_CHECK, refer to Exception Categories(ABAP Keyword Documentation). Furthermore, the class
implements the relevant message interfaces IF_ABAP_BEHV_MESSAGE, which implements the interfaces
IF_T100_DYN_MSG and IF_T100_MESSAGE. For more details about the interfaces, refer to Messages -
System Interfaces (ABAP Keyword Documentation).

CLASS DMO_MESSAGEWRAPPER DEFINITION
PUBLIC
INHERITING FROM CX_STATIC_CHECK
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
INTERFACES IF_ABAP_BEHV_MESSAGE .
PROTECTED SECTION.
PRIVATE SECTION.
ENDCLASS.
CLASS DMO_MESSAGEWRAPPER IMPLEMENTATION.
ENDCLASS.

3. Create variables for all fields of the data definition you want to pass as message variables with the
same type as the fields in the data definitions and add them as optinal importing parameters to the
message constructor. For this example, the fields travel_id, end_date, begin_date,flight_date,
Customer_ID and booking_id are relevant for the message texts. The variable types are derived from
the data definition the fields were contained in. The message severity can be set with the severity variable
severity TYPE if_abap_behv_message=>t_severity in the messagec constructor.

//Relevant fields from the data definitions
DATA:
mv_attr1 TYPE string,
mv_travel_id TYPE /dmo/travel_id,
mv_booking_id TYPE /dmo/booking_id,
mv_customer_id TYPE /dmo/customer_id,
mv_connection_id TYPE /dmo/connection-connection_id,
mv_begin_date TYPE /dmo/begin_date,
mv_end_date TYPE /dmo/end_date,
mv_booking_date TYPE /dmo/booking_date,
mv_flight_date TYPE /dmo/flight_date.

870 PUBLIC Develop
METHODS constructor
IMPORTING
textid LIKE if_t100_message=>t100key OPTIONAL
attr1 TYPE string OPTIONAL
previous LIKE previous OPTIONAL
customer_id TYPE /dmo/customer_id OPTIONAL
connection_id TYPE /dmo/connection-connection_id OPTIONAL
begin_date TYPE /dmo/begin_date OPTIONAL
end_date TYPE /dmo/end_date OPTIONAL
booking_date TYPE /dmo/booking_date OPTIONAL
flight_date TYPE /dmo/flight_date OPTIONAL

severity TYPE if_abap_behv_message=>t_severity OPTIONAL.
4. Implement the constructor and map the importing parameters to the variables. Set the severity and the
textID.

METHOD CONSTRUCTOR.
SUPER->CONSTRUCTOR( PREVIOUS = PREVIOUS ).
MV_ATTR1 = ATTR1.
MV_ATTR2 = ATTR2.
MV_ATTR3 = ATTR3.
MV_ATTR4 = ATTR4.
MV_TRAVEL_ID = TRAVEL_ID.
MV_BOOKING_ID = BOOKING_ID.
MV_CUSTOMER_ID = CUSTOMER_ID.
MV_CONNECTION_ID = CONNECTION_ID.
MV_BEGIN_DATE = BEGIN_DATE.
MV_END_DATE = END_DATE.
MV_BOOKING_DATE = BOOKING_DATE.
MV_FLIGHT_DATE = FLIGHT_DATE.
IF_ABAP_BEHV_MESSAGE~M_SEVERITY = SEVERITY.
CLEAR ME->TEXTID.
IF TEXTID IS INITIAL.
IF_T100_MESSAGE~T100KEY = IF_T100_MESSAGE=>DEFAULT_TEXTID.
ELSE.
IF_T100_MESSAGE~T100KEY = TEXTID.
ENDIF.
ENDMETHOD.

ENDCLASS.
5. Create message constant for each T100-message text you have created in the T100-message class.
A generic message constant consists of the following elements::

CONSTANTS:
GC_MSGID TYPE SYMSGID VALUE 'Message_Class',
BEGIN OF Message_Constant,
MSGID TYPE SYMSGID VALUE 'Message_Class',
MSGNO TYPE SYMSGNO VALUE 'Message_Number',
ATTR1 TYPE SCX_ATTRNAME VALUE 'Message_Variable',
END OF Message_Constant,

A message constant begins and end with the constant name. Ideally, the name reflects the message
content to make the message usage easier. MSGID TYPE SYMSGID has the message class assgined as

Develop PUBLIC 871
value and MSGNO TYPE SYMSGNO has the message number assigned as value. You can pass message
variables with the ATTR 1-4.
A specific implementation for message 001 ("Enter Customer ID for Travel&1.") with the message variable
TravelID is implemented analogously to the generic message constant implementation:

CONSTANTS:
GC_MSGID TYPE SYMSGID VALUE 'DMO_TRAVEL_MESSAGES',
BEGIN OF CUSTOMERID_NOT_INITIAL,
MSGID TYPE SYMSGID VALUE 'DMO_TRAVEL_MESSAGES',
MSGNO TYPE SYMSGNO VALUE '001',
ATTR1 TYPE SCX_ATTRNAME VALUE 'TRAVEL_ID',
ATTR2 TYPE SCX_ATTRNAME VALUE '',
END OF CUSTOMERID_NOT_INITIAL,

Results
You have created message-wrapper class for your T100-Messages. The following source code shows the
sample implementation of a message-wrapper.
 Expand the following code sample to view the source code of DMO_MESSAGEWRAPPER.
 Sample Code

CLASS DMO_MESSAGEWRAPPER DEFINITION
PUBLIC
INHERITING FROM CX_STATIC_CHECK
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
INTERFACES IF_ABAP_BEHV_MESSAGE .
CONSTANTS:
GC_MSGID TYPE SYMSGID VALUE 'DMO_TRAVEL_MESSAGES',
BEGIN OF CUSTOMER_ID_NOT_INITIAL,
END OF CUSTOMER_ID_NOT_INITIAL,
BEGIN OF CUSTOMERID_NOT_EXIST,
ATTR1 TYPE SCX_ATTRNAME VALUE 'Customer_id',
END OF CUSTOMERID_NOT_EXIST,
BEGIN OF BEGIN_DATE_MISSING,
END OF Begin_DATE_MISSING,
BEGIN OF END_DATE_MISSING,

872 PUBLIC Develop
END OF END_DATE_MISSING,
BEGIN OF END_DATE_BEF_BEGIN_DATE,
ATTR1 TYPE SCX_ATTRNAME VALUE 'BEGIN_DATE',
END OF END_DATE_BEF_BEGIN_DATE,
BEGIN OF BEGIN_DATE_WRONG,
ATTR1 TYPE SCX_ATTRNAME VALUE 'BEGIN_DATE',
END OF BEGIN_DATE_WRONG,
BEGIN OF AIRLINE_ID_IS_INITIAL,
ATTR1 TYPE SCX_ATTRNAME VALUE 'BOOKING_ID',
END OF AIRLINE_ID_IS_INITIAL,
BEGIN OF CONNECTION_ID_IS_INITIAL,
ATTR1 TYPE SCX_ATTRNAME VALUE 'BOOKING_ID',
END OF CONNECTION_ID_IS_INITIAL,
BEGIN OF FLIGHT_NOT_EXIST,
ATTR1 TYPE SCX_ATTRNAME VALUE 'FLIGHT_DATE',
END OF FLIGHT_NOT_EXIST,
BEGIN OF ACTION_SUCCESSFUL,
END OF ACTION_SUCCESSFUL,
BEGIN OF INCORRECT_BOOKING_DATE,
END OF INCORRECT_BOOKING_DATE.

Develop PUBLIC 873
DATA:
MV_ATTR1 TYPE STRING,
MV_TRAVEL_ID TYPE DMO_I_Travel_Messages_DEMO-travelUUID OPTIONAL,
MV_BOOKING_ID TYPE DMO_I_Booking_Messages_DEMO-BookingUUID OPTIONAL,
MV_CUSTOMER_ID TYPE /DMO/CUSTOMER_ID,
MV_CONNECTION_ID TYPE /DMO/CONNECTION-CONNECTION_ID,
MV_BEGIN_DATE TYPE /DMO/BEGIN_DATE,
MV_END_DATE TYPE /DMO/END_DATE,
MV_BOOKING_DATE TYPE /DMO/BOOKING_DATE,
MV_FLIGHT_DATE TYPE /DMO/FLIGHT_DATE.
METHODS CONSTRUCTOR
IMPORTING
TEXTID LIKE IF_T100_MESSAGE=>T100KEY OPTIONAL
ATTR1 TYPE STRING OPTIONAL
PREVIOUS LIKE PREVIOUS OPTIONAL
TRAVEL_ID TYPE DMO_I_Travel_Messages_DEMO-travelUUID OPTIONAL
BOOKING_ID TYPE DMO_I_Booking_Messages_DEMO-BookingUUID OPTIONAL
CUSTOMER_ID TYPE /DMO/CUSTOMER_ID OPTIONAL
CONNECTION_ID TYPE /DMO/CONNECTION-CONNECTION_ID OPTIONAL
BEGIN_DATE TYPE /DMO/BEGIN_DATE OPTIONAL
END_DATE TYPE /DMO/END_DATE OPTIONAL
BOOKING_DATE TYPE /DMO/BOOKING_DATE OPTIONAL
FLIGHT_DATE TYPE /DMO/FLIGHT_DATE OPTIONAL
SEVERITY TYPE IF_ABAP_BEHV_MESSAGE=>T_SEVERITY OPTIONAL.
PROTECTED SECTION.
PRIVATE SECTION.
ENDCLASS.
METHOD CONSTRUCTOR ##ADT_SUPPRESS_GENERATION.
SUPER->CONSTRUCTOR( PREVIOUS = PREVIOUS ).
MV_ATTR1 = ATTR1.
MV_ATTR2 = ATTR2.
MV_ATTR3 = ATTR3.
MV_ATTR4 = ATTR4.
MV_TRAVEL_ID = TRAVEL_ID.
MV_BOOKING_ID = BOOKING_ID.
MV_CUSTOMER_ID = CUSTOMER_ID.
MV_CONNECTION_ID = CONNECTION_ID.
MV_BEGIN_DATE = BEGIN_DATE.
MV_END_DATE = END_DATE.
MV_BOOKING_DATE = BOOKING_DATE.
MV_FLIGHT_DATE = FLIGHT_DATE.
IF_ABAP_BEHV_MESSAGE~M_SEVERITY = SEVERITY.
CLEAR ME->TEXTID.
IF TEXTID IS INITIAL.
IF_T100_MESSAGE~T100KEY = IF_T100_MESSAGE=>DEFAULT_TEXTID.
ELSE.
IF_T100_MESSAGE~T100KEY = TEXTID.
ENDIF.
ENDMETHOD.
ENDCLASS.


874 PUBLIC Develop
4.6.4.2.2 Exposing Messages for a Sample Business Object
with Draft Capabilities
This topic explains how to integrate messages in your behavior implementation.
Prerequisites
You’ve created a message-wrapper class for all of your T100-messages relevant for the business object. This
example uses the message texts and the message-wrapper class created in Creating a Message Exception
Class [page 869].
For more information about the example business object structure, refer to Example Business Object Structure
[page 866].
The implementation examples list the message implementation - and at the bottom of each section you can
find the complete source code for each method to see how the message implementation is integrated in the
context of the source code.
 Note
It’s strongly recommended to add all validations to the PREPARE action. Since validation return state
messages, the state messages are only rendered according to their properties when triggered during
the PREPARE and before the ACTIVATE. Even though validations are triggered a second time during the
ACTIVATE, the state message handling differs: Validation included in the PREPARE run on the draft instance
and render state messages as such, because no rollback is triggered if the validation fails. However, if a
validation fails later during the ACTIVATE, a rollback is triggered and all state messages triggered until this
point are converted to transition messages by the framework. For more information about the PREPARE ,
see Preparing Draft Instances for Activation [page 73].
Sample Implementation: validateCustomer (Travel)
This example shows the message implementation for validateCustomer of the Travel entity.
This validation checks whether a CustomerID entered by the user exists in the /DMO/CUSTOMER table. Since
the validation checks the consistency of business object state, it returns state messages in the reported
structure of the travel entity. To implement a state message, the component %state_area must be filled in
with a string. ValidateCustomer essentially checks for two conditions of which only one can be true at a
time - either the user entered a CustomerID that is unknown or the user didn't enter any value. Consequently,
both messages can have the same %state_area, so that only one invalidation statement is required at the
beginning of the implementation. The %state_area has the same name as the validation. The target field in
both cases is the field CustomerID. As the messages are returned after an entry in the failed structure, all
messages are categorized with the severity error.

Develop PUBLIC 875
 Note
It’s recommended to use the same %state_area within the implementation of a validation. If the
%state_area differs, each %state_area must be invalidated separately.

" Invalidate state messages
APPEND VALUE #( %tky = ls_travel-%tky
%state_area = 'VALIDATE_CUSTOMER' ) TO reported-
travel.
[...]
"Return state message when no CustomerID was entered
%msg = NEW dmo_messagewrapper(
textid =
dmo_messagewrapper=>customer_id_not_initial
error )
%element-customerid = if_abap_behv=>mk-on
[...]
"Return state message if incorrect CustomerID was entered
textid =
dmo_messagewrapper=>customerid_not_exist
severity =

 Expand the following code sample to view the source code of validateCustomer.
 Sample Code

METHOD validatecustomer.
READ ENTITIES OF dmo_i_travel_messages IN LOCAL MODE
ENTITY travel
FIELDS ( customerid )
RESULT DATA(lt_travel)
FAILED DATA(lt_failed).
failed = CORRESPONDING #( DEEP lt_failed ).
DATA lt_customer TYPE SORTED TABLE OF /dmo/customer WITH UNIQUE KEY
customer_id.
lt_customer = CORRESPONDING #( lt_travel DISCARDING DUPLICATES MAPPING
customer_id = customerid EXCEPT * ).
DELETE lt_customer WHERE customer_id IS INITIAL.
IF lt_customer IS NOT INITIAL.
SELECT FROM /dmo/customer FIELDS customer_id
FOR ALL ENTRIES IN @lt_customer
WHERE customer_id = @lt_customer-customer_id
INTO TABLE @DATA(lt_customer_db).
ENDIF.
" Raise message for non existing customer id
LOOP AT lt_travel INTO DATA(ls_travel).
" Invalidate state messages
%state_area = 'VALIDATE_CUSTOMER' ) TO reported-
travel.
IF ls_travel-customerid IS INITIAL.

876 PUBLIC Develop
APPEND VALUE #(
%tky = ls_travel-%tky ) TO failed-travel.
APPEND VALUE #(
%tky = ls_travel-%tky
textid =
dmo_messagewrapper=>customer_id_not_initial
severity =
ELSEIF ls_travel-customerid IS NOT INITIAL AND NOT
line_exists( lt_customer_db[ customer_id = ls_travel-customerid ] ).
APPEND VALUE #( %tky = ls_travel-%tky ) TO failed-travel.
" Message if customerID is unknown
textid =
dmo_messagewrapper=>customerid_not_exist
severity =

ENDIF.
Sample Implementation: setToBooked (Travel)
This example shows the message implementation for setToBooked of the Travel entity.
This action sets the overall_status field to B (booked). Usually, actions return transition messages,
because they trigger a change in the business object. Consequently, this action returns a transition message:
This message to confirm the successful transition of the overallStatus. The transition message is
categorized as success and it’s allocated to the reported-travel since it's semantically related to a request
triggered on this entity. The target field is overallStatus. For transitions messages the corresponding
operation must be specified in %op. In this case, the message belongs to the action setToBooked.

"Return transition message in case of successful request
APPEND VALUE #( %tky = result[ 1 ]-%tky
textid =
dmo_messagewrapper=>action_successful
success )
%element-overallstatus = if_abap_behv=>mk-on
%action-setToBooked = if_abap_behv=>mk-on

 Expand the following code sample to view the source code of setToBooked.
 Sample Code

" Modify travel instance
MODIFY ENTITIES OF z_fd_i_travel_messages_demo IN LOCAL MODE
ENTITY travel
UPDATE FIELDS ( overallstatus )
overallstatus = 'B' ) ) "Booked
FAILED failed.

Develop PUBLIC 877
" read changed data for action result
READ ENTITIES OF dmo_travel_messages IN LOCAL MODE
ENTITY travel ALL FIELDS WITH
RESULT DATA(lt_travel).
result = VALUE #( FOR travel IN lt_travel ( %tky = travel-%tky
*add success MESSAGE at the END of the action
APPEND VALUE #( %tky = result[ 1 ]-%tky
textid =
dmo_messagewrapper=>action_successful
success )
%element-overallstatus = if_abap_behv=>mk-on
%action-setToBooked = if_abap_behv=>mk-on

Sample Implementation: validateBookingDate (Booking)
This example shows the message implementation for validateBookingDate of the Booking entity.
The validation checks whether the selected booking date is between the StartDate and EndDate of the
parent travel entity. In this example, the validation is included in the determine action PREPARE, so that the
validation is triggered before the ACTIVATE. This validation returns a state message in case the selected1
BookingDate doesn't lie in between Start-and Enddate. The message has the severity error and the target field
BookingDate. Since the booking entity is a direct child of the travel entity, it’s required to fill in the %path
component with the path to the travel entity by mapping both draft instances. This state message is bound to
the REPORTED-booking structure.
 Note
If you have external numbering in your business object and pass the ID as a message variable, the
message-wrapper class doesn't take care of omitting leading zeros.

"Return state message when bookingdate is not in of selected time frame
APPEND VALUE #( %tky = <ls_booking>-%tky
%state_area = lv_state_area
%path = VALUE #( travel-%is_draft =
<ls_booking>-%is_draft
travel-traveluuid =
<ls_booking>-traveluuid )
textid =
dmo_messagewrapper=>incorrect_booking_date
travel_id = <ls_booking>-traveluuid
severity =
%element-bookingdate = if_abap_behv=>mk-on ) TO reported-
booking.

 Expand the following code sample to view the source code of validateDates.
 Sample Code

METHOD validateDates.

878 PUBLIC Develop
CHECK keys IS NOT INITIAL.
READ ENTITIES OF z_fd_i_travel_messages_demo IN LOCAL MODE
ENTITY booking
FIELDS ( bookinguuid traveluuid bookingid bookingdate )
RESULT DATA(lt_booking).
READ ENTITIES OF z_fd_i_travel_messages_demo IN LOCAL MODE
ENTITY booking BY \_travel
FIELDS ( traveluuid travelid begindate enddate )
WITH CORRESPONDING #( lt_booking )
RESULT DATA(lt_travel).
LOOP AT lt_booking ASSIGNING FIELD-SYMBOL(<ls_booking>) WHERE
bookingdate IS NOT INITIAL.
ASSIGN lt_travel[ KEY entity COMPONENTS traveluuid = <ls_booking>-
traveluuid ] TO FIELD-SYMBOL(<ls_travel>).
IF <ls_travel>-begindate IS NOT INITIAL AND
<ls_travel>-enddate IS NOT INITIAL.
DATA(lv_state_area) = 'VAL_BOOKING_DATE'.
IF <ls_booking>-%tky-%is_draft = if_abap_behv=>mk-on.
%state_area = lv_state_area ) TO reported-
booking.
ENDIF.
IF <ls_booking>-bookingdate < <ls_travel>-begindate OR
<ls_booking>-bookingdate > <ls_travel>-enddate.
APPEND VALUE #( %tky = <ls_booking>-%tky ) TO
failed-booking.
%state_area = lv_state_area
%path = VALUE #( travel-%is_draft
= <ls_booking>-%is_draft
travel-traveluuid
= <ls_booking>-traveluuid )
textid =
dmo_messagewrapper=>incorrect_booking_date
travel_id =
<ls_booking>-traveluuid
severity =
%element-bookingdate = if_abap_behv=>mk-on ) TO
reported-booking.
ENDIF.
ENDIF.
ENDLOOP.
ENDMETHOD.

Sample Implementation: Messages in Global Context
Messages that are returned from global authoriation or global feature control methods don't belong to a
specific instance, because global methods are called before an instance is created. That's why global methods
always return entity bound transition messages. For more information, refer to Transition Messages [page
264].
As global authorization is independent of the state of the entity and just checks the authorization of the user
that has executed the request, the global authorization handler is used to forbid certain operations for certain
user groups in general. A typical use case is to only allow specific user groups to create new instances.
For more information about authorization, refer to Authorization Control [page 80].

Develop PUBLIC 879
4.6.4.3 Mapping Messages Between Business Objects
This topic explains end-to-end how to receive and adapt messages from a different business object.
Message Mapping
A business object determination may trigger an operation of another business object that then returns
messages. To receive and adapt the messages from a foreign business object, you register the foreign
business object to extend the reported structure of the receiving business object. You can adapt the received
messages to your requirements and the messages are then mapped during the SAVE sequence.
1. To handle messages of other business objects, you reference the foreign business object as foreign entity
in the behavior definition of your business object with the following syntax:
 Sample Code

implementation {unmanaged | managed | abstract};
[with draft];
foreign entity EntityName alias Alias;

The foreign entity reference requires a redefinition of the MAP_MESSAGES method in the behavior
implementation of the root entity. This method has changing parameter reported of type response
for reported late. The reported structure contains all entities of the source business object and
all entities of the referenced foreign business object.
 Example
In the following example, a Travel business object with the child entity Booking references the foreign
business object /DMO/I_Flight_M in the behavior definition:
 Sample Code

implementation managed;
with draft;
foreign entity /DMO/I_Flight_M alias Flight;
define behavior for /DMO/I_Travel alias travel
implementation in class /DMO/TRAVEL_MESSAGES unique
...

This triggers the redefinition of the MAP_MESSAGES method in the behavior definition of the root view
if not specified otherwise in the behavior definition - in this example, the behavior implementation
of travel. The saver class inherits from the CL_ABAP_BEHAVIOR_SAVER class. For more information
about CL_ABAP_BEHAVIOR_SAVER, refer to Saver Classes [page 149]. :
 Sample Code
CLASS LSC_DMO/I_Travel DEFINITION INHERITING FROM

CL_ABAP_BEHAVIOR_SAVER.

PROTECTED SECTION.
METHODS MAP_MESSAGES REDEFINITION.
ENDCLASS.

880 PUBLIC Develop
CLASS LSC_DMO/I_Travel IMPLEMENTATION.
METHOD MAP_MESSAGES.
//Message mapping implementation
ENDMETHOD.

ENDCLASS.
The reported structure is extended with the entities of the referenced foreign business object. In this
example, the reported structure is extended with the flight entity:
This gives you access to the messages that are returned in the reported structure of the flight
entity.
2. You can map the returned messages to your business object according to your requirements, for example
by:
• Mapping messages to your business object instance key (%tky)
• Adapting the path for messages on child instances (%path)
• Adapting the targets of your messages (%element)
• Omitting messages that do not fit certain criteria (for example: Success messages are omitted)

Develop PUBLIC 881
4.6.5 Working with Large Objects
Context
You can enable your RAP application for maintaining large objects (LOBs). By doing so, you provide end users
the option to incorporate external binary files or text files when editing entity instances.
The following video shows how an end user performs an image upload using a RAP application, which has been
enabled for the maintenance of LOBs.
Adding Image Attachments on a Fiori Elements UI
Data Model Enhancements
Large objects are modeled by means of the following fields:
• Attachment
• Mimetype
• Filename
The field Attachment contains the LOB itself and is technically bound to the field Mimetype, which represents
the content type of the attachment. No attachment can exist without its mimetype and vice versa. The
filename is an optional field.

882 PUBLIC Develop
When consuming large objects via a Fiori Elements UI, the values for the fields Mimetype and Filename
are derived from the field Attachment by the framework based on the maintained CDS annotations, so UI
consumers only need to interact with the field Attachment to maintain large objects.
Example Scenario
We use an example from the ABAP Flight Reference Scenario to show how to enable the maintenance of
large objects in a business object. In this example, we work with the business object from the package /DMO/
FLIGHT_REUSE_AGENCY that can be used for the administration of agency master data like agency names
and addresses. This guide shows how to enable your existing business object for the maintenance of file
attachments such as agency flyers.
Prerequisites
To be able to follow the instructions of this guide and test the result of your enhancements, your business
object should meet the following requirements:
• Your business object is create- and update-enabled.

• Your business object contains a projection layer.
• The projection layer has a metadata extension for providing CDS annotations .
• Your business object is exposed as an OData UI service.
Procedure
1. In your active and draft database tables, add the following fields for the large object:
attachment: /dmo/attachment;

mimetype: /dmo/mime_type;

filename: /dmo/filename;
The fields are typed with the corresponding base types from the /dmo/ domain. Whereas the base
type /dmo/attachment uses the data type rawstring, /dmo/mime_type and /dmo/filename use the
data type char128.
2. In the CDS view /DMO/I_Agency, add the fields defined for the database tables, define field
aliases and use CDS annotations to semantically relate the fields to each other. The annotation
contentDispositionPreference can be used to define whether, depending on the browser settings,
the file attachment is either displayed in the browser (setting #INLINE) or downloaded when selected
(option #ATTACHMENT). Use the CDS annotation @Semantics.mimeType: true to define the field
MimeType as such.
@Semantics.largeObject:

{ mimeType: 'MimeType',
fileName: 'Filename',
contentDispositionPreference: #INLINE }
Agency.attachment as Attachment,
@Semantics.mimeType: true
Agency.mime_type as MimeType,

Agency.filename as Filename
3. In the base CDS view /DMO/R_AGENCYTP, add the fields Attachment, MimeType and Filename from the
CDS view /DMO/I_Agency.

Develop PUBLIC 883
4. Also add the fields to the CDS projection views /DMO/C_AgencyTP and /DMO/I_AgencyTP.
5. In the metadata extension for the CDS projection view /DMO/C_AgencyTP, you can set the header
information to be displayed on the object page. In this example scenario, the content of the Attachment
field is displayed as an avatar in the header, in case the file attachment is an image. This is achieved by
providing the UI annotation imageUrl: 'Attachment' in the title section.
@UI: { headerInfo: {

typeName: 'Agency',
typeNamePlural: 'Agencies',
title: { type: #STANDARD, value: 'Name' },
imageUrl: 'Attachment',
description: { type: #STANDARD, value: 'AgencyID' } },
presentationVariant: [{
sortOrder: [{ by: 'AgencyID', direction: #ASC }],

visualizations: [{type: #AS_LINEITEM}] }] }
6. Additionally, use the CDS annotation @UI.hidden: true for the fields Mimetype and Filename to
ensure that only the field Attachment is displayed for the large object on the Fiori Elements UI. As
mentioned, a UI consumer only needs to interact with the field Attachment to maintain large objects, the
value handling for the fields Mimetype and Filename is taken care of by the framework.
@UI:

{ fieldGroup: [ { position: 100, qualifier: 'General_FG' } ],
identification: [ { position: 100, label: 'Attachment' } ] }
Attachment;
@UI.hidden: true
MimeType;
@UI.hidden: true

Filename;
4.6.6 Creating RAP Business Events
This topic explains how you can use events in a RAP BO to enable asynchronous communication between the
RAP BO as event provider and an event consumer, such as an application in a cross-system landscape.
Use Case
You can use events to send messages when the state of a business object has changed and you want to
inform consumers about the change. Events trigger the messaging framework that informs consumers. In a
cross-system or cross-product set up, the Enterprise Messaging running on SAP BTP acts as a messaging
broker between the RAP BO as event provider and the consuming application. In this example the RAP BO acts
as event provider, so an outbound communication arrangement is required to set up the connection between
your system and the SAP Event Mesh.
For more information about events, see Business Events [page 135].

884 PUBLIC Develop
Prerequisites
• You have set up a communication arrangement for your product and configured the SAP Event Mesh as
required. For more information, see SAP Event Mesh.
• For SAP S/4HANA Cloud, see Communication Management.
Procedure
The following example is based on the extensibility data model as described in Data Modeling and Behavior
[page 12]. In this case, the event is raised in a behavior extension of the original Agency RAP BO.
You want to define an event that is raised every time a new review is created in order to inform the respective
agency. Events have to be triggered once the point of no return has passed and the business process is
finished, which is why the event is raised with an additional save in the late save phase . This ensures that the
data will be saved to the database and that the state change of the BO is final. An event itself is defined with the
key word event in the behavior definition and can be defined with or without parameters. For this use case, a
parameter is defined using an abstract entity that transmits an email address and the text to inform the agency
via email. The raising of the event is implemented in the behavior pool within an additional save.
The communication arrangement enables the communication between the system and the Enterprise
Messaging instance, from where an application can consume the event. In this example, the event consumption
itself requires an inbound communication arrangement that connects the respective Mesh instance with the
target system.
1. Create the abstract entity /DMO/ZZ_D_AgencyReviewCreated and define the required data types. The
variable EMailAddress is defined as strg(256) and contains the email address of the respective
Agency. The ReviewID contains the information about the review that triggered the event.
@EndUserText.label: 'Agency Review Infos for create event'

define abstract entity /DMO/ZZ_D_AgencyReviewCreated
{
ReviewID : /dmo/zz_review_id;
Rating : /dmo/zz_rating;
FreeTextComment : /dmo/zz_free_text_comment;
EMailAddress : /dmo/email_address;
}

For details about modeling of parameters in RAP, see Modeling Parameters for Non-Standard Operations
[page 887].
2. Define the event in the behavior definition, with the keyword event. The event in this example is
named /DMO/AgencyReviewCreated and receives the /DMO/ZZ_D_AgencyReviewCreated as an input
parameter. The event is defined as part of a behavior extension of the original Agency BO.

extend behavior for /DMO/Agency
{
event /DMO/AgencyReviewCreated parameter /DMO/ZZ_D_AgencyReviewCreated;

}

Develop PUBLIC 885
3. Define the additional save for the BO entity for which you want to raise the event. In this example, the
event is raised for the extension node /DMO/ZZ_R_Agency_ReviewTP, and so with additional save
is added to the header of the entity definition:

define behavior for /DMO/ZZ_R_AGENCY_REVIEWTP alias /DMO/ZZ_Review using /DMO/
ZZ_I_AGENCY_REVIEWTP
persistent table /DMO/ZZ_AGN_REVA
draft table /DMO/ZZ_AGN_REVD
lock dependent
authorization dependent
late numbering
{
...

}
4. Implement the raising of the event in the save_modified method in the behavior pool.
This method checks whether a review was actually created by checking that create-/dmo/zz_review
isn't empty. The READ returns the root node agency instance for which the review was created. The
emailaddress information is the email address to which the email will be sent after the event has been
triggered. Then the event is raised with RAISE EVENT on the RAP BO interface /DMO/I_AgencyTP that
was extended with the event /DMO/AgencyReviewCreated. In the last step, the instance key and the
parameter values for the event are filled.
For general information about the additional save, see SAVE [page 231].

IF create-/dmo/zz_review IS NOT INITIAL.
READ ENTITIES OF /dmo/i_agencytp IN LOCAL MODE
ENTITY /dmo/agency
FIELDS ( emailaddress ) WITH CORRESPONDING #( create-/dmo/
zz_review )
RESULT DATA(agencies).
RAISE ENTITY EVENT /dmo/i_agencytp~/dmo/agencyreviewcreated
FROM VALUE #(
FOR review IN create-/dmo/zz_review (
agencyid = review-agencyid
reviewid = review-reviewid
rating = review-rating
freetextcomment = review-freetextcomment
emailaddress = agencies[ KEY entity agencyid = review-
agencyid ]-emailaddress
)
).
ENDIF.

ENDMETHOD.
5. Create an Event Binding in ADT. The event binding represents the design time definition of the event and
maps the event defined in a RAP BO to a namespace, a business object and a business object operation
like modify.

886 PUBLIC Develop
4.6.7 Modeling Parameters for Non-Standard Operations
This topic explains how you model parameters and use their representations in ABAP.
Usage of Parameters
Parameters in RAP are understood as input or output parameters to transmit values that are not inherently
part of the BO data model. You can use parameters for non-standard operations (actions, functions, business
events) to request extra information values from the operation consumer in input parameters. This information
must be provided by the operation consumer, so that the operation can use the provided values for its
calculations. In case of actions and functions, parameters can also be used to return results. This is realized as
output parameters. When working with business events, parameters are needed to pass the relevant values to
perform the event.
Depending on the use case, you can model flat or deep parameters for your non-standard operation. With
flat parameters, scalar values or flat structures are handed over. With deep parameters you can use nested
structure- or table-typed elements as parameter values.
OData exposure of operation parameters that are modeled as a composition hierarchy of abstract entities
(deep parameters) is only possible with OData V4.
For more information about actions, see Actions [page 101]. An example for a parameter action is given in
Implementing Actions for the Travel Entity [page 596].
For more information about functions, see Functions [page 111].
For more information about business events, see Business Events [page 135]. An example for the parameter
usage in business events is given in Creating RAP Business Events [page 884].
Modeling Parameters
The values for parameters must be typed properly. Since parameters are not described in the BO data model,
they don't need a database object to define their data model. The typing is done in a CDS abstract entity, which
is defined in a CDS data definition.
For more information about abstract entities, see ABAP CDS - Abstract Entities (ABAP- Keyword
Documentation).
Flat Parameters
Flat parameters are parameters that do not reflect a hierarchical structure. They are defined in one abstract
entity. Each value of the parameter must be typed properly as an element in the abstract entity. The
implementation of the non-standard action then imports a flat structure with which you can work as a regular
flat ABAP structure.
The definition of a non-standard operation with a flat parameter does not include the keyword deep.

Develop PUBLIC 887
 Example
Action Definition with Flat Parameter
*flat input parameter (flat structure)

action MyAction parameter /dmo/a_flat_param
*flat output parameter (nested structure)

action MyAction result [1] /dmo/a_flat_param
Flat Parameter Modeling in CDS and its Representation in ABAP
Deep Parameters
Deep parameters are parameters that reflect a hierarchical structure, meaning the parameter contains
elements that are in a parent-child relationship. They are defined in a composition hierarchy of abstract
entities. The hierarchy is represented in ABAP as nested structures for compositions with cardinality [0..1]
or [1]. It is represented as nested tables for compositions with cardinality [0..*] or [1..*].
Like in a database-represented data model, the compositional relationship must be declared in each abstract
entity with the keywords composition or association to parent to express their relationship to other
composition components. In addition, an abstract behavior definition, that includes the composition hierarchy
of abstract entities must be defined to construct the hierarchical derived type for the abstract entity. Each
associated abstract entity must be included in the behavior definition, as well as the related association.
Beginning at the root entity, a type derived from the behavior definition structure contains all entity fields, plus
a component for every composition. For a composition with cardinality [0..1] or [1], this component is a
structure; otherwise with cardinality [0..*] or [1..*], the component is a table. The keyword to define such
an abstract behavior definition as hierarchy model is with hierarchy. For more information, see CDS BDL -
CDS Abstract Behavior Definitions (ABAP- Keyword Documentation).
The definition of a non-standard operation with a deep parameter must include the keyword deep or deep
table for input parameters. Output parameters of actions or functions declare their structure or table type via
the cardinality. Deep result parameters with cardinality [1] represent a structure, with cardinality [1..*] they
represent a table in ABAP.
 Example
Action Definition with Deep Parameter
*deep input parameter (nested structure)

action MyAction deep parameter /dmo/a_deep_param_root
*deep input parameter (nested table)
action MyAction deep table parameter /dmo/a_deep_param_root

888 PUBLIC Develop
*deep output parameter (nested structure)
action MyAction deep result [1] /dmo/a_deep_param_root
*deep output parameter (nested table)

action MyAction deep result [1..*] /dmo/a_deep_param_root
Deep Parameter Modeling in CDS and its Representation in ABAP
You can use an abstract entity model for different parameters of different non-standard operations, as long as
the derived types match.
 Caution
You cannot use the same abstract entity model once as flat parameter and once as deep (table) parameter
in the same service. The derived types of such parameters would not match and the representation in
ABAP would be unclear. An error message in the service binding prevents such usage.
The representation of a parameter as flat or deep parameter depends on its definition in the non-standard
operation. If the keyword deep or deep table is not used before the parameter, the parameter is represented
as a flat parameter even if the abstract entities are modeled as a composition hierarchy.

Develop PUBLIC 889
 Remember
A parameter is only represented as hierarchical structure in ABAP if it is explicitly defined as deep in the
non-standard operation. For example, the definition of an action with a deep parameter must look like this
in the behavior definition:
action myAction deep parameter myParam
The definition of an action with a deep table parameter must look like this:
action myAction deep table parameter myParam
Exposure and Consumption of Operations with Parameters in RAP Services
OData V2 only allows non-standard operations with flat parameters. The service binding shows an error
message if a non-standard operation with a deep parameter is included in the service.
Operations with deep parameters in RAP can't be consumed with standard Fiori Elements UIs as they can't
represent hierarchical structures by default. For the consumption with EML or via Web APIs, a nested structure
or nested tables must be build with ABAP and passed to the operation in case of deep parameters.
4.7 Develop Common Capabilities
This chapter outlines how to develop individual capabilities both for business objects and for queries.
Working with Text Elements [page 891]

This section describes how to provide related text for a CDS view element in business service based on
the ABAP RESTful Programming Model.
Enabling Text and Fuzzy Searches in SAP Fiori Apps [page 897]
The descriptions in this topic refer to the range of functions for text and fuzzy searches that are
provided in the context of SAP HANA.
Using Aggregate Data in SAP Fiori Apps [page 901]

This topic explains how you can provide aggregate data for your SAP Fiori application. The available
aggregate functions operations are sum, minimum, maximum, and average. Alongside this, the
framework also provides options for counting.
Using Virtual Elements in CDS Projection Views [page 910]

With virtual elements, you define additional CDS elements that are not persisted on the database, but
calculated during runtime using ABAP classes that implement the virtual element interface.

890 PUBLIC Develop
4.7.1 Working with Text Elements
This section describes how to provide related text for a CDS view element in business service based on the
ABAP RESTful Programming Model.
Text elements are used to make technical names consumable for end users. Instead of only displaying an ID
element, or a technical name, the corresponding description is shown in combination with the ID elements on a
Fiori UI.
ID elements are needed to uniquely identify real-life artifacts in a technical environment as readable names
might not be unique, or are distinct for different languages or might change at some point or another. However,
these technical names are hard to work with for end user
Examples are
• product, company, or customer names

• descriptions
 Example
The product ID for supplements that can be booked for a flight are, for example, BV-0008 or ML-0027.
These technical names are useful for uniquely identifying the products, but are not easy to remember or
work with by end users. It is helpful if the readable text is displayed along with the identifier element, as can
be seen in the following illustration of a travel app.
Contents
You have different options to provide text for CDS view elements:
• Providing Text by Text Elements in the Same Entity [page 892]

Use this option if the identifier element and the text element are part of the same entity. You can establish a
direct link between the two elements.
• Getting Text Through Text Associations [page 893]
Use this option if the identifier element and the text element are not part of the same entity, or if the text
element is language-dependent and shall be displayed in the system log-on language in scenarios without
projection layer.
• Getting Language-Dependent Text in Projection Views [page 895]
Use this option if you are working with a projection layer.
 Note
You cannot combine text associations with projection scenarios.
• Editing Language-Dependent Fields [page 854]

Use this option if you want to enable editing for the denormalized text field.

Develop PUBLIC 891
4.7.1.1 Providing Text by Text Elements in the Same Entity
Language independent text elements can be maintained in the same entity as the identifier element.
Within the context of CDS views, the text elements establish the link between identifier elements (code values)
of the view and its descriptive language-independent texts. For example, you can define a link between a
company code and the (descriptive) company name, or between currency code and the currency name if
these elements are part of the one CDS view. These kinds of descriptive texts are language-independent. That
means, they do not contain text that is to be translated.
Relevant Annotation
Annotation Effect
@ObjectModel.text.element[] Establishes the link between the annotated element (that

defines an identifier element) and its descriptive language-
independent texts
 Note
The usage of this annotation excludes the usage of

@ObjectModel.text.association in the same
CDS entity. .
More on this: ObjectModel Annotations [page 1207]
 Note
Runtime Behavior: In scenarios with exposure via OData, only the first text element listed in the
annotation array will be handled as a descriptive text of the annotated field.
Example
In the listing below, the CDS view /DMO/I_SupplementText defines the fields Description that serves as
language-independent descriptions for the view field SupplementID.
define view /DMO/I_SupplementText

as select from /dmo/suppl_text as SupplementText
{
@ObjectModel.text.element: ['Description']
key SupplementText.supplement_id as SupplementID,
...
SupplementText.description as Description
….
}

Related Information
Getting Text Through Text Associations [page 893]

Getting Language-Dependent Text in Projection Views [page 895]

892 PUBLIC Develop
4.7.1.2 Getting Text Through Text Associations
Context
Using the CDS text association, you can define the relationship between an element (field) and its
corresponding texts or descriptions. The texts are usually language-dependent and are displayed in the end
user's language. If you annotate an element with a text association (as described below), the associated text
or description field is added as a field to the referencing entity. At runtime, this field is read from the database
and filtered by the logon language of the OData consumer automatically. It is not necessary to use session
properties or view parameters in your CDS view.
 Note
In scenarios, in which you use projection views, getting text through text associations is not supported.
To retrieve texts by direct use of text associations, proceed as follows:
Procedure
1. Create a data definition with a CDS view that serves as text provider
The following annotations are required at element level in the text provider view to annotate the language
key element and the text elements of the view’s element list:
Annotation and Values Effect
@Semantics.language: true The annotated element identifies the language field.
@Semantics.text: true Identifies view elements as text elements (fields pointing to a textual descrip-
tion)
 Note
In general, you can annotate more than one view field as a text field. How-
ever, only the first annotated field will be considered in the text consumer
view for OData exposure.
More on this: Semantics Annotations [page 1247]
2. Create a text association from your consumer CDS view to the text provider view .
The following CDS annotation is relevant when creating text associations:

Develop PUBLIC 893
@ObjectModel.text.associa Name of an association with a text view that provides descriptive texts for
tion: the annotated element. In other words: the annotation indicates that the
'<_AssocToTextProvider>' description for the annotated element is available using the text association
<_AssocToTextProvider>.
More on this: ObjectModel Annotations [page 1207]
The view /DMO/I_BookSuppl_T serves as a consumer for the text provider view /DMO/I_SupplText_T.
For this purpose, the association _SupplementText with the text provider view as target is defined. To
indicate the field for which a text should be made available through the association _SupplementText,
the annotation @ObjectModel.text.association is added. Note that only the first text element
(Description) from the text provider, which is annotated with @Semantics.text: true, will be
considered for OData exposure. In Fiori Elements apps, the supplement ID will then be displayed together
with the long text in description of the text provider view.
Text Provider View /DMO/I_SupplText_T
define view /DMO/I_SupplText_T as select from /dmo/suppl_text as

SupplementText

{
key SupplementText.language_code as LanguageCode,
SupplementText.alt_Description as AlternativeDescription

}
Text Consuming View /DMO/I_BookSuppl_T
define root view /DMO/I_BookSuppl_T as select from /dmo/book_suppl as

BookingSupplement

association [1..*] to /DMO/I_SupplText_T as _SupplementText on
{
key travel_id,
key booking_id,
@ObjectModel.text.association: '_SupplementText'
supplement_id,
/* Associations */
_SupplementText

}
Related Information
Providing Text by Text Elements in the Same Entity [page 892]

Getting Language-Dependent Text in Projection Views [page 895]

894 PUBLIC Develop
4.7.1.3 Getting Language-Dependent Text in Projection
Views
The denormalization of language-dependent text in projection views is done via the keyword localized
for the text elements, which are included in the projection view and referenced with the annotation
@ObjectModel.text.element: ['<text_element>'].
Context
You have a text provider view, in which text for unreadable elements is maintained. To get the text from there
you do not need any preparation in the text provider view.
To establish a connection to this text provider view, the projected view must have an association to the text
provider view.
 Note
To use the denormalization in projection views, you must not use the indicator for text associations
@ObjectModel.text.association: '<text_association> in the projected view.
You can then include the text element via the association in the projection view. The relationship
between identifier elements and the respective text is defined in the projection view via the annotation
@ObjectModel.text.element: ['<text_element>'], see CDS Projection View [page 201]. If the
keyword localized is used, the text in the system log-on language is drawn.
The following diagram illustrates the modeling of text denormalization in projection views.

Develop PUBLIC 895
Prerequisites
• The text provider view has a key element indicating the language of the text.
• The projected CDS view has an association to the text provider view, but does not use the annotation
ObjectModel.text.association.
Procedure
The example code snippets are taken from the ABAP Flight Scenario, which can be downloaded from GitHub,
see ABAP Flight Reference Scenario [page 309].
1. Include the text element from the text provider view into the projection view.
2. Annotate the element in the projection view, for which you want to provide the text with
@ObjectModel.text.element: [<text_element>] and reference the text element.
3. To get language-dependent texts use the keyword localized on the text element.
 Sample Code
//Text Provider View

//The text provider view selects from a database table, in which the
description texts in different languages are stored.
define view entity /DMO/I_SupplementText
as select from /dmo/suppl_text as SupplementText
{
@ObjectModel.text.element: ['Description']
key SupplementText.language_code as LanguageCode,
}
Projected View
define view entity /DMO/I_BookSuppl_M
as select from /dmo/booksuppl_m as BookingSupplement
association to parent /DMO/I_Booking_M as _Booking on
$projection.travel_id = _Booking.travel_id
and
$projection.booking_id = _Booking.booking_id
...
{
key travel_id,
key booking_id,
supplement_id,
...
_SupplementText
}
//Projection View
//The projection view denormalizes the supplement description and filters the
relevant values based on the requested language.It depends on the language
configuration of your cloud system, which language is allowed.
define view entity /DMO/C_BookSuppl_Processor_M

896 PUBLIC Develop
as projection on /DMO/I_BookSuppl_M
{
key booking_supplement_id as BookingSupplementID,
...
_SupplementText
}

If you create a UI service for this example, you can check the results when sending the request in different
languages, given that texts for different languages are provided on the database table.
Supplement Descriptions in English and German
Related Information
Getting Text Through Text Associations [page 893]

Providing Text by Text Elements in the Same Entity [page 892]
4.7.2 Enabling Text and Fuzzy Searches in SAP Fiori Apps
The descriptions in this topic refer to the range of functions for text and fuzzy searches that are provided in the
context of SAP HANA.
Text and Fuzzy Searches
The full text searching (or just text search) provides you with the capability to identify natural language terms
that satisfy a query and, optionally, to sort them by relevance (ranking) to the query. The most common type

Develop PUBLIC 897
of search is to find texts that contain the term specified and return them in the order of their similarity to these
terms.
Fuzzy search is a fast and fault-tolerant search feature of SAP HANA. The basic concept behind the fault-
tolerant search is that a database query returns records even if the search term (user input) contains
additional or missing characters, or even spelling errors. Fuzzy search can be used in various applications
-- for example, to trigger a fault-tolerant search in a structured database content, like a search for a product
called 'coffe krisp biscuit' and you find 'Toffee Crisp Biscuits'.
Providing Freestyle Search Capabilities in SAP Fiori UI screen
Within the context of the ABAP RESTful programming model, you only need to enable the text and fuzzy search
functionality in your data model definitions. For this purpose, you implement it in designated CDS views using
appropriate text and fuzzy search annotations (listed below).
 Note
As an application developer however, you must ensure that your CDS views are suitable for text and fuzzy
search enabling. For more information take a look at the corresponding topics in the SAP HANA Search
Developer Guide .
Annotations for Text- and Fuzzy Search
As the name suggests, search annotations enable the search feature on the CDS view elements.
First of all, you need the following CDS annotation at the view level:
Annotation and Value Effect
@Search.searchable: true/ Defines whether a CDS view is generally relevant for search scenarios. This anno-
false tation provides a general switch and a means to quickly detect whether a view
is search-relevant or not. Set to value true in order to enable search support by
means of @Search annotations. Here, at least one view field must be defined as
@defaultSearchElement at element level.
The annotations (required) at the element level are:

898 PUBLIC Develop
@Search.defaultSearchEleme Specifies that the annotated element is to be considered in a full-text search

nt: true/false
 Note
At least one element has to be defined for the default full-text search. Search-
ing in views without default full-text search elements is not supported!
All view elements that are annotated for the default search define the search
scope. (The search will be performed on all elements that have this annotation.).
 Caution
Such a search must not operate on all elements – for performance reasons
and because not all elements qualify for this kind of access.
@Search.fuzzinessThreshold This annotation specifies the least level of fuzziness the element has to have in
: <value> order to be considered in a fuzzy search at all.
The <value> defines the threshold for a fuzzy search (how fuzzy scores are
calculated when comparing two strings or two terms).
Possible values are: 0..1 The default value is 1. The fuzzy search algorithm
calculates a fuzzy score for each string comparison. The higher the score, the
more similar the strings are. A score of 1.0 means the strings are identical. A
score of 0.0 means the strings have nothing in common.
@Search.ranking: <value> This annotation specifies how relevant the values of an element (view field) are
for ranking, should the freestyle search terms match the element’s value.
The ranking can have the following values:
• HIGH - The element is of high relevance; typically, this is useful for IDs and
their descriptions.
• MEDIUM - The element is of medium relevance; designated usually for im-

portant elements.
• LOW - Although the element is relevant for a freestyle search, a hit for this
element has no real significance for the ranking of a result item.
 Tip
For the fuzzy search threshold, we recommend using the default value 0.7 to start with. Later on, you can
fine-tune the value based on your experiences with the search. You can also fine-tune the search using
feedback collected from your users.
Example
The listing below implements a search model for searching products. The model definition results from the
data source db_pd that already specifies the persistence layer for searching. The data source provides product
data and text reference fields.

Develop PUBLIC 899
The annotation @Search.searchable: true marks the view as searchable. In addition, the elements Name
and Category are annotated with @Search.defaultSearchElement: true. This means that a freestyle
search is enabled on the search UI where it is possible to search for the annotated elements. The annotation
@Search.fuzzinessThreshold: 0.7 (0.8) defines that the text search should be applied to the element
Category with a similarity value of 70% and to the element Name with a similarity value of 80%.

...
@Search.searchable : true
define view SearchForPuducts as select from db_pd
key pd_id as ID,
@Search.defaultSearchElement : true
@Search.fuzzinessThreshold : 0.8
@Search.ranking : #HIGH
pd_text as Name,
@Search.defaultSearchElement : true
@Search.fuzzinessThreshold : 0.7
@Search.ranking : #LOW
pd_category as Category
}

Results
If you expose a CDS view with search annotations for an OData service, the OData entity set receives the
annotation sap:searchable: true.
The following image display a Fiori UI that consumes an OData service with the example CDS view.
Standard filter allows to search for product category and product name
Related Information
Search Annotations [page 1243]

900 PUBLIC Develop
4.7.3 Using Aggregate Data in SAP Fiori Apps
This topic explains how you can provide aggregate data for your SAP Fiori application. The available aggregate
functions operations are sum, minimum, maximum, and average. Alongside this, the framework also provides
options for counting.
What is Aggregate Data?
We speak of aggregate data when numerical values are combined to form a single value that signifies meaning.
General assumptions can be drawn from this value that is representative for all values that were included in the
calculation of the value.
The classic aggregate functions are:
• sum
• minimum
• maximum
• average
These functions determine a value from which you can assume information relating to all the values that were
included in the calculation.
Apart from these functions, there is also a counting function available to count distinct values:
• distinct count.
This counting option determines a natural number based on the number of entries in the calculation.
All of these functions are supported and evaluated by the SADL framework.
Aggregate Data in your SAP Fiori App
Aggregate data calculated by the SADL framework provides additional and enhanced information for your list
reporting app.
To display aggregate data in your application, annotate the respective elements in CDS with the annotations
described in Annotating Aggregate Functions in CDS [page 902]. These annotations cause the CDS entity
to be respected as an aggregated entity by OData. A thorough description of how OData interprets the
annotations is provided in OData V2 Interpretation of Aggregation Annotations [page 906].
 Note
Aggregate functions are only supported for non-transactional OData V2 scenarios.
Aggregate functions are not supported in scenarios with projection CDS views. Aggregation annotations
in projection view cause an error on service compilation. Aggregation annotations in projected entities are
ignored.

Develop PUBLIC 901
Based on the entity that calculates aggregate data, the SAP Fiori user interface displays aggregate data
depending on the settings you choose. The aggregated values are displayed in your list reporting app as an
additional field in the relevant column.
List Reporting App of Sales Order Items with Aggregate Data
4.7.3.1 Annotating Aggregate Functions in CDS
The elements for which you want to display aggregate data in your SAP Fiori App must be annotated in the CDS
entity with the relevant annotation for the aggregate function.
Metadata for Aggregations
The annotation @Aggregation.Default: #<AGGR_FUNCTION> enables the aggregation of the values of the
annotated element.
Only measures can be annotated with an aggregation annotation. Measures are elements that either represent
numerical values, which means they can be summed, averaged, or otherwise mathematically manipulated.
Typically, measures are units that express the size, amount, or degree of something, for example prices. In
addition, elements with date values, can also be compared with each other to determine the maximum or
minimum. That means date values can also be measures for calculating the minimum or the maximum.
The other elements in a CDS entity are called dimensions. Dimensions provide structured labeling information
about otherwise unordered numeric measures. They are relevant for the grouping and the order of the
elements in the Fiori App.
The SADL framework supports the following aggregating functions for measures. As soon as one element is
annotated with one of these annotations, the CDS entity is considered an analytical entity.
 Note
Only elements with numerical data types can be annotated with @Aggregation annotations.
@Aggregation.Default: #SUM Calculates the sum of the values of the annotated element.
@Aggregation.Default: #MAX Calculates the maximum of the values of the annotated element.
You can also annotate elements with date types with this annotation.

902 PUBLIC Develop
@Aggregation.Default: #MIN Calculates the minimum of the values of the annotated element.
You can also annotate elements with date types with this annotation.
@Aggregation.Default: #AVG Calculates the average of the values of the annotated element.
@Aggregation.Default: Counts the number of distinct values of the annotated element.
#COUNT_DISTINCT In combination with the annotation

@Aggregation.ReferenceElement: ['elementRef'],
you can count the number of distinct values of another element that
is referenced.
 Note
Since the distinct count of the referenced element is naturally

1 for single data records, the value of the annotated element
is 1 regardless of the actual value of the element. In grouped
records the annotated element counts the distinct values of
the referenced element. So the actual value of the annotated
element is ignored.
For this reason, it is recommended that a new element for the

counting of elements be created. Make sure that you use an
adequate numerical type for this element.
 Example
@Aggregation.referenceElement:
['CustomerID']

@Aggregation.default: #COUNT_DISTINCT

DistinctCustomers,
This examples counts the number of distinct customers into

the element DistinctCustomers.
@Aggregation.ReferenceElement: References the element that is used for distinct counts.

['elementRef']
 Note
Can only be used in combination with

@Aggregation.Default: #COUNT_DISTINCT.
Only one aggregate function can be used on one element. You cannot display different aggregated values of the
same element.

Develop PUBLIC 903
Aggregations in Fiori Elements UIs
In a Fiori Elements UI, records are always grouped by the dimensions that are selected by $select in an OData
request. The elements for $select in OData requests are the column elements that are selected in the Fiori UI.
If the key elements are selected in the Fiori UI, the records are grouped by these key elements, which means
there is no grouping, as there are no records that can be grouped by the same key element. If not all key
elements are requested, the records are grouped by the dimensions that are requested and the selected
measures are aggregated according to the groups.
If you want to suppress the behavior, that the records are grouped automatically if not all key elements are
selected, you can use a @UI annotation that triggers the key elements to be always selected implicitly.
Defines the properties that must always be included in the result of

@UI.presentationVariant:

[{requestAtLeast: the queried collection if no grouping is desired.
['<TECHNICAL_KEY>']}]
The UI offers the option to group explicitly. On the UI, go to settings and define the dimensions to group by or
click on a dimension column and choose Group.
For more information on grouping, see OData V2 Interpretation of Aggregation Annotations [page 906].
Example
The following listing displays a CDS entity in which all the necessary annotations for analytical operations are
used. This view describes sales order combined with associated product and customer information.
 Sample Code
define view entity ZDEMO_C_SOI_ANLY

as select from <data source> as Item
association [0..1] to SEPM_I_Product_E as _Product on
$projection.Product = _Product.Product
association [0..1] to ZDEMO_C_SO_ANLY as _SalesOrder on
$projection.SalesOrderID = _SalesOrder.SalesOrder
{
key SalesOrder as
SalesOrderID,
key SalesOrderItem as
ItemPosition,
Item._SalesOrder.Customer as
CustomerID,
Item._SalesOrder._Customer.CompanyName as
CompanyName,
@ObjectModel.foreignKey.association: '_Product'
Product as
Product,
_Product.ProductCategory as
ProductCategory,

904 PUBLIC Develop
TransactionCurrency as
CurrencyCode,
cast( 'EUR' as abap.cuky ) as
TargetCurrency,
@Aggregation.Default: #SUM
@Semantics.amount.currencyCode: 'TargetCurrency'
CURRENCY_CONVERSION(
amount => Item.GrossAmountInTransacCurrency,
source_currency => Item.TransactionCurrency,
target_currency => cast( 'EUR' as abap.cuky ),
exchange_rate_date => cast( '20180315' as abap.dats ),
error_handling => 'SET_TO_NULL' ) as
ConvertedGrossAmount,
@Aggregation.Default: #AVG
GrossAmountInTransacCurrency as
GrossAmount,
@Aggregation.Default: #MIN
NetAmountInTransactionCurrency as
NetAmount,
@Aggregation.Default: #MAX
TaxAmountInTransactionCurrency as
TaxAmount,
@Aggregation.referenceElement: ['Product']
@Aggregation.Default: #COUNT_DISTINCT
DistinctProducts,
_SalesOrder,
_Product
}

 Note
Aggregate functions only respect values with the same semantics. This means that, if you have prices in
different currencies that are annotated with an aggregation annotation, you receive aggregated data for
each currency.
The following figure displays the maximum tax amount with regard to the respective currency.
Aggregate Data for Distinct Currencies
Related Information

Develop PUBLIC 905
OData V2 Interpretation of Aggregation Annotations [page 906]
4.7.3.2 OData V2 Interpretation of Aggregation

Annotations
The following sections provide an overview of the most prominent features of aggregated entities in OData.
Data models with aggregation annotations are considered as aggregated entities by OData. The behavior of
these aggregated OData entities differs from non-aggregated entities.
OData Annotations
The OData entity is given multiple annotations based on the aggregate annotation you use in CDS for your data
model. The following figure displays the metadata of an aggregated entity that processes sales order items.
The annotations specific to aggregations are highlighted and labeled. Further descriptions of the annotations in
OData are given below.
Metadata of an Aggregated Entity
Aggregated OData Entities

As soon as one element in the CDS view is annotated with the aggregation annotation
@Aggregation.Default: #<AGGR_FUNCTION>, the OData entity is annotated with sap:semantics=
“aggregate”. Hence, the OData entity is identified as an aggregated entity.
In the example of the screenshot above, this OData annotation can be found in the first line of the extract of the
metadata.

906 PUBLIC Develop
Measures
The aggregated entity is characterized by measures and dimensions. Measures are those properties that are
annotated with the annotation relevant for aggregating data in CDS. Measures are given the OData annotation
sap:aggregation-role=”measure”.
In the example of the screenshot above, there are six properties which are marked as measures:
ConvertedGrossAmount, GrossAmount, NetAmount, TaxAmount, AllItems, and DistinctProducts.
Dimensions
Dimensions are all properties that are neither marked as measures nor as attributes. Dimensions are given the
OData annotation sap:aggregation-role=”dimension”.
In the example of the screenshot above, there are six OData properties which are marked as dimensions:
SalesOrderID, ItemPosition, Customer ID, Product, CurrencyCode, and TargetCurrency.
Each dimension can have a maximum of one text property. A text property is an element that is defined as a
text element in CDS, as described in Working with Text Elements [page 891]. Dimensions with a text property
are annotated by OData with sap:text="<TEXT_PROPERTY>".
In the example of the screenshot above, the dimension Product has a text property.
Attributes
Dimensions can have attributes. Attributes are elements that are annotated with the annotation
@Consumption.groupWithElement: 'ElementRef'. The attributes are always considered as an
addition to their corresponding dimension. Attributes are annotated by OData with sap:attribute-
for="<DIMENSION>".
In the example of the screenshot above, the dimension CustomerID has the attribute CompanyName and the
dimension Product has the attribute ProductCategory.
Generated ID for Aggregated OData Entities
An aggregated OData entity is given an additional property for a generated ID (<Property Name="ID"/>).
The generated ID for the aggregate entity uniquely identifies each record so that every entity request for a given
ID always returns the same values.
In the example of the screenshot above, the property for the generated ID can be found as the first property on
the list.
The ID is also generated for every group record when it is requested for the first time. Following from this, you
can use this ID in a further request.
 Example
This behavior is exemplified by a request on the entity that supplies the metadata above. It retrieves sales
order items. The following request selects the generated ID ( ID), the dimension Product, and some
aggregated measures related to the selected dimension.
.../sap/opu/odata/SAP/<service_name>/ZDEMO_C_SOI_ANLY?
$select=ID,Product,GrossAmount,NetAmount,TaxAmount,AllProducts
This request retrieves the following result:

Develop PUBLIC 907
Aggregate Data of Group Record with Generated ID for Group Record
Each group record is given its own generated ID which retrieves the same results when requested
again. Based on this group ID, you can also execute other requests, as in /sap/opu/odata/SAP/
<service_name>/ZDEMO_C_SOI_ANLY('.4~HT%26c1002.6~USD')?$select=AllProducts, which
will only retrieve the count of this group, which is 9.
Requesting Data from an Aggregated Entity
Results of requesting data from aggregated entities depend on the elements you select in your OData request.
Grouping and aggregation are both driven by the elements you request with the parameter $select in
entity set queries. The result of a query consists of aggregated entities with distinct values for the requested
dimension properties and requested measures are aggregated using the aggregate function with which the
measure elements are annotated in CDS.
If an attribute is requested, the result is grouped by its corresponding dimension and within that group it is
grouped by the attribute itself.
 Note
If you use a SAP Fiori app, the $select statement of the OData request directly depends on the columns
you select in the list reporting app. The following descriptions of requesting data with OData can also be
managed by selecting the respective columns in your Fiori App.
Requests that Contain All Primary Key Elements
If all primary key elements of the requested CDS entity are included in the query option $select, no grouping
is possible since every record is unique. Hence, an OData request with all key elements behaves just like a
non-aggregated entity. Consequently, no aggregate data is calculated.

908 PUBLIC Develop
Requests that Do not Contain All Primary Key Elements
If not all key elements are included in the OData request, the requested dimensions are grouped and the
requested measures are aggregated according to their annotated aggregate function. For every distinct
combination of dimension values (after evaluating $filter), the result includes an aggregated entity with
aggregated values for the requested measures.
 Note
Each group record is given its own generated ID, which can be reused in requests to retrieve the same
results.
Only if no dimension and no attribute are requested does the result show the aggregate data of measures for
the whole entity set.
You can still execute other query options, such as $filter or $orderby on grouped requests. The filtering is
executed before the grouping, so that the groups are created from the available records after the filtering. The
ordering is executed after the grouping, which means the records within a group are ordered according to the
query option.
 Note
You can filter for properties that you do not select, but you cannot order by properties that are not included
in the $select due to the order of executing query options mentioned above.
Navigating and Expanding from a Group Record
You can navigate directly from a group record to one of the properties that are included in the group, for
example properties that you have selected previously.
 Example
Assume you have an aggregated entity of sales order items and you group them by product. From this
group record, you can navigate directly to the associated entity of products if the association exists in CDS.
The same holds true for the query option $expand. Only properties that are selected can be expanded.
 Note
The target entity of the navigation or the expand is also given an aggregated ID if the underlying data model
is also aggregated.
Related Information

Annotating Aggregate Functions in CDS [page 902]

Develop PUBLIC 909
4.7.4 Using Virtual Elements in CDS Projection Views
With virtual elements, you define additional CDS elements that are not persisted on the database, but
calculated during runtime using ABAP classes that implement the virtual element interface.
What Are Virtual Elements, and Why Do I Need Them?
For some business use cases, it may be necessary to add new elements to the data model of an application
whose values cannot be fetched from the database. Virtual elements are used if these elements are not
provided as part of the original persistence data model but can be calculated using ABAP resources during
runtime.
Virtual elements represent transient fields in business applications. They are defined at the level of CDS
projection views as additional elements within the SELECT list. However, the calculation of their values is
carried out by means of ABAP classes that implement the specific virtual element interface provided for this
purpose. The ABAP implementation class is referenced by annotating the virtual element in the CDS projection
view with @ObjectModel.virtualElementCalculatedBy: 'ABAP:<CLASS_NAME>'. With data retrieval
via OData, the query framework calls the ABAP implementation class of the virtual element to retrieve the
value for it. The instance of the ABAP implementation class instance is reused for all requests related to the
same entity within the ABAP session.
The OData service metadata do not differentiate between regular CDS elements with database persistence and
virtual elements. Consequently, the virtual element appears in an application UI equal to any other element.
Definition of Virtual Element in CDS Projection View and Implementation in Referenced ABAP Class
 Note
• You can use virtual elements only in CDS projection views.

•  Cloud In the current version of the ABAP RESTful Programming Model, you cannot add
implementations for filtering or sorting by virtual elements.
• Virtual elements cannot be keys of the CDS projection view.
• Virtual elements cannot be used together with the grouping or the aggregation function.
• Data from virtual elements can only be retrieved via the query framework. In particular this means that
the following options to retrieve data from CDS are not possible for virtual elements:
• ABAP SQL SELECT on CDS views return initial values for the virtual element,
• EML READ on BO entities is not possible as EML does not know virtual elements.

910 PUBLIC Develop
Example
In an application that processes flight bookings, we want to include a field that calculates how many days are
left until the flight date, or how many days have passed since the flight date. The following booking app UI
provides the booking information with an additional field Days to Flight that calculates the days that have
passed since the flight or the days that are left until the flight. The value is calculated by comparing the flight
date with the system date.
Flight Bookings List with Virtual Element to Calculate Days to Flight
Developer Activities
1. Adding the virtual element and corresponding annotations to the relevant CDS projection view.
For a more detailed description, see Modeling Virtual Elements [page 911].
2. Creating and implementing an ABAP class that implements the virtual element calculation.
For more detailed information, see Implementing the Calculation of Virtual Elements [page 912].
4.7.4.1 Modeling Virtual Elements
Virtual elements are defined in the select list of CDS projection views. Their values are calculated in a
referenced ABAP class. This topic explains how you can model virtual elements in CDS.
Context
A virtual element is declared in the CDS projection view. It enables you to have additional fields that are not
persisted on the database in your application scenario. You can also have different virtual elements in different
BO projections. With those, you are flexible in providing an accurately tailored projection layer for one specific
service without affecting the basic business object.
You can use virtual elements for read-only, as well as for transactional scenarios.
Virtual elements can also be used in CDS projection views that are defined as custom queries by the annotation
ObjectModel.query.implementedBy. In this case, the custom query is evaluated first. Then, the virtual

Develop PUBLIC 911
element is calculated and can use the values returned by the custom query. This can be useful, for example, in
extensibility scenarios.
The following steps model a virtual element in a CDS projection view using the CDS view /DMO/I_BOOKING_U
as an underlying CDS view. The projection CDS view defines the subset of the CDS view that is relevant to the
respective service and is extended with a virtual field for this service.
For details about the syntax for defining a Virtual Element in CDS Projection View, see CDS DDL - CDS
Projection View, VIRTUAL (ABAP- Keyword Documentation)
 Example
define view entity /DMO/C_Booking_VE

as projection on /DMO/I_Booking_U
{ ...
@ObjectModel.virtualElementCalculatedBy: 'ABAP:/DMO/
CL_DAYS_TO_FLIGHT'
@EndUserText.label: 'Days to Flight'
virtual DaysToFlight : abap.int2,

…}
Next Steps
1. Creating and implementing an ABAP class that implements the virtual element contract.
More on this: Implementing the Calculation of Virtual Elements [page 912].
4.7.4.1.1 Implementing the Calculation of Virtual Elements
The values of virtual elements are calculated in a referenced ABAP class. This topic explains how you calculate
their values by means of an example implementation.
Context
By using a virtual element in a CDS projection view, you define an additional field for your OData service. As
this additional field is not persisted in the database layer, its value must be calculated during runtime. The
calculation is implemented in an ABAP class that is referenced in an annotation on the virtual element in the
CDS projection view.
The calculation class must implement the interface IF_SADL_EXIT_CALC_ELEMENT_READ. This interface
provides two methods for the calculation implementation:
• get_calculation_info: This method is called before the actual data retrieval. It ensures that all the
relevant elements that are needed for the calculation of the virtual element are selected.
• calculate: This method is called after the data retrieval. It uses the values of the relevant elements to
calculate the value for the virtual element.

912 PUBLIC Develop
Prerequisites
• The virtual element is modeled in the CDS projection view as explained in Modeling Virtual Elements [page
911].
• The virtual element uses the annotation @ObjectModel.virtualElementCalculatedBy which
references an existing ABAP class.
Procedure
1. Add the interface IF_SADL_EXIT_CALC_ELEMENT_READ to the public section of your calculation class
and add the two method implementations.
 Example
CLASS /dmo/cl_days_to_flight DEFINITION

PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
INTERFACES if_sadl_exit_calc_element_read.
PROTECTED SECTION.
PRIVATE SECTION.
ENDCLASS.
CLASS /dmo/cl_days_to_flight IMPLEMENTATION.
METHOD if_sadl_exit_calc_element_read~get_calculation_info.
ENDMETHOD.
METHOD if_sadl_exit_calc_element_read~calculate.
ENDMETHOD.

ENDCLASS.
2. Implement the method get_calculation_info.

With this method, you can check that the calculation for the virtual element is only executed if the relevant
element is requested. In addition, you must provide a list of elements that are required for the calculation.
You can only add elements of the requested CDS entity.
For more information, see the method description of get_calculation_info [page 915].
If an entity or a virtual element other than the intended is requested, raise adequate exceptions. For more
information on application-specific message handling, see , , and .
 Example
At first, we check if the requested entity is the entity that contains the virtual element for which the
calculation is intended. To calculate the remaining time or the passed time compared to the flight date,
we need the element FlightDate. This element is added to the requested elements list to ensure that
the value is available to calculate the virtual element.
It is possible to calculate the values for more than one virtual element in the same ABAP class.
Depending on the virtual element, you might have to append different elements to the list of requested
elements.
 Expand the following code sample to view the source code of method get_calculation_info.

Develop PUBLIC 913
 Sample Code
CLASS /dmo/cl_days_to_flight IMPLEMENTATION.

METHOD if_sadl_exit_calc_element_read~get_calculation_info.
IF iv_entity <> '/DMO/C_BOOKING_VE'.
EXPORTING
textid = /dmo/cx_virtual_elements=>entity_not_known
entity = iv_entity.
ENDIF.
LOOP AT it_requested_calc_elements ASSIGNING FIELD-
SYMBOL(<fs_calc_element>).
CASE <fs_calc_element>.
WHEN 'DAYSTOFLIGHT'.
APPEND 'FLIGHTDATE' TO et_requested_orig_elements.
* WHEN 'ANOTHERELEMENT'.
* APPEND '' ...
WHEN OTHERS.
EXPORTING
textid = /dmo/
cx_virtual_elements=>virtual_element_not_known
element = <fs_calc_element>
entity = iv_entity.
ENDCASE.
ENDLOOP.
ENDMETHOD.

ENDCLASS.
 Note
The methods of the interface IF_SADL_CAL_ELEMENT_READ import and export their parameters as
strings in upper case. The CDS entity and element names must therefore be in upper case as well, so
they can be mapped correctly.
3. Implement the method calculate.

it_original_dataWith this method, you must as they are previously retrieved. The parameter
it_requested_calc_elements contains one or more virtual elements. In the changing parameter
ct_calculated_data, you must provide the calculated value for the virtual element.
For more information, see the method description of calculate [page 916].
 Example
In our example, we want to calculate how many days are left before the flight or how many days have
passed since the flight, so we compare the value of FLIGHTDATE with today's date to calculate the
value for the virtual element.
The system date can be retrieved via cl_abap_context_info=>get_system_date( ).
ABAP is able to calculate with date types as long as the date context is clear. The actual calculation is
therefore quite easy: We just subtract the today's date from the flight date. The returning parameter
can then be filled with the calculated days to flight.
METHOD if_sadl_exit_calc_element_read~calculate.

DATA(lv_today) = cl_abap_context_info=>get_system_date( ).
DATA lt_original_data TYPE STANDARD TABLE OF /dmo/c_booking_proc_ve
WITH DEFAULT KEY.
lt_original_data = CORRESPONDING #( it_original_data ).
LOOP AT lt_original_data ASSIGNING FIELD-SYMBOL(<fs_original_data>).

914 PUBLIC Develop
<fs_original_data>-DaysToFlight = <fs_original_data>-FlightDate -
lv_today.
ENDLOOP.
ct_calculated_data = CORRESPONDING #( lt_original_data ).

ENDMETHOD.
Related Information
Interface IF_SADL_EXIT_CALC_ELEMENT_READ [page 915]
4.7.4.2 API for Virtual Elements
Virtual elements are defined in CDS projection views and implemented in related ABAP classes that calculate
their values and transform filtering and sorting requests. For this calculation and transformation, the generic
RAP runtime engine calls the ABAP classes that implement the methods of the virtual elements API.
• Calculation: Interface IF_SADL_EXIT_CALC_ELEMENT_READ [page 915]
For more information about virtual elements, see Using Virtual Elements in CDS Projection Views [page 910].
4.7.4.2.1 Interface IF_SADL_EXIT_CALC_ELEMENT_READ
Interface that must be implemented by calculation classes for virtual elements that are referenced at the level
of the CDS projection view element with the annotation@ObjectModel.virtualElementCalculatedBy.
This interface defines the following methods for implementing the field calculation:
Method get_calculation_info
This method provides a list of all elements that are required for calculating the values of the virtual elements in
the requested entity.
This method is called during runtime before the retrieval of data from the database to ensure that all necessary
elements for calculation are filled with data.
Signature
TYPES tt_elements TYPE SORTED TABLE OF string WITH UNIQUE DEFAULT KEY .

METHODS get_calculation_info IMPORTING !it_requested_calc_elements TYPE
tt_elements
!iv_entity TYPE string
EXPORTING !et_requested_orig_elements TYPE
tt_elements

RAISING cx_sadl_exit.

Develop PUBLIC 915
Parameter
importing it_requested_calc_elements List of the virtual elements that are requested by the client
and intended for calculation.
The names of the virtual elements are listed as upper case

strings.
iv_entity Name of the CDS entity that contains the requested virtual
elements in it_requested_calc_elements.
The name of the CDS entity is a string in upper case.
exporting et_requested_orig_elements List of the CDS elements that are needed for the calculation.
The CDS elements are listed as upper case strings.
 Note
Only elements of the requested entity that are needed

for the calculation of the virtual elements. iv_entity
can be appended for data retrieval.
raising cx_sadl_exit Abstract exception class that can be used to raise excep-
tions and return messages related to the processing of the
virtual element calculation.
 Example
See Implementing the Calculation of Virtual Elements [page 912].
Method calculate
Executes the value calculation for the virtual element.
This method is called during runtime after data is retrieved from the database. The elements needed for the
calculation of the virtual elements are already inside the data table passed to this method. The method returns
a table that contains the values of the requested virtual elements.
Signature
TYPES tt_elements TYPE SORTED TABLE OF string WITH UNIQUE DEFAULT KEY .

METHODS calculate IMPORTING !it_original_data TYPE STANDARD TABLE
!it_requested_calc_elements TYPE tt_elements
CHANGING !ct_calculated_data TYPE STANDARD TABLE

RAISING cx_sadl_exit.
importing it_original_data Result table of the retrieved values for the elements re-
quested by the client, in addition to the elements that are
needed for calculation, which are requested for data retrieval
by the method get_calculation_info.

916 PUBLIC Develop
it_requested_calc_elements List of virtual elements that are requested by the client and
are intended for calculation.
The names of the virtual elements are listed as upper case

strings.
exporting ct_calculated_data Table of the virtual element for each entity instance corre-
sponding to the table it_original_data by index.
raising cx_sadl_exit Abstract exception class that can be used to raise excep-
tions and return messages related to the processing of vir-
tual element calculation.
With this method you ensure that the virtual element is calculated and that its values are passed to the runtime
engine to process the data in the requested entity.
 Example
See Implementing the Calculation of Virtual Elements [page 912].
4.8 Implementing an Unmanaged Query
An unmanaged query uses an ABAP interface to implement read-only access to persistent or non-persistent
data. It enables a more flexible data retrieval than using the SQL push down by the query framework to retrieve
data from a database table.
Context
An unmanaged query is implemented for read-only access to a data source whenever the standard SQL
push-down by the query framework is not sufficient or not usable at all; or if there is no persistent data source
at all.
Use cases for unmanaged queries are
• the data source for an OData request is not a database table, but, for example another OData service,
which is reached by an OData client proxy,
• performance optimization with application specific handling,
• using AMDPs with some query push-down parameters in the SQL script implementation,
• forwarding the call to the analytical engines, or
• enrichment of query result data on property or row level, for example when splitting rows for intermediate
sums or condensing the filter result.
In these cases, the data model is defined in a CDS view, for example, in a custom entity
which references a query implementation class, where the query is implemented using a query

Develop PUBLIC 917
provider interface. The runtime of an unmanaged query is illustrated in the following diagram.
For more background information about the unmanaged query and the custom entity, see Unmanaged Query
[page 285].
Example Scenario
The following sections offer an example for the implementation of the query provider interface. It is aimed
to give an understanding on how to work with the interface IF_RAP_QUERY_PROVIDER. The example query
implementation retrieves data from a database table, which is not a typical use case.
 Note
Do not use the custom query in the straight-forward case of retrieving data from a database table. The
example is only used for demonstration purposes, as no background information about another technology
(for example in AMDP implementations) is necessary to understand the example. The recommended
implementation for such a scenario is to use a CDS view and the underlying query implementation of the
SQL select by the RAP runtime engine.
The data model is defined in a custom entity. Expand the following codeblock to view the data model of the
example scenario. For simplification reasons, the same element names as in the data source are used. (If you
use differing names, you must map the elements of the custom entity to the corresponding table fields in the
query implementation. Make sure that the types are compatible.)
For information about the syntax in custom entities, see CDS DDL - DEFINE CUSTOM ENTITY (ABAP - Keyword
Documentation).  Expand the following code sample to view the source code
Custom Entity /DMO/I_TRAVEL_U
@EndUserText.label: 'Custom entity for unmanaged travel query'

@ObjectModel.query.implementedBy:'ABAP:/dmo/cl_travel_uq'
define custom entity /DMO/I_TRAVEL_UQ

918 PUBLIC Develop
{
key Travel_ID : abap.numc( 8 );
Agency_ID : abap.numc( 6 );
Customer_ID : abap.numc( 6 );
Begin_Date : abap.dats;
End_Date : abap.dats;
Booking_Fee : abap.dec( 17, 3 );
Total_Price : abap.dec( 17, 3 );
Currency_Code : abap.cuky;
LastChangedAt : timestampl;

}
The annotation @ObjectModel.query.ImplementedBy references the query implementation class. Learn

how you implement the unmanaged query for this example scenario in the following section.
The data source in the example scenario is the database table /dmo/travel, see ABAP Flight Reference
Implementation
Every method provided by IF_RAP_QUERY_PROVIDER is used and explained in this implementation. The
complete source code of the query implementation with every method is displayed after the implementation
steps.
 Note
For every query request on the CDS custom entity, the implementation class is reinstantiated. The class
instance is never cached.
Prerequisites
• The custom entity references the query implementation class in the annotation
@ObjectModel.query.implementedBy.
• The query implementation class implements the interface IF_RAP_QUERY_PROVIDER with its select
method.
 Caution
In scenarios, in which you expose your custom entity for a Fiori UI, you have to include at least the
implementation for counting and paging as the UI always requests the count and sets the query options
$top and $skip for paging.
To receive consistent results on the pages, it is also indispensable to implement the method for sorting to
support the query option $orderby. When paging is requested the RAP query engine adds the primary key
to the query option for stable paging results.
If the corresponding methods are not implemented and the unmanaged query does not return the
respective information, there will be an error during runtime.

Develop PUBLIC 919
 Note
To avoid high resource consumption when calling an OData service without using $top each OData service,
based on the ABAP RESTful Programming Model uses a default paging. This includes
• Setting a default paging if the client does not provide $top

• Reducing the response to the default limit if $top exceeds this limit
• Adding a __next link with a skiptoken to the response if the response represents a partial listing,
which is a subset of all available data records. See https://www.odata.org/documentation/odata-
version-2-0/json-format/ → 6. Representing Collections of Entries.
 Note
The RAP runtime engine can only handle associations to or from a custom entity with attribute bindings (A1
= A2 and B1 = B2), but no:
• OR, NOT
• Other operators than ‘=’
• Using something else than CDS elements as operands (e.g. no literals or variables)
• Check that the query is only executed when the requested entity set matches the custom entity.
For implementation details, see Returning Requested Entity in an Unmanaged Query [page 923].
• Separate your implementation for data retrieval and count.
For implementation details, see Requesting and Setting Data or Count in an Unmanaged Query [page
923].
• Implement filter conditions according to
• a requested filter,
For implementation details, see Implementing Filtering in an Unmanaged Query [page 925]
• a requested search term,
For implementation details, see Implementing Search in an Unmanaged Query [page 929]
• requested parameters.
For implementation details, see Using Parameters in an Unmanaged Query [page 927].
• Get the paging information and retrieve data according to the requested page.
For implementation details, see Implementing Paging in an Unmanaged Query [page 931].
• Get the sorting information and order the retrieved data according to the sort elements and direction.
For implementation details, see Implementing Sorting in an Unmanaged Query [page 933].
• Get the requested elements and select only the relevant elements from the data source.
For implementation details, see Considering Requested Elements in an Unmanaged Query [page 935].
• Get the aggregated and the grouped elements and aggregated and group the records accordingly.
For implementation details, see Implementing Aggregations in an Unmanaged Query [page 936].

920 PUBLIC Develop
Query Implementation Class /dmo/cl_travel_uq c
CLASS /dmo/cl_travel_uq DEFINITION

PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
PROTECTED SECTION.
PRIVATE SECTION.
ENDCLASS.
CLASS /dmo/cl_travel_uq IMPLEMENTATION.
TRY.
CASE io_request->get_entity_id( ).
WHEN '/DMO/I_TRAVEL_UQ' .
**query implementation for travel entity
**filter
DATA(lv_sql_filter) = io_request->get_filter( )-
>get_as_sql_string( ).
TRY.
DATA(lt_filter) = io_request->get_filter( )->get_as_ranges( ).
CATCH cx_rap_query_filter_no_range.
"handle exception
ENDTRY.
**parameters
DATA(lt_parameters) = io_request->get_parameters( ).
DATA(lv_next_year) = CONV /dmo/
end_date( cl_abap_context_info=>get_system_date( ) + 365 ) .
DATA(lv_par_filter) = | BEGIN_DATE >=
'{ cl_abap_dyn_prg=>escape_quotes( VALUE #( lt_parameters[ parameter_name =
'P_START_DATE' ]-value
DEFAULT cl_abap_context_info=>get_system_date( ) ) ) }'| &&

| AND | &&
| END_DATE <=
'P_END_DATE' ]-value
DEFAULT lv_next_year ) ) }'| .

IF lv_sql_filter IS INITIAL.
lv_sql_filter = lv_par_filter.
ELSE.
lv_sql_filter = |( { lv_sql_filter } AND { lv_par_filter } )| .
ENDIF.
**search
DATA(lv_search_string) = io_request->get_search_expression( ).
DATA(lv_search_sql) = |DESCRIPTION LIKE '%
{ cl_abap_dyn_prg=>escape_quotes( lv_search_string ) }%'|.
lv_sql_filter = lv_search_sql.
ELSE.
lv_sql_filter = |( { lv_sql_filter } AND { lv_search_sql } )|.
ENDIF.
**request data
**paging
DATA(lv_offset) = io_request->get_paging( )->get_offset( ).
DATA(lv_page_size) = io_request->get_paging( )->get_page_size( ).
DATA(lv_max_rows) = COND #( WHEN lv_page_size =
if_rap_query_paging=>page_size_unlimited
THEN 0 ELSE lv_page_size ).
**sorting
DATA(sort_elements) = io_request->get_sort_elements( ).
DATA(lt_sort_criteria) = VALUE string_table( FOR sort_element IN
sort_elements

Develop PUBLIC 921
( sort_element-
element_name && COND #( WHEN sort_element-descending = abap_true THEN `
descending`
ELSE ` ascending` ) ) ).
DATA(lv_sort_string) = COND #( WHEN lt_sort_criteria IS INITIAL
THEN `primary key`
ELSE concat_lines_of( table = lt_sort_criteria sep = `, ` ) ).

**requested elements
**aggregate
DATA(lt_aggr_element) = io_request->get_aggregation( )-
>get_aggregated_elements( ).
IF lt_aggr_element IS NOT INITIAL.
LOOP AT lt_aggr_element ASSIGNING FIELD-
SYMBOL(<fs_aggr_element>).
DELETE lt_req_elements WHERE table_line = <fs_aggr_element>-
result_element.
DATA(lv_aggregation) = |{ <fs_aggr_element>-
aggregation_method }( { <fs_aggr_element>-input_element } ) as
{ <fs_aggr_element>-result_element }|.
APPEND lv_aggregation TO lt_req_elements.
ENDLOOP.
ENDIF.
DATA(lv_req_elements) = concat_lines_of( table = lt_req_elements
sep = `, ` ).
****grouping
DATA(lt_grouped_element) = io_request->get_aggregation( )-
>get_grouped_elements( ).
DATA(lv_grouping) = concat_lines_of( table = lt_grouped_element
sep = `, ` ).
**select data
DATA lt_travel_response TYPE STANDARD TABLE OF /dmo/i_travel_uq.
SELECT (lv_req_elements) FROM /dmo/travel
WHERE (lv_sql_filter)
GROUP BY (lv_grouping)
ORDER BY (lv_sort_string)
INTO CORRESPONDING FIELDS OF TABLE
@lt_travel_response
OFFSET @lv_offset UP TO @lv_max_rows ROWS.
**fill response
io_response->set_data( lt_travel_response ).
ENDIF.
**request count
**select count
SELECT COUNT( * ) FROM /dmo/travel
INTO @DATA(lv_travel_count).
**fill response
io_response->set_total_number_of_records( lv_travel_count ).
ENDIF.
WHEN `/DMO/I_BOOKING_UQ`.
**query implementation for booking entity
ENDCASE.
CATCH cx_rap_query_provider.
ENDTRY.
ENDMETHOD.

ENDCLASS.

922 PUBLIC Develop
4.8.1 Returning Requested Entity in an Unmanaged Query
Getting the requested entity ID into your query implementation class can be helpful to ensure that the query
is only executed if a specific entityis queried. You can also differentiate between query implementations of
different custom entities in one query implementation class. The interface IF_RAP_QUERY_REQUEST provides
a method to get the entity ID, which is requested.
Prerequisites
For general prerequisites of an unmanaged query implementation, see Prerequisites Unmanaged Query [page
919].
The following steps provide an example on how to use the method get_entity_id in your query
1. Call the method get_entity_id of the interface IF_RAP_QUERY_REQUEST, which returns the requested
CDS entity name.
2. Use the returned value to compare to the custom entity the query implementation is aimed at, or to define
query implementation for different custom entities in one query implementation class.
The following codeblock illustrates the implementation within the SELECT method of
IF_RAP_QUERY_PROVIDER in the query implementation class.
CASE io_request->get_entity_id( ).

WHEN `/DMO/I_TRAVEL_UQ` .
****query implementation for travel entity
WHEN `/DMO/I_BOOKING_UQ`.
****query implementation for booking entity

ENDCASE.
For API information, see Method get_entity_id [page 291].
4.8.2 Requesting and Setting Data or Count in an

Unmanaged Query
The interface IF_RAP_QUERY_REQUEST provides methods to indicate whether data or the count is requested.
These methods can be used to separate the implementations for data retrieval and count or to ensure that the
query implementation is only executed if the respective request is made.
The interface IF_RAP_QUERY_RESPONSE provides methods to return the requested data or the count as a
response for the request.

Develop PUBLIC 923
 Note
If data is requested, the method set_data must be called. If the total number of records is requested,
the method set_total_number_of_records must be called. Otherwise there will be an error during
runtime.
In UI scenarios with Fiori Elements the total number of records is always requested by the UI.
Prerequisites
919].
Requesting and Setting Data
The following steps provide an example on how to use the method is_data_requested in your query
1. Call the method is_data_requested of the interface IF_RAP_QUERY_REQUEST, which returns a boolean
value.
2. Create the SQL SELECT to retrieve the requested data into a local variable.
3. Call the method set_data of the interface IF_RAP_QUERY_RESPONSE and use the retrieved data as
importing parameter. The result is then returned to the OData client, for example the SAP Fiori Elements
UI.
The following codeblock illustrates the implementation for data requests within the select method of
IF_RAP_QUERY_PROVIDER in the query implementation class..

SELECT * FROM /dmo/travel
INTO CORRESPONDING FIELDS OF TABLE @lt_travel_response.

ENDIF.
For API information, see Method is_data_requested [page 292] and Method set_data [page 303].
Requesting and Setting Count
The following steps provide an example on how to use the method is_total_numb_of_rec_requested in
your query implementation class.
1. Call the method is_total_numb_of_rec_requested of the interface IF_RAP_QUERY_REQUEST, which

returns a boolean value.
2. Create the SQL SELECT to retrieve the requested count into a local variable.

924 PUBLIC Develop
3. Call the method set_total_number_of_records of the interface IF_RAP_QUERY_RESPONSE and use
the retrieved data as importing parameter. The count is then returned to the OData client, for example the
SAP Fiori Elements UI.
The following codeblock illustrates the implementation for data requests within the select method of
IF_RAP_QUERY_PROVIDER in the query implementation class. .


ENDIF.
For API information, see Method is_total_numb_of_rec_requested [page 292] and Method
set_total_number_of_records [page 304].
4.8.3 Implementing Filtering in an Unmanaged Query
To retrieve filtered data or a filtered number of records in an unmanaged query, you need to implement a filter
in the query implementation class. The interface IF_RAP_QUERY_REQUEST provides a method to get the filter
for the request with three options to retrieve the filter conditions:
• Get the filter condition as an SQL string.

• Get the filter condition in a ranges table.
• Get the filter condition in a filter tree.
Choose one of these options depending on your use case. If you retrieve your data from the data source with
an SQL SELECT, you can include the SQL filter string directly in the WHERE clause of the SELECT statement. If
you want to manipulate the filter conditions before executing the filter, a ranges table can be the better choice.
Ranges tables cannot express all possible filter conditions. In cases where you want to include complex filter
conditions in an easily parsable format, the filter tree is a suitable option. It also enables you to manipulate the
filter conditions beforehand.
 Note
If the filter is not feasible as a ranges table, an exception is raised. You then have to handle the error
appropriately.
Prerequisites
919].

Develop PUBLIC 925
Using the Filter as an SQL String

The following steps provide an example on how to use the method get_as_sql_string in your query
1. Call the method get_filter of the interface IF_RAP_QUERY_REQUEST, which returns an interface
instance of IF_RAP_QUERY_FILTER. Use the method get_as_sql_string to use the filter directly in
an SQL string.
2. Check if data is requested.
3. Use the filter condition in the WHERE clause of the SQL statement to retrieve the filtered data from the data
source.
4. Call the method set_data of the interface IF_RAP_QUERY_RESPONSE to respond to the OData request
with the filtered data. The filtered result is then returned to the OData client, for example the SAP Fiori
Elements UI.
5. Check if count is requested.
6. Use the filter condition in the WHERE clause of the SQL statement to retrieve the count for the data records
that match the request.
7. Call the method set_total_number_of_records of the interface IF_RAP_QUERY_RESPONSE to
respond to the OData request with the filtered count. The filtered result is then returned to the OData
client, for example the SAP Fiori Elements UI.
The following codeblock illustrates the filter implementation within the select method of
DATA(lv_sql_filter) = io_request->get_filter( )->get_as_sql_string( ).

ORDER BY ('primary key')
ENDIF.
DATA(lv_travel_count) = conv int8( lines( lt_travel_response ) ).

ENDIF.
 Note
It is recommended to implement a default sort order to return consistent results from the data source.
For API information, see Method get_filter [page 293].
Getting the Filter as Ranges Table

The following steps provide an example on how to use the method get_as_ranges in your query
1. In a TRY - CATCH block, call the method get_filter of the interface IF_RAP_QUERY_REQUEST, which
returns an interface instance of IF_RAP_QUERY_FILTER. Use the method get_as_ranges to get the filter
as a ranges table. The format of the returned ranges table is described in Method get_as_ranges [page
296].

926 PUBLIC Develop
2. Use the filter condition of the ranges table in your implementation.
3. Catch the exception CX_RAP_QUERY_FILTER_NO_RANGE, which is raised if the filter cannot be expressed
as a ranges table.
4. Handle the exception appropriately. For example:
1. Throw an error.
2. Use the filter SQL string as a fall back, see Method get_as_sql_string [page 298]
TRY.

DATA(lt_ranges) = io_request->get_filter( )->get_as_ranges( ).
****filter manipulation
CATCH cx_rap_query_filter_no_range.
""error handling

ENDTRY.
Getting the Filter as Filter Tree
The following steps provide an example on how to use the method get_as_tree in your query implementation
class.
1. Call the method get_filter of the interface IF_RAP_QUERY_REQUEST, which returns an interface
instance of IF_RAP_QUERY_FILTER.
2. Call the mehod get_as_tree for this instance. The format of the returned filter tree is described in
Method get_as_tree [page 299].
3. Check if the returned filter tree reference is bound. If no filter condition is supplied, the reference is
unbound and method calls using the filter tree reference variable lead to a dump.
4. If the filter tree reference is bound, you can use use the methods get_root_node, get_children,
get_type and get_value of the interface to parse the structure of the filter tree and use the retrieved
filter condition in your implementation.
DATA(filter) = io_request->get_filter( ).

DATA(filter_tree) = filter->get_as_tree( ).
IF filter_tree IS NOT INITIAL.
"parse the filter tree using the methods get_root_node, get_children, get_type
and get_value
...

ENDIF.
4.8.4 Using Parameters in an Unmanaged Query
To retrieve data dependent on an entity parameter that is set in the custom entity, you need to implement
a handling for the parameters in the query implementation class. The interface IF_RAP_QUERY_REQUEST
provides a method to get the parameters. It returns a string table with the parameter names and values.
It is up to the application developer how to implement the parameter logic. One option is to implement the
parameters as filter criteria. To use the parameter values as a filter in the WHERE clause of an SQL SELECT
statement, you need to create a filter string from the parameter values.

Develop PUBLIC 927
The interface IF_RAP_QUERY_RESPONSE provides a method to set the filtered data or the filtered total number
of records for the query response after retrieving data from the data source.
Prerequisites
• The custom entity has one or more entity parameters.
 Example
define custom entity /DMO/I_Travel_UQ

with parameters p_start_date : /dmo/begin_date,

p_end_date : /dmo/end_date
• For general prerequisites of an unmanaged query implementation, see Prerequisites Unmanaged Query
[page 919].
The following steps describe the procedure of using parameters as additional filter criteria. The parameters
p_start_date and p_end_date are used as a filter on the elements Begin_Date and End_Date.
1. Call the method get_parameters of the interface IF_RAP_QUERY_REQUEST, which returns a string table
of the parameters and their values.
2. Define default parameter values in case the parameters are not given in the request. The implementation
example uses the system date for Begin_Date and the system date of the following year for End_Date.
3. Define a variable for the filter string and fill it with the filter condition for the SQL WHERE clause on the
element Begin_Date and End_Date and integrate the default values.
 Note
To avoid security risks via SQL string injections, use the method escape_quotes of the public class
CL_ABAP_DYN_PRG.
4. If there are other filter conditions (from filter requests or parameters), concatenate the filter strings with
AND.
source.
Elements UI.

928 PUBLIC Develop
The following codeblock illustrates an implementation for parameters within the select method of
IF_RAP_QUERY_PROVIDER in the query implementation class. Expand the following code sample to view
the source code
 Sample Code
DATA(lt_parameters) = io_request->get_parameters( ).

DATA(lv_next_year) = CONV /dmo/
end_date( cl_abap_context_info=>get_system_date( ) + 365 ) .
DATA(lv_par_filter) = |( BEGIN_DATE >=
'P_START_DATE' ]-value
DEFAULT cl_abap_context_info=>get_system_date( ) ) ) }'| &&

| AND | &&
| END_DATE <=
'P_END_DATE' ]-value
DEFAULT lv_next_year ) ) }' )| .

lv_sql_filter = lv_par_filter.
ELSE.
lv_sql_filter = |( { lv_sql_filter } AND { lv_par_filter } )| .
ENDIF.
INTO CORRESPONDING FIELDS OF TABLE @lt_travel_response
ENDIF.

ENDIF.
 Note
For API information, see Method get_parameters [page 294].
4.8.5 Implementing Search in an Unmanaged Query
To retrieve data according to the search term in the OData request, you need to implement a search logic in
your query implementation class. The interface IF_RAP_QUERY_REQUEST provides a method to get the search
expression from the request.

Develop PUBLIC 929
It is up to the application developer how the search logic is implemented. One option is to use the search
expression as (additional) filter criteria for one or more elements. To use the search expression as a filter in the
WHERE clause of an SQL SELECT statement, you need to create a filter string from the search expression and
combine it with other possible filter strings.
The interface IF_RAP_QUERY_RESPONSE provides a method to set the filtered data for the query response
after retrieving data from the data source.
Prerequisites
[page 919].
• To send query requests with search conditions from a Fiori Elements UI, you need to annotate the custom
entity with @Search.seachable:true.
 Note
The annotation @Search.searchable: true requires using the annotation

@Search.defaultSearchElement: true on at least one element in the custom entity. This
element annotation does not have any influence on the search, as it is up to the application developer
on which element(s) the search logic is implemented.
The following steps provide an example on how to implement the search as a filter for the element
Description. If a filter is also requested, you need to ensure that the SQL filter string has the right syntax for
the SQL SELECT statement.

2. Call the method get_search_expression of the interface IF_RAP_QUERY_REQUEST, which returns a
string of the requested search expression.
3. Create the filter string for the WHERE clause of SQL SELECT statement with the filter for the element
Description.
 Note
To avoid security risks via SQL string injections use the method escape_quotes of the public class
CL_ABAP_DYN_PRG.
4. If there are other filter conditions (from filter requests or parameters), concatenate the filter strings with
AND.
source.

930 PUBLIC Develop
Elements UI.
The following codeblock illustrates the search implementation within the select method of
DATA(lv_search_string) = io_request->get_search_expression( ).

DATA(lv_search_sql) = |DESCRIPTION LIKE '%
{ cl_abap_dyn_prg=>escape_quotes( lv_search_string ) }%'|.
lv_sql_filter = lv_search_sql.
ELSE.
lv_sql_filter = |( { lv_sql_filter } AND { lv_search_sql } )|.
ENDIF.
ENDIF.

ENDIF.
 Note
For API information, see Method get_search_expression [page 296].
4.8.6 Implementing Paging in an Unmanaged Query
To retrieve data in packages, you need to implement paging in the query implementation class. The interface
IF_RAP_QUERY_REQUEST provides a method to get the paging information. It returns an interface instance of
IF_RAP_QUERY_PAGING with two methods for the beginning and the number of records to be retrieved.
The method get_offset defines the number of records that are dropped.
 Note
In accordance to the OData query option $skip, the method get_offset does not return the position
of the first data record to retrieve, but the number of records that are not taken into account before the

Develop PUBLIC 931
retrieval starts. That means, the first line of the data source that is retrieved is the returning value of
get_offset plus 1.
 Note
For retrieving all available data records, the method get_page_size returns the constant
page_size_unlimited of the interface IF_RAP_QUERY_PRAGING. This has to be converted when using
the paging information in an SQL string.
The method get_page_size defines the number of records that are retrieved.
The paging information can then be used in the OFFSET and the UP TO n ROWS clause of the SQL SELECT
statement.
The interface IF_RAP_QUERY_RESPONSE provides a method to set the reduced data records for the query
response after retrieving data from the data source.
Prerequisites
919]
The following steps provide an example on how to implement paging.
1. Call the method get_paging of the interface IF_RAP_QUERY_REQUEST, which returns an interface
instance of IF_RAP_QUERY_PAGING. Use the method get_offset to get the number of records to drop
into a local variable.
2. Call the method get_paging of the interface IF_RAP_QUERY_REQUEST, which returns an interface
instance of IF_RAP_QUERY_PAGING. Use the method get_page_size to get the number of records to
retrieve.
3. Convert the number for infinite numbers of records to be compatible with the definition of the SQL SELECT
statement to retrieve an infinite number.
 Note
The SQL SELECT addition UP TO 0 ROWS retrieves all available data sets.
4. Use the additions OFFSET and UP TO n ROWS in the SQL SELECT to retrieve the data records in packages.
with the reduced data records. The filtered result is then returned to the OData client, for example the SAP
Fiori Elements UI.

932 PUBLIC Develop
The following codeblock illustrates the paging implementation within the select method of

DATA(lv_offset) = io_request->get_paging( )->get_offset( ).
DATA(lv_page_size) = io_request->get_paging( )->get_page_size( ).
DATA(lv_max_rows) = COND #( WHEN lv_page_size =
if_rap_query_paging=>page_size_unlimited THEN 0
ELSE lv_page_size ).).
OFFSET @lv_offset UP TO @lv_max_rows ROWS.

ENDIF.
 Note
It is required to implement a default sort order to return consistent results from the data source. Sorted
results are essential in combination with paging. If you do not provide a default order, the data records for a
certain page might not be consistent.
For API information, see Method get_paging [page 293].
4.8.7 Implementing Sorting in an Unmanaged Query
To retrieve sorted data in an unmanaged query, you need to add sorting criteria to the SQL SELECT statement.
The interface IF_RAP_QUERY_REQUEST provides a method to get the sort element and the sort order for the
request.
The method returns an ordered list of elements with their sort order. If there is more than one sort element,
the sorting priority is in order of appearance. To use the sorting criteria in an SQL SELECT clause, the sorting
criteria has to be transformed into a string that has comma-separated pairs of sort element and sort order.
Whereas abap.bool indicates the sort order for the element descending in the sorted table that you get
from the query request, the sort order must be indicated with the string ascending or descending in the
ORDER BY clause of the SQL statement.
 Example
The string for the SQL select statement must look like element1 ascending , element2
descending, … .
The interface IF_RAP_QUERY_RESPONSE provides a method to set the sorted data for the query response
after retrieving the data records from the data source.

Develop PUBLIC 933
Prerequisites
919].
The following steps provide an example on how to implement sorting criteria.
1. Call the method get_sort_elements of the interface IF_RAP_QUERY_REQUEST, which returns an

ordered list of sort elements with the respective sort direction.
2. Write the elements of the returning value into a string table and map abap.bool to ' ascending' or '
descending' respectively.
3. Concatenate the lines of the string table with comma separation into a string variable.
4. To achieve a consistent result if there is a query request with initial sort order, provide a default sort order,
for example 'primary key'.
5. Use the sort condition in the ORDER BY clause of the SQL select.
with the sorted data. The sorted result is then returned to the OData client, for example the SAP Fiori
Elements UI.
The following codeblock illustrates the sort implementation within the select method of

DATA(sort_elements) = io_request->get_sort_elements( ).
DATA(lt_sort_criteria) = VALUE string_table( FOR sort_element IN
sort_elements
( sort_element-element_name &&
COND #( WHEN sort_element-descending = abap_true
THEN ` descending`
ELSE ` ascending` ) ) ).
DATA(lv_sort_string) = COND #( WHEN lt_sort_criteria IS INITIAL THEN
`primary key`
ELSE
concat_lines_of( table = lt_sort_criteria sep = `, ` ) ).
ORDER BY (lv_sort_string)

ENDIF.
For API information, see Method get_sort_elements [page 294].

934 PUBLIC Develop
4.8.8 Considering Requested Elements in an Unmanaged
Query
You can optimize the performance for your unmanaged query you can add an implementation to retrieve only
the elements that are requested in the OData request. If you do not specify requested element, the query
retrieves the value for every element in the custom entity.
To retrieve only the elements that are requested in the OData request, you need to implement an element
restriction in the SQL SELECT statement. The interface IF_RAP_QUERY_PROVIDER provides a method to get
the requested elements for the request.
To select only the requested element in the SQL SELECT clause, you must transform the requested elements
into a string with comma separations.
The interface IF_RAP_QUERY_RESPONSE provides a method to set the data for the query response after
retrieving the relevant data from the data source.
Prerequisites
919].
The following steps provide an example on how to select only the requested elements from a data source.

2. Call the method get_requested_elements of the interface IF_RAP_QUERY_REQUEST, which returns a
table with the requested elements.
3. Concatenate the lines of the table with comma separation into a string variable.
4. Include the string variable in the SQL SELECT clause to retrieve only the requested elements from the data
source.
with the requested elements. The result is then returned to the OData client, for example the SAP Fiori
Elements UI.
The following codeblock illustrates the implementation to retrieve only the requested elements within the
select method of IF_RAP_QUERY_PROVIDER in the query implementation class.

DATA(lv_req_elements) = concat_lines_of( table = lt_req_elements sep = `,
` ).
@lt_travel_response.

Develop PUBLIC 935

ENDIF.
 Note
For API information, see Method get_requested_elements [page 296].
4.8.9 Implementing Aggregations in an Unmanaged Query
To retrieve aggregate data, you need to implement a logic to retrieve and group data according to the requested
aggregations in the OData request. The interface IF_RAP_QUERY_REQUEST provides a method to get the
aggregation information. It returns an interface instance of IF_RAP_QUERY_AGGREGATION with two methods
to get the elements to be aggregated or grouped.
To select the requested elements according to the requested aggregation, you need to transform the requested
aggregation elements into an aggregation string for the SQL SELECT. The aggregation string must look as
follows:
<AGGR_METHOD> ( <aggr_element> ) as <result_element>
For more information about aggregate functions in SQL expressions, see ABAP SQL -Aggregate Expressions
agg_exp (ABAP Keyword Documentation).
To avoid double selecting the result element, you need to delete it from the list of elements that are requested
as the aggregation string is used in the SQL SELECT together with the other requested elements.
To group the response data by the requested grouped elements, you need to create an SQL string for the SQL
GROUP BY clause.
The interface IF_RAP_QUERY_RESPONSE provides a method to set the aggregated and grouped data for the
query response after retrieving data from the data source.
Prerequisites
[page 919].
• To use aggregation in a Fiori Elements UI and send requests for aggregate values, you need to annotate the
related elements with @Aggregation.default: <aggr_method>.

936 PUBLIC Develop
This procedure combines the implementation of requested elements and aggregation, as both are used in the
select list of the SQL SELECT. The steps also provide an example on how to use the grouped elements in the
SQL SELECT.

2. Call the method get_requested_elements of the interface IF_RAP_QUERY_REQUEST, which returns a
table with the requested elements.
3. Call the method get_aggregation of the interface IF_RAP_QUERY_REQUEST, which returns an interface
instance of IF_RAP_QUERY_AGGREGATION. Use the method get_aggregated_elements, which returns
a list of the elements to be aggregated, their respective aggregation method and the result element for the
aggregated value.
4. Delete the result element from the requested elements.
5. Create the aggregation string for the SQL SELECT with the aggregation method, the element to be
aggregated and the result element.
6. Append the aggregation string to the string of requested elements.
7. Call the method get_aggregation of the interface IF_RAP_QUERY_REQUEST, which returns an interface
instance of IF_RAP_QUERY_AGGREGATION. Use the method get_grouped_elements, which returns a
list of the elements that are requested as group reference.
8. Concatenate the lines of the string table with comma separation into a string variable.
9. Use the requested elements in the select list of the SQL SELECT.
10. Use the string with the grouped elements in the GROUP BY clause of the SELECT statement.
The following codeblock illustrates the implementation for aggregation and grouping select method of

DATA(lt_aggr_element) = io_request->get_aggregation( )-
>get_aggregated_elements( ).
IF lt_aggr_element IS NOT INITIAL.
LOOP AT lt_aggr_element ASSIGNING FIELD-SYMBOL(<fs_aggr_element>).
DELETE lt_req_elements WHERE table_line = <fs_aggr_element>-
result_element.
DATA(lv_aggregation) = |{ <fs_aggr_element>-aggregation_method }
( { <fs_aggr_element>-input_element } ) as { <fs_aggr_element>-result_element }|.
APPEND lv_aggregation TO lt_req_elements.
ENDLOOP.
ENDIF.
DATA(lv_req_elements) = concat_lines_of( table = lt_req_elements sep =
`, ` ).
DATA(lt_grouped_element) = io_request->get_aggregation( )-
>get_grouped_elements( ).
DATA(lv_grouping) = concat_lines_of( table = lt_grouped_element sep =
`, ` ).
GROUP BY (lv_grouping)
@lt_travel_response.

ENDIF.

Develop PUBLIC 937
 Note
 Note
For API information, see Method get_aggregation [page 295].

938 PUBLIC Develop
5 Extend
RAP Extensibility Process and Personas
RAP Extensibility offers the possibility to develop semantically rich, upgrade-safe, and lifecycle-stable
extensions for RAP business objects on each layer of the RAP stack. An original business object developed
by a BO provider is extended with additional functionality to extend the functional scope of the original RAP
BO. Using well-defined extension points enabled in the original business object, an extension provider can then
extend the original data model and behavior in accordance with the business requirements or create their own
business service based on a RAP BO interface.
The overall extensibility process consists of two main parts: The extensibility-enablement in which a RAP BO is
prepared and technically enabled for an extensibility use case. This is done by the extensibility-enabler. Then
the original RAP BO is extended with data model, behavior, or node extensions by the extension provider.
• Extensibility-Enabler: The extensibility-enabler is a developer who technically enables an existing RAP

BO and defines the available extensibility options for the extension provider. You can find the relevant
information for this persona in the chapter RAP Extensibility-Enablement [page 949].
• Extension Provider: The extension provider is a developer who extends an original RAP BO with data
model or behavior extensions, as well as node extensions. You can find the relevant information for this
persona in the chapter RAP Extensions [page 978].
RAP Extensibility Big Picture

Extend PUBLIC 939
Generally, the RAP extensibility architecture is based on an Opt-in approach to provide fine-granular control
over which parts of a business object can be extended. This means, that every possible extension point must
be defined explicitly in the corresponding development objects in the data model and the behavior definition
and implementation. Once enabled, every BO layer can be extended with one or several extensions from
extension provider side. In addition, the extensibility architecture ensures a separation of concerns between
original BO elements and extensions to limit technical dependencies to public and well-defined extension
points. This guarantees lifecycle-stability and upgrade-safety that is also checked and technically enforced by
the RAP framework.
Extension providers can extend RAP BOs and their services on-stack or develop and expose their own services
based on released RAP BO interfaces.

940 PUBLIC Extend
Extensibility Use Cases
Extensibility Use Cases

Extensibility Use Case Extensibility Persona Background Information
Data Model Extension: Build full-stack Extensibility-Enabler: Adds annota- • For more information about ena-
data model extensions by adding new tions and extension include structures
bling full-stack data extensibility,
fields and associations including corre- to the original RAP BO to enable data
see Extensibility-Enablement for
sponding behavior characteristics and model extensions.
authorization control. CDS Data Model Extensions [page
952].
• For an implementation example,
see Enabling Data Model Exten-
sions [page 963].
Extension Provider: Extends the origi- • For more information about how
nal RAP BO with new fields or associa- to develop data model extensions,
tions including field characteristics de- see CDS Data Model Extensions
pending on the options defined by the [page 979].
extensibility-enabler.
see Develop Data Model Exten-
sions [page 991].
Behavior and Field-Related Behavior Extensibility-Enabler: Enables data • For more information about en-
Extensions: Build additional behavior model extensibility and behavior exten-
abling your BO for behavior ex-
like new validations, determinations, or sibility on the original RAP BO.
tensions, see Extensibility-Enable-
actions including dynamic feature con-
trol and other field-related behavior. ment for Behavior Extensions
[page 958].
see Enabling Non-Standard Behav-
ior and Field-Related Behavior
[page 971] and Enabling Standard
Behavior Extensions [page 973].
Extension Provider: Extends the origi- • For more information about how
nal RAP BO with new validations, deter-
to develop different behavior ex-
minations, or actions depending on the
tensions, see Behavior Extensions
options defined by the extensibility-en-
abler. [page 981].
see Develop Behavior Extensions
[page 995].
Node Extensibility: Build additional BO Extensibility-Enabler: Enables node ex- • For more information about node
nodes with own behavior and data tensibility on the original RAP BO.
extensibility enabling, see Extensi-
model with node extensibility.
bility-Enablement for Node Exten-
sibility [page 960].
see Enabling Node Extensions
[page 975].

Extend PUBLIC 941
Extensibility Use Case Extensibility Persona Background Information
Extension Provider: Extend the original • For more information about how to
BO with new nodes that have their own
develop node extension, see Node
data model and behavior.
Extensions [page 985].
About RAP Extensibility [page 942]

This topic gives you an overview of the RAP extensibility architecture, extension development artifacts
and all available extensibility features.
RAP Extensibility-Enablement [page 949]

This section explains the concepts of how to enable a custom RAP BO for extension development.
RAP Extensions [page 978]

This section explains the concepts of how to extend an original RAP business object with data model
extensions, behavior extensions and node extensions.
5.1 About RAP Extensibility
This topic gives you an overview of the RAP extensibility architecture, extension development artifacts and all
available extensibility features.
Extensibility enables application consumers to adapt business requirements and processes of existing
applications using RAP extensions. The extensibility options in RAP are designed for lifecycle-stability and
a separation of concerns between the original BO and its extensions. Extensions themselves are self-contained
and are always RAP managed for both managed and unmanaged BOs.
By default, a RAP BO is not extensible and requires extensibility enablement on part of the original BO
provider to allow extensions at dedicated extension points. The extension points can be controlled on a on a
fine-granular level to give full control over which parts of a BO can be extended with what kind of extension.
Once a RAP BO has been enabled for extensibility, an extension provider can add different types of extensions
to enhance the original data model and behavior. Extension providers can only define extension fields and
behavior that the original BO is enabled for. Defining other behavior or field types that the original BO isn´t
enabled for leads to a syntax error in the extension BDEF and the corresponding data model extension objects.
From the perspective of the consumer, extensions are fully integrated into the BO runtime and design time
and act as a whole even though extensions are self-contained and can only define behavior specifically for
extension elements and operations. They can not redefine any behavior for any elements of the original BO.
For an architecture overview, see Extensibility Architecture Overview [page 948] .
Relation Between the Original BO and Extensions
Extensions are self-contained and can only refer to elements from the original BO and elements defined in the
extension itself. All derived types and method signatures are automatically extended to include the extension
elements in the structures and method signatures. An extension inherits the authorizations from the original

942 PUBLIC Extend
BO: If an original RAP BO defines authorization (global, instance), this is automatically inherited by
the extension where the extension provider can then implement global and instance authorization for elements
of the extension.
 Example
If a BO interface has several extensions, a projection A can reference an element from BDEF
extension B and BDEF extension C, if they both apply the BO interface I_interface..
Extension behavior characteristics and operations behave like they do in the original BO. For example, so
there's no difference between an original validation or an extension validation at runtime or design time. In both
cases, the RAP framework manages the runtime orchestration for defined trigger conditions in the same way.
For an overview of all available extensibility features, see Extensibility Feature Overview [page 944].
From the consumer's perspective, extensions are considered an implementation detail of the respective RAP
BO. There's no way to differentiate if an element is part of the original BO or an extension. The BO is always
consumed as a whole, including all its extensions that apply a particular BO interface. From original BO
perspective, an extension acts as external consumer. The RAP BO runtime differentiates in local mode for
elements of the original BO or extension elements.
 Example
If BDEF extension B contains an action with the name sampleAction (features:instance) ,

the BDEF extension C can not define an action with the same name. Additionally, it's not possible
to redefine SampleAction (features:instance) in BDEF extension C with additional or different
behavior.
For more information, see Behavior Extensions [page 981].
Extensibility Lifecycle-Stability and Dependencies
The lifecycle-stability of RAP extensions is decoupled from the technical architecture. The stability for
extensions is achieved by releasing dedicated development objects as released API (a so-called Release
Contract) in the respective language version. Depending on the underlying release contract, the respective
development objects undergo additional compatibility and consistency checks that ensure lifecycle-stability
between dependent objects. They also impose general restrictions on the development object to avoid
incompatible changes in the future. The lifecycle-stability of a RAP BO and its extension essentially relies
on the following release contracts for extensibility-enablement and consumption:
• Extend (C0): The Extend release contract with the visibility Use in Cloud Development is required
as a basis for extensibility-enablement for all development objects in a RAP stack. If you want to release
a database table, a CDS view or a behavior definition for the Extend release contract, the relevant
development object must be enabled for extensibility as a prerequisite. Depending on the development
object, additional technical requirements must be met before stable extension points can be defined. For
more information, refer to .
• Use System-Internally (C1): The Use System-Internally (C1) release contract with the visibility
Use in Cloud Development is required for all development objects intended for consumption. You can
only access objects released for Use System-Internally (C1) in your implementations. Accessing
unreleased objects results in a syntax error. After releasing a development object for this release contract,

Extend PUBLIC 943
restrictions and checks on further changes are imposed. For example, you can not delete elements used in
extensions or you can not make additions to the implementation that would result in incompatible changes
and possible upgrade issues. For more information regarding the C1 release contract, refer to .
The combination of both release contracts ensures that extension points and extensions remain stable and
consistent during upgrades and lifecycle changes.
Extensibility for Released Business Objects
Released business objects can be used for building extensions that fit customer-specific requirements. If an
SAP RAP business object is released for consumption and extension, the business object interface is always
released with the release contract C1 to ensure stability for customer extensions. Consequently, all extensions
built on a released BO interface inherit the C1 release contract and its resulting limitations on future changes.
Furthermore, behavior extensions can only refer fields and associations in their implementations belonging to
the same namespace and/or software component . Fields from the original BO can only be used in contexts
where the field itself is not modified, e.g., as part of a trigger condition.
For more information about how to build extensions for a released business object, see RAP Extensions [page
978]. For information about how to consume released business objects in your behavior implementation, refer
to Consume [page 1085] .
Extensibility Feature Overview [page 944]

This topic gives you an overview of all available extensibility features.
Extensibility Architecture Overview [page 948]
5.1.1 Extensibility Feature Overview
This topic gives you an overview of all available extensibility features.
Extensibility-Enabler Feature Overview
This table gives you an overview of all available features for extension-enabler in an extensibility scenario. You
can find the following information:
• Feature: This column lists the available features.

• Available for Implementation Types: Not all implementation types can be enabled for all extensibility
options. This column lists for which implementation types a feature is available.
• Further Information: This column provides links to further conceptual information or implementation
examples.

944 PUBLIC Extend
Feature Available for Implementation Type Further Information
Enable the original RAP BO for node ex- • Managed • About extensibility-enablement
tensibility. for extension nodes: Extensibility-
Enablement for Node Extensibility
[page 960]
• Example for node extensibility-
enablement: Enabling Node Exten-
sions [page 975]
Enable the original data model for data • Managed • About extensibility-enablement
model extensions. • Unmanaged for data model extensions: Exten-
sibility-Enablement for CDS Data
Model Extensions [page 952].
• Example for data model extensi-
bility-enablement: Enabling Data
Model Extensions [page 963]
Enable extensibility for nonstandard • Managed • About extensibility-enablement

and field-related behavior like actions • Unmanaged for behavior: Extensibility-Enable-
and functions or dynamic feature con- ment for Behavior Extensions
trol. [page 958].
• Example for nonstandard and
field-related behavior extensibil-
ity-enablement:: Enabling Non-
Standard Behavior and Field-Re-
lated Behavior [page 971]
The extensibility-enablement for data

model extensions is a prerequisite for
nonstandard and field-related behavior.
For more information, see Extensibility-
Enablement for CDS Data Model Exten-
sions [page 952]
Enable extensibility for standard behav- • Managed • About extensibility-enablement

ior like determinations and validations • Unmanaged for behavior: Extensibility-Enable-
or unmanaged save. ment for Behavior Extensions
[page 958].
• Example for standard and un-
managed save extensibility-ena-
blement:: Enabling Standard Be-
havior Extensions [page 973]
Extension-Provider Feature Overview
This table gives you an overview of all available features for extension-providers in an extensibility scenario. You
can find the following information:

Extend PUBLIC 945
• Feature: This column lists the available features.
• Required Extensibility-Enablement: All extensibility features depend on the enabled extensibility options
in the original RAP BO. This column lists the required extensibility-enablement for the respective feature.
• Further Information: This column provides links to further conceptual information or implementation
examples.
Required Extensibility-Ena-
Feature Extensibility Scenario blement Further Information
Extend field mapping for ex- • Field Extensibility The field mapping in the orig- • Creating Extension
tensions fields in your BDEF inal RAP BO must be defined Fields: CDS Data Model
extension. as extensible. Extensions [page 979]

Extensibility-Enablement for
Behavior Extensions [page
958].
Add new extension fields to • Field Extensibility The data model must be en- • Creating new extension
an original RAP BO data abled for data model exten- fields: CDS Data Model
model. sion to allow adding new ex- Extensions [page 979]
tension fields to the original • Creating new behav-
data model. ior for the extensions
fields: Behavior Exten-
sions [page 981] and
Develop Behavior Exten-
CDS Data Model Extensions
sions [page 995]
[page 952]
Add new extension actions or • Behavior Extensibility Adding new functions and • About actions and
extension functions.
actions requires enabling functions: Nonstandard
the base BDEF with Operations [page 101]
extensible and defining • Creating new behavior
at least one node as extensions: Develop Be-
extensible. havior Extensions [page
995].
958]

946 PUBLIC Extend
Add new extension determi- • Behavior Extensibility Adding new determinations • About determinations
nations and validations with
and validations requires ex- and validations: Deter-
their respective trigger con-
plicit enablement in the orig- minations [page 119]
ditions in a BDEF extension.
inal behavior definition. Only and Validations [page
behavior and trigger condi- 123].
tions specified in the BDEF • Creating new extension
header can be added in a be- validations or determi-
havior extension. nations: Develop Behav-
ior Extensions [page
For more information, see 995].
958]
Add extension validations • Behavior Extensibility The original RAP BO • Add determinations
and determinations to an ex-
must be draft-enabled. and validations to
tension of the determine ac-
The draft determine action Prepare example: De-
tion Prepare.
Prepare must be defined velop Behavior Exten-
as extensible. sions [page 995].
• About determine ac-
tions: Determine Ac-
tions [page 127].
958].
• State Messages : State
Messages [page 268].
Add new extension deter- • Behavior Extensibility The original RAP BO must • About determine ac-
mine actions.
be draft-enabled and enabled tions: Determine Ac-
for behavior extensions. tions [page 127].

958].
Define and implement an • Behavior Extensibility The original BDEF must be • About with
additional save in enabled for behavior exten- additional save:
your extension.
sions and additional Defining Unmanaged
save. Save in the Behavior
Definition [page 450]
958]

Extend PUBLIC 947
Add a business event in your • Behavior Extensibility The original RAP BO must be • About RAP business
behavior extension.
enabled for additional events: Business Events
[page 135].
save.

958].
Add a new extension node • Node Extensibility The original RAP BO must be • Node Extensions: Node
to an original RAP BO data
enabled for node extensibil- Extensions [page 985].
model.
ity. • Develop new extension
nodes: Develop Node
Node Extensibility [page
960].
5.1.2 Extensibility Architecture Overview
Depending on which part of business object is extended, different development artifacts are used to store the
extensions for the data model, the behavior, or the service definition. The required extension artifacts depend
on the individual use case. For an overview of extension options and use cases, refer to RAP Extensions [page
978].
The RAP extension artifacts store all extensions to the different parts of a business object from the data model
extension to the service definition in a full-stack extension scenario. The individual artifacts ensure that only
previously defined and stable extension points can be extended.
The following graphic gives you an overview of all extension development objects throughout the stack of a RAP
BO. The depicted architecture is recommended if you want to make use of release contracts in your BO. Each
layer in the stack can be extended with the respective extension artifacts:
• Database Tables: Database tables are extended with Database Extends. A C0 extension include
structure is included in draft and active database tables. These extension include structures
can then be extended with the actual database extends from a BO extension provider. This indirect
EXTENSION architecture ensures that the C0 release contract requirements are decoupled from the
original database tables.
• CDS Views: CDS Views are extended with CDS View Extends. The corresponding original artifact for CDS
View Extends is released for C0 if release contracts are used and for released RAP BOs.
• Behavior Definitions: BDEFs are extended with Behavior Definition Extensions. The BDEF
extensions for the base layer can include additional behavior extensions for nodes of the original BO or
define new behavior for extension nodes. The BDEF extension on projection layer can only expose behavior
defined on the base layer or define new behavior that doesn't require an implementation class.

948 PUBLIC Extend
• Service Definition Extension: A service definition extension is required to expose an extension node in an
OData Service.
5.2 RAP Extensibility-Enablement
This section explains the concepts of how to enable a custom RAP BO for extension development.
About Extensibility-Enablement
Since RAP extensibility is based on an opt-in approach, all possible extension points in the stack have to be
explicitly enabled for a RAP BO.
That means that all development objects, like database tables, CDS views, behavior definitions, and behavior
projections must be explicitly enabled for extensibility before the respective RAP BO can be extended by an
extension provider. The RAP BO provider has full control over which parts of a RAP BO are extensible. The only
exceptions are BO interfaces that are required for behavior and field-related behavior extensions. Other
than the keyword extensible, BO interfaces don't require any specific enablement: They merely serve as
a consolidated consumption view of the base BO and always reflect the extensibility-enablement level of the
base layer. When a BO interface is used in an extension, the extension behavior of the nodes from the base
RAP BDEF is added implicitly to the BO interface. For more information about the implicit extension of BO
interfaces, see Business Object Interface [page 194].

Extend PUBLIC 949
Extensibility-Enablement for Different Implementation Types with or without
Draft Capabilities
The specific enablement steps depend on the implementation type of a RAP BO and whether a BO has draft
capabilities or not.
The enablement steps are similar for managed and unmanaged RAP BOs:
1. Data Model Extensibility Enablement: Define the technical extension points and extension possibilities in
the respective artifacts, e.g. prepare a database table for extension by adding an extension include
in active and draft tables and defining the technical properties by means of annotation of the extensions,
like which extensions are possible and what is the maximum number of available fields. For details, see
Extensibility-Enablement for CDS Data Model Extensions [page 952].
2. Behavior Extensibility Enablement: Define the BDEF as extensible and specify the behavior extension
scope available for extension providers, like validations on save, determinations on modify,
determinations on save and additional save . For details, see Extensibility-Enablement for
Behavior Extensions [page 958].
3. Node Extensibility Enablement: Define the annotation
@AbapCatalog.extensibility.allowNewCompositions in all CDS view entities throughout the stack
to enable adding new toParent/Child compositions. Define the base BDEF as extensible to allow
adding the behavior for the extension node. For details, see Extensibility-Enablement for Node Extensibility
[page 960].
4. Release for Extend (C0) Release Contract: This release contract ensures the stability of the extension
point with additional checks for the extension provider and RAP BO consumer. This release contract
inhibits incompatible changes to extension points. Note that it's mandatory to use the highest available
strict level, if you want to release your development objects for this release contract.
For more information about the Extend (C0) release contract, see .
5. Use System-Internally (C1) (Consumption Enablement): The C1 release contract is required for all
development objects intended for consumption or use in the behavior implementation. With ABAP for
Cloud Development, development objects released for Use System-Internally (C1) can only
consume objects released for the same release contract and visibility in your implementations. If you try to
access non-released objects, a syntax error occurs. With the release for Use System-Internally (C1),
restrictions and checks on further changes are imposed to ensure end-to-end stability for consumers: For
example, you can't delete elements or you can't make additions to the implementation that would result in
incompatible changes and possible upgrade issues. For more information, refer to .

950 PUBLIC Extend
Development Objects with Release Contracts Overview
The following diagram gives an overview of app development artifacts and their release contract. If you want to
use, release contract in your BO this is the recommended architecture that is also valid for released RAP BOs:
For a detailed description, see Extensibility Architecture Overview [page 948].
Extensibility-Enablement Target Overview
The following overview shows the extensibility-enablement throughout the stack of a generic RAP BO. The
depicted extensibility-enablement model enables the RAP BO for field and behavior extensions, as well as node
extensibility.
• Data Model: The data model consisting of database tables and CDS Views is extensibility-enabled with the
required technical properties and released for the C0 release contract. This enables field extensibility and
allows the addition of extension fields to the database tables. It also allows the extension of the CDS data
model with fields and associations from extension provider side.
For more information about the extensibility-enablement for the data model for extension fields, see
Extensibility-Enablement for CDS Data Model Extensions [page 952] .
• Behavior: The behavior definition is defined as extensible and the general extensibility scope that
specifies which behavior extensions are possible is defined. The individual BO entities are defined as
extensible to define to which BO entities the behavior extension scope can be applied to. The BDEF is
released for the C0 release contract to ensure the stability of the defined extension points.
For more information about extensibility-enablement for the behavior of a RAP BO, see Extensibility-
Enablement for Behavior Extensions [page 958].

Extend PUBLIC 951
• Service Extensions: For adding extension BO entities, the service definition is defined
as extensible and released for the C0 release contract. You've included the annotation
@AbapCatalog.extensibility.extensible: true to enable extensibility. Node extensibility also
requires extensibility-enablement throughout the stack to be able to add the required associations at the
appropriate extension points.
For more information about extensibility-enablement for node extensibility, see Extensibility-Enablement
for Node Extensibility [page 960].
Learn about Extensibility-Enablement [page 952]
Develop Extensibility-Enablement [page 962]
5.2.1 Learn about Extensibility-Enablement
This section offers you conceptual background about extensibility-enablement for different enablement use
cases.
Extensibility-Enablement for CDS Data Model Extensions [page 952]
Extensibility-Enablement for Behavior Extensions [page 958]
Extensibility-Enablement for Node Extensibility [page 960]
5.2.1.1 Extensibility-Enablement for CDS Data Model

Extensions
Enabling Extensibility for Field and Association Extensions
 Note
A prerequisite for the extensibility enabling of your CDS data model is the use of CDS View Entities.
You can enable your data model, so that extension providers can add additional fields and associations to the
CDS data model and expose them in a business service. The enabling approach focuses on separating the
dedicated extension points from the modeling details of the respective tables and CDS views: To achieve this
separation of concerns, the data model extensibility is based on extension include structures for the database
tables and extension include CDS views for the CDS data model.

952 PUBLIC Extend
The following graphic shows a draft-enabled root node with one subnode including all development objects
relevant for the extensibility-enabling of the CDS data model:
Enabling your data model for extensibility consists of the following parts:
1. Extensibility-Enabling for Database Tables [page 953]

2. Extensibility-Enablement for CDS Views [page 955]
5.2.1.1.1 Extensibility-Enabling for Database Tables
Database Table Enablement Architecture
To allow adding extension fields to a RAP BO, the same extension include structure is added to the active
and also the draft table in case of a draft-enabled RAP BO. This achieves a separation of concerns between
extension elements and the original databases: The extension include structure serves as abstraction layer
between the extension fields and the base BO database tables to limit the stability requirements of the Extend
C0 release contract to the extension include structure and guarantee full flexibility with regards to enhancing
the original database tables later:

Extend PUBLIC 953
Technically, it's possible to extend the database table directly. In this case, the database table itself must be
Extend C0 released with visibility Extend in Cloud Development. However, to maintain flexibility and
separation of concerns, this is only recommended for simple data models.
In unmanaged RAP BOs, this extension includes are required throughout the legacy ABAP application to be
able to persist the extension field values on the database. Make sure to use MOVE-CORRESPONDING to transfer
the extension field values in your application stack.
Basic Extensibility-Enablement for Extension Type, Suffix, and Quota

Enablement
Extensibility-Type-Enablement
The annotation @AbapCatalog.enhancement.category determines if and how a database table or
structure can be extended. You can define, for example, if a structure can only be extended with character-type
fields.
• #EXTENSIBLE_ANY: All kinds of extension types are allowed for the structure or table (e.g. deep types).
• #EXTENSIBLE_CHARACTER: Only character-like extension types are allowed.
• #EXTENSIBLE_CHARACTER_NUMERIC: Only character and numeric like extension types are allowed.
• #NOT_EXTENSIBLE: No extensions are allowed.
Field Suffix-Enablement
The extensibility field suffix is defined with the annotation @AbapCatalog.enhancement.fieldSuffix. This
annotation allows you to avoid field naming conflicts. All fields included in an extension need to end with the
given field suffix. The field suffix should be unique, but this isn't technically enforced. Note that you can only
add one extension-include structure for every BO node.
 Example
If you've defined @AbapCatalog.enhancement.fieldSuffix: 'XX', all fields included in the

extensions must end with the specified suffix like in this case with SAMPLE_EXT_FIELD_XX. If the field
name was defined as SAMPLE_EXT_FIELD without the specified suffix, an error will occur when release
contracts are used.
Extension-Quota-Enablement
You can use the @AbapCatalog.enhancement.quotaMaximumFields annotation to limit the
number of extension fields that can be added by an extension provider. The annotation
@AbapCatalog.enhancement.quotaMaximumBytes allows you to define a maximum byte capacity that
is reserved for extension providers.

954 PUBLIC Extend
Quota Definition for different Consumer Groups
The Quota definition shares are used to assign the reserved field counts / byte capacity to a dedicated
consumer group.
 Note
For database tables and structures, a quota share of 50% for both parties is technically enforced.
Currently, there are two different consumer groups:
• • Partner Development: The partner quota share is defined with the annotation
@AbapCatalog.enhancement.quotaSharePartner.
• Customer Development: The customer quota share is defined with annotation
@AbapCatalog.enhancement.quotaShareCustomer.
This allows you to assign more or less space for dedicated consumer groups. It’s also possible to prevent the
creation of extensions for a dedicated consumer group.
Release for Stability Contract
After you've defined the possible extension types, as well as extensibility quotas if necessary, you can release
the extension include structure for the C0 Extend stability contract.
For information about the C0 Extend, see .
Parent topic: Extensibility-Enablement for CDS Data Model Extensions [page 952]
Next: Extensibility-Enablement for CDS Views [page 955]
5.2.1.1.2 Extensibility-Enablement for CDS Views
The extensibility-enablement for CDS views is based on an opt-in approach allowing for full control of possible
extensions and quantity of extensions. By using annotations, you can define whether the addition of new data
sources or compositions is allowed or not.
CDS-Enabling Architecture
The following graphic shows the best practice architecture throughout the CDS data model with an example
extension field that extends the data model for a RAP BO with draft.
To develop a robust CDS architecture for extensions, an extension include view is used. This limits the
constraints resulting from the Extend (C0) release contract to the E_View and R_View, while the CDS View
stack below the R_View can still be changed flexibly. The extension include view E_View is associated to the
original R_View and selects from the original database bypassing the view stack below the original R_View .

Extend PUBLIC 955
The model contains a CDS view Draft_Query_View, because the BO is draft-enabled. The draft query view
is used in the corresponding behavior definition to read the content directly from the draft table. Since the
extension include structure is included in both tables, the E_View and the Draft_Query_View must be
extended to add the extension field to the data model.
Every CDS view that is later extended with extension fields and associations must be enhanced with the
respective annotations before the CDS View can be released for Extend (C0). These CDS views are then
extended throughout the stack with extensions fields and associations by the extension provider.
For more information about the syntax, see ABAP CDS - Extending CDS Views (ABAP- Keyword
Documentation).
Draft Query Views in BOs with Draft
Specifying a draft query view in the behavior definition is mandatory if the BO is draft-enabled and you want to
use the Extend (C0) for your RAP BO.

956 PUBLIC Extend
Basic Extensibility-Enablement for the Data Model
The data model needs to be enhanced with extensibility annotations that define the type and scope of possible
extensions for extension providers. These annotations are prerequisites if you want to release the CDS views
for the Extend (C0) release contract.
Basic Extensibility Enablement
 Note
If the annotation isn't set at all, the CDS View entity is considered extensible by default.
The CDS views need to be defined as extensible to enable any kind of extensions. The annotations
@AbapCatalog.extensibility.extensible must be set to true. Optionally, for CDS Views, the
annotation @AbapCatalog.viewEnhancementCategory can also be used. For node extensibility, the
annotation @AbapCatalog.extensibility.allowNewCompositions: true is a mandatory prerequisite.
Displaying Extension Elements on the UI

You need to define the annotation @Metadata.allowExtensions: true on the projection layer of your RAP
BO, so that the extension elements can be added to UI with metadata extensions.
Suffix Enablement
The CDS Entity needs to define an element suffix, which needs to be used by extension fields and
associations. The annotation @AbapCatalog.extensibility.elementSuffix allows you to define a suffix.
If an extension association doesn't use the Suffix, a syntax error occurs.
Quota Enablement
The CDS Entity needs to define a quota definition, which specifies capacity for extension
content. The annotation @AbapCatalog.extensibility.quota.maximumFields enables you
to define the maximum number of possible extension fields and with the annotation
@AbapCatalog.extensibility.quota.maximumBytes, you can define a maximum byte capacity that is
reserved for extension providers. Both annotations are obligatory if you want to release the datasource for C0.
Stable Data Sources Enablement

It's required to define stable aliases for associations contained in the original CDS view to ensure stability for
consumers. The aliases can't be changed after a CDS view has been released for a release contract. You can
use the annotation @AbapCatalog.extensibility.dataSources to define the respective aliases.
Extension Data Sources and Compositions

An original data source must be explicitly enabled for new associations, new data sources and compositions.
If that's not the case, no new data sources or compositions can be introduced to the data model. The
annotations @AbapCatalog.extensibility.allowNewDatasources allows you to add new data sources.
These data sources need to comply with the respective stability requirements.
The annotation @AbapCatalog.extensibility.allowNewCompositions allows you to enable the data

model for new compositions. This is a mandatory requirement if you want to enable node extensibility. For
more information about node extensibility enablement, see Extensibility-Enablement for Node Extensibility
[page 960].

Extend PUBLIC 957
For more information about what to take into account when introducing extension associations or
compositions, see CDS Data Model Extensions [page 979].
Release for Release Contract
After you've defined the possible extension possibilities, as well as extensibility quotas if necessary, you can
release the CDS Views in the data model for the Extend (C0) release contract.
For information about the Extend (C0), see .
Field Mapping
Extension fields need to be mapped in an extension of the field mapping. Thus, the field mapping enablement is
required for extension fields. For more information, see Extensibility-Enablement for Behavior Extensions [page
958]
Parent topic: Extensibility-Enablement for CDS Data Model Extensions [page 952]
Previous: Extensibility-Enabling for Database Tables [page 953]
5.2.1.2 Extensibility-Enablement for Behavior Extensions
Behavior extension-enablement allows an extension provider to enrich the original BO with additional behavior.
The following use cases can be covered with behavior extensibility:
• Field-Related Behavior Extensions: Extension providers can add additional behavior to extension fields
like static or dynamic feature control. This use case only requires basic behavior enablement. This
automatically enables extensibility for actions and functions..
 Note
As a prerequisite, the data model of the BO must be extensibility-enabled. For more information, see
Extensibility-Enablement for CDS Data Model Extensions [page 952].
• Behavior Extensions: Extension providers can add additional behavior like validations or determinations.
This use case requires basic behavior enablement and extensibility-enablement for behavior extensions.
For more information, see Extensibility-Enablement for CDS Data Model Extensions [page 952] and
Extensibility-Enablement for Behavior Extensions [page 958].

958 PUBLIC Extend
Behavior Extension-Enablement Architecture
Offering the possibility for behavior extensibility in a homogeneous and lifecycle-stable way requires
extensibility enabling for the corresponding BDEF and the projection BDEFs in which the behavior and
extension behavior is defined. Another prerequisite is a BO interface and the use of strict(2). For more
information, see Strict Mode [page 184] and Business Object Interface [page 194].
The opt-in approach allows you fine-granular extensibility enabling on all levels of a RAP BO. The following
graphic shows a fully enabled BDEF architecture and uses an action as a behavior extension example to show
how an extension is then propagated throughout the entire stack.
Enablement in the Original BDEF
In the BDEF header, you can define whether the BDEF is extensible overall by adding the keyword extensible
to the header. Furthermore you can specify whether validations and determinations and with which trigger
conditions can be added to the entity extension behavior. It's not possible to add determinations or validations
with trigger conditions to a BDEF extension, if it's not defined in the BDEF header. This leads to a syntax error in
the BDEF extension.
 Example
Using the example above, you could add for example a validation on save to the Root entity node.
On entity behavior definition level, you can define for each individual entity node whether it's extensible or not.
The determinations and validations with their trigger conditions defined after extensible in the BDEF header
apply to all entity nodes defined as extensible.

Extend PUBLIC 959
If the original BDEF is draft-enabled and managed, you can define determine actions and the determine
action Prepare as extensible. This is recommended in case you have enabled your BO for validations,
since adding validations to the determine action Prepare is required for processing state messages. For more
information about state messages, see State Messages [page 268].
Furthermore, you can define the field mapping as extensible which is required for extension fields and their
mapping.
For more information about the syntax and the individual options, see CDS BDL - Extensibility Enabling for RAP
BOs (ABAP- Keyword Documentation).
Enablement in the BO Interface
You can define whether a BDEF interface is extensible by adding extensible to the header. The BDEF
interface then implicitly inherits the extension properties defined in the original BDEF, and no further enabling
is required on this level.
Enablement in the BDEF Projection
You can define whether a BDEF projection is extensible by adding extensible to the header.You can enable
each entity node individually as extensible, but at least one node must be defined as extensible.
An extension provider can then expose extension behavior defined for the base BO in a BDEF projection
extension. However, it's not possible to add behavior on the projection level that requires an implementation
class.
For more details about the syntax and the individual elements, see CDS BDL - Extensibility Enabling for CDS
Projection BDEFs (ABAP- Keyword Documentation).
5.2.1.3 Extensibility-Enablement for Node Extensibility
With node extensibility enablement, extension providers can add their own extension node to a data model,
including its own data model and behavior.
Node Extensibility Architecture
In this use case, the extension provider wants to add an additional child node with data model and behavior to
an original BO and define behavior for that node in a BDEF extension.
To establish the relationship between root node and extension node, the extension provider must introduce a
new composition to the data model. Thus, the association target ( in this case the root node ) must be enabled
to allow new compositions with the corresponding annotation as described in Extensibility-Enablement for
CDS Views [page 955]. The BDEF must be enabled to add the extension node, and in the last step, the
service definition requires extensibility enabling, since the extension node needs to be exposed for service
consumption.

960 PUBLIC Extend
Prerequisite: Extension Node
 Note
As extension provider, you must use ancestor associations to support locking, authorization, and etag
handling later on in the BDEF. For more information about ancestor associations, see Node Extensions
[page 985].
As a prerequisite, the extension provider has defined an additional node with its own data model and behavior
that is to be included in the existing data model. The data model described here is described in more detail in
Node Extensions [page 985], however the data model of the extension node is not relevant for the enablement
itself.
Enabling the Data Model and Behavior

The original data model is enabled for to-parent-associations/compositions by using the annotation
@AbapCatalog.extensibility.allowNewCompositions in the CDS views R_View, I_View and C_View.
This allows the extension provider to create the required composition in a CDS View extension. The
R_View_BDEF is enabled for extension with the keyword extensible in the header, and no further
enablement is required on node level. This allows the extension provider to define behavior for the extension
node in extend 'R_View_BDEF’ and reuse the behavior in the BDEF projection extend 'C_View_BDEF’
The following graphic shows the enablement throughout the data model:
Enabling the Service Definition

The service definition is enabled by adding the annotation @AbapCatalog.extensibility.extensible:
true to the header. This allows the extension provider to create a service definition extension for the extension
node.

Extend PUBLIC 961
 Sample Code
...

@AbapCatalog.extensibility.extensible: true
define service ExtNodeService {
expose R_View as Root;
...

}
5.2.2 Develop Extensibility-Enablement
This section offers how-to information and implementation examples for extensibility enabling a RAP BO.
Reference Scenario
We use an example from the ABAP Flight Reference Scenario to show how to enable a business object for
different extensibility use cases. In this example, we work with the business object from the package /DMO/
FLIGHT_REUSE_AGENCY that can be used for the administration of agency master data like agency names and
addresses.
 Note
The following sub packages of the package /DMO/FLIGHT_REUSE_AGENCY contain the artifacts to be
developed by the extender of the business object as described in chapter Develop RAP Extensions [page
990]:
• /DMO/FLIGHT_REUSE_AGENCY_SLOGN
• /DMO/FLIGHT_REUSE_AGENCY_CNTRY
• /DMO/FLIGHT_REUSE_AGENCY_REV
For practical reasons, the extension artifacts in these packages are shipped within the same software
component as the artifacts of the original business object itself, thus making release contracts obsolete.
In a productive environment, the extension artifacts don't belong to the same software component as the
original business object, which is why the artifacts of the original business object require release contracts
in order to be consumable and extendable from another software component. During the course of the
following enablement guide, the artifacts that require release contracts for cross-component access are
pointed out respectively. The artifacts of the /DMO/ reference content themselves, however, are shipped
without release contracts for maintenance reasons.
Extensibility Enablement Scenarios
The following guide is structured by the different extensibility use cases and guides you through the
enablement processes required respectively.

962 PUBLIC Extend
Enabling Data Model Extensions [page 963]
In the following section, you will enable our reference business object /DMO/R_AgencyTP for data
model extensions that allow extenders to add new elements to the business object.
Enabling Non-Standard Behavior and Field-Related Behavior [page 971]

This chapter guides you step-by-step on how to enable a business object for actions and functions as
well as for static and dynamic feature control extensions for new fields.
Enabling Standard Behavior Extensions [page 973]

To allow the extender to add validations, determinations and additional save implementations, you
need to enable these operations in the behavior definition of your business object.
Enabling Node Extensions [page 975]

To allow extenders to add their own extension node to the data model, you need to enable node
extensions in the original business object.
5.2.2.1 Enabling Data Model Extensions
In the following section, you will enable our reference business object /DMO/R_AgencyTP for data model
extensions that allow extenders to add new elements to the business object.
Required Enablement Steps
Data model extensions affect the whole stack of a business object. Hence you will extensibility-enable the
database layer as well as every involved layer of the CDS data model. In order to retain flexibility for the original
business object and the stability of extensions, you will develop dedicated extension points which decouple the
business object from the data model extension artifacts on the respective layers.
For more information and the whole picture of the CDS-enabling architecture, see Extensibility-Enablement for
CDS Data Model Extensions [page 952].
Enabling the Database Tables [page 964]

This chapter guides you through the necessary steps to enable the database tables of our reference
business object for extensions to its data model.
Enabling the CDS Views [page 966]

This chapter guides you through the necessary steps to enable the CDS views of our reference
business object for extensions to its data model.

Extend PUBLIC 963
5.2.2.1.1 Enabling the Database Tables
This chapter guides you through the necessary steps to enable the database tables of our reference business
object for extensions to its data model.
In order to enable the database tables for data model extensions, you need to define an extension include
structure which can later be used by the extender for structure extends. The extension include structure is
then referenced in both the active and in the draft database table. Additionally, you need to define the database
tables and the extension include structure as extensibile explicitly.
For more information about enabling database tables for extensibility, see Extensibility-Enabling for Database
Tables [page 953].
Procedure
1. Create a structure called /DMO/S_EXT_INCL_AGENCY. This extension include structure serves as an

abstraction layer between the original business object and extensions and is added as an include to the
database tables in a subsequent step.
2. In the extension include structure, add a dummy field and use the following annotations in the header
section to define the enablement scope for the structure:
• @AbapCatalog.enhancement.category: Use the value #EXTENSIBLE_ANY to allow any kind of
extensions to the extension include structure.
• @AbapCatalog.enhancement.fieldSuffix: Choose the field suffix ZAG to avoid field name
collisions.
• @AbapCatalog.enhancement.quotaMaximumFields: Choose the number of fields which can be
added by the extender of the include structure.
• @AbapCatalog.enhancement.quotaMaximumBytes: Choose the byte capacity reserved for the
extender of the include structure.
• @AbapCatalog.enhancement.quotaShareCustomer: Choose the percentage of reservec fields /
byte capacity for customers.
• @AbapCatalog.enhancement.quotaSharePartner: Choose the percentage of reservec fields /
byte capacity for partners.
@EndUserText.label : 'Extension Include'

@AbapCatalog.enhancement.fieldSuffix : 'ZAG'
@AbapCatalog.enhancement.quotaMaximumFields : 350
@AbapCatalog.enhancement.quotaMaximumBytes : 3500
@AbapCatalog.enhancement.quotaShareCustomer : 50
@AbapCatalog.enhancement.quotaSharePartner : 50
define structure /dmo/s_ext_incl_agency {
dummy_field : abap.char(1);

}

964 PUBLIC Extend
 Note
It is recommended to add a C0 release contract in order to specify that this development object is
intended as a stable API for extensions.
For maintenance reasons, the artifacts of the /DMO/ reference content are not shipped with defined
release contracts. For further information on release contracts, see .
3. In the header of the database tables /DMO/AGENCY and /DMO/AGENCY_D, add the annotation
@AbapCatalog.enhancement.category : #EXTENSIBLE_ANY. It allows any kind of extensions for the
database table.
...

define table /dmo/agency {

...
4. Inlude the created extension include structure to the database tables /DMO/AGENCY and /DMO/AGENCY_D.
...

include /dmo/s_ext_incl_agency;

}
The resulting database table /DMO/AGENCY looks like this:
@EndUserText.label : 'Flight Reference Scenario: Managing Agencies'

define table /dmo/agency {
key agency_id : /dmo/agency_id not null;
postal_code : /dmo/postal_code;
city : /dmo/city;
country_code : land1;
phone_number : /dmo/phone_number;
email_address : /dmo/email_address;
web_address : /dmo/web_address;
mime_type : /dmo/mime_type;

}
5. The resulting database table /DMO/AGENCY_D looks like this:
@EndUserText.label : 'Draft table for entity /DMO/R_AGENCY'

define table /dmo/agency_d {

Extend PUBLIC 965
key agencyid : /dmo/agency_id not null;
postalcode : /dmo/postal_code;
city : /dmo/city;
countrycode : land1;
phonenumber : /dmo/phone_number;
emailaddress : /dmo/email_address;
webaddress : /dmo/web_address;
mimetype : /dmo/mime_type;
lastchangedat : abp_lastchange_tstmpl;

}
Result
You have now enabled the database tables for data model extensions. To enable extenders to add new fields,
you need to extensibility-enable the CDS data model as well, see chapter Enabling the CDS Views [page 966].
5.2.2.1.2 Enabling the CDS Views
This chapter guides you through the necessary steps to enable the CDS views of our reference business object
for extensions to its data model.
Analogously to the database level, you need to create an extension include view and define an association
to it from the CDS view /DMO/R_AGENCYTP. The extender can then add view extends with the new fields for
the extension include view and for the CDS view /DMO/R_AGENCYTP. In the latter one, the extender uses the
association to the extension include view in order to extend the CDS view /DMO/R_AGENCYTP with the new
fields.
In order to prepare the whole stack of our business object for field extensions, you need to define the CDS
views on the base layer as well as on the projection and interface layer as extensible explicitly using CDS
annotations.
For more information and the whole picture of the CDS-enabling architecture, see Extensibility-Enablement for
CDS Views [page 955].

966 PUBLIC Extend
Defining the Extension Include View
Create a CDS view entity with the name /DMO/E_AGENCY which will be used as your extension include view.
In the CDS view, select only the key field agency_id from the database table /DMO/AGENCY and provide the
alias Agency for the data source. Use the following CDS annotations that define the enablement scope for the
extension include view:
• @AbapCatalog.viewEnhancementCategory: [#PROJECTION_LIST]: Allows extensions of the

select list.
• @AbapCatalog.extensibility.extensible: true: Defines the extension include view as extensible.
• @AbapCatalog.extensibility.elementSuffix: 'ZAG': Defines the element suffix to be used in
view extends of this extension include view.
• @AbapCatalog.extensibility.allowNewDatasources: false: Defines whether associations
defined in CDS view extends can be used to address data sources in path expressions. In this example, we
do not want any further data sources to be used in the CDS view extends, so we choose the option false.
• @AbapCatalog.extensibility.dataSources: ['Agency']: Defines that the alias Agency can be
used in extensions of this CDS view.
• @AbapCatalog.extensibility.quota.maximumFields: 500: Defines the maximum number of
fields that can be added by extenders.
• @AbapCatalog.extensibility.quota.maximumBytes: 5000: Defines the byte capacity reserved for
extenders.
The resulting extension include view looks like this:
@AbapCatalog.viewEnhancementCategory: [#PROJECTION_LIST]

@EndUserText.label: 'Agency - Extension Include View'
@AbapCatalog.extensibility: {
extensible: true,
elementSuffix: 'ZAG',
allowNewDatasources: false,
dataSources: ['Agency'],
quota: {
maximumFields: 500,
maximumBytes: 5000
}
}
define view entity /DMO/E_Agency
as select from /dmo/agency as Agency
{
key agency_id as AgencyId
}

 Note
It is recommended to add a C0 release contract in order to specify that this development object is intended
as a stable API for extensions.

Extend PUBLIC 967
Enabling the CDS View /DMO/R_AGENCYTP
1. Define an association to the extension include view /DMO/E_AGENCY with the cardinality [1], the
association name _Extension and the field Agency ID as join condition.
association [1] to /DMO/E_Agency as _Extension on $projection.AgencyID =

_Extension.AgencyId
2. Use CDS annotations that define the enablement scope for the CDS view. Most of the
annotation values are identical to the extension include view described above. For the annotation
@AbapCatalog.extensibility.dataSources, use the association _Extension. This enables
extenders to use this association in extensions of this CDS view.
The upper section of the resulting CDS view looks like this:

@EndUserText.label: 'Agency'
extensible: true,
dataSources: ['_Extension'],
quota: {
maximumFields: 500,
maximumBytes: 5000
}
}
define root view entity /DMO/R_AgencyTP
as select from /DMO/I_Agency as Agency
_Country.Country
association [1] to /DMO/E_Agency as _Extension on $projection.AgencyID =
_Extension.AgencyId
{

key AgencyID,
 Note
Enabling the CDS View /DMO/C_AGENCYTP
Use CDS annotations that define the enablement scope for the CDS view. Most of the annotation values are
identical to the views described above. For the annotation @AbapCatalog.extensibility.dataSources,
use the alias Agency. This enables extenders to use this alias in extensions of this CDS view. Additionally, the
annotation @Metadata.allowExtensions: true is used to enable the addition of metadata extensions for
this view.

968 PUBLIC Extend

@ObjectModel.semanticKey: ['AgencyID']
extensible: true,
quota: {
maximumFields: 500,
maximumBytes: 5000
}
}
define root view entity /DMO/C_AgencyTP
as projection on /DMO/R_AgencyTP as Agency
{

key AgencyID,
 Note
Enabling the CDS View /DMO/I_AGENCYTP
Use CDS annotations that define the enablement scope for the CDS view. Most of the annotation values are
identical to the views described above. For the annotation @AbapCatalog.extensibility.dataSources,
use the alias Agency. This enables extenders to use this alias in extensions of this CDS view.

extensible: true,
dataSources: ['AGENCY'],
quota: {
maximumFields: 500,
maximumBytes: 5000
}
}
define root view entity /DMO/I_AgencyTP
provider contract transactional_interface
as projection on /DMO/R_AgencyTP as Agency
{

key AgencyID,

Extend PUBLIC 969
 Note
 Note
as a stable data source for consumption.
Defining the Draft Query View /DMO/R_AGENCYDRAFT
1. Create a CDS view entity called /DMO/R_AgencyDraft which selects the database table /DMO/AGENCY_D
and provide the alias Agency for the data source. Remove all CDS annotations in the header except
for @AccessControl.authorizationCheck: #NOT_REQUIRED and @EndUserText.label: 'Draft
Query View: Agency'. The CDS view will be used as the Draft Query View.
2. Use CDS annotations that define the enablement scope for the CDS view. Most of
the annotation values are identical to the views described above. For the annotation
@AbapCatalog.extensibility.dataSources, use the alias Agency. This enables extenders to use
this alias in extensions of this CDS view.
The resulting CDS view looks like this:

@EndUserText.label: 'Draft Query View: Agency'
extensible: true,
quota: {
maximumFields: 500,
maximumBytes: 5000
}
}
define view entity /DMO/R_AgencyDraft
as select from /dmo/agency_d as Agency
{
key agencyid as Agencyid,
key draftuuid as Draftuuid,
name as Name,
street as Street,
postalcode as Postalcode,
city as City,
countrycode as Countrycode,
phonenumber as Phonenumber,
emailaddress as Emailaddress,
webaddress as Webaddress,
attachment as Attachment,
mimetype as Mimetype,
filename as Filename,

970 PUBLIC Extend
localcreatedby as Localcreatedby,
localcreatedat as Localcreatedat,
locallastchangedby as Locallastchangedby,
locallastchangedat as Locallastchangedat,
lastchangedat as Lastchangedat,
draftentitycreationdatetime as Draftentitycreationdatetime,
draftentitylastchangedatetime as Draftentitylastchangedatetime,
draftadministrativedatauuid as Draftadministrativedatauuid,
draftentityoperationcode as Draftentityoperationcode,
hasactiveentity as Hasactiveentity,
draftfieldchanges as Draftfieldchanges
}

 Note
3. In the behavior definition /DMO/R_AGENCYTP, add the reference to the created draft query view.
...

define behavior for /DMO/R_AgencyTP alias Agency

...
Result
You have now enabled the business object for data model extensions. Refer to chapter Develop Data Model
Extensions [page 991] to learn how to add new fields to the database tables and the CDS data model.
5.2.2.2 Enabling Non-Standard Behavior and Field-Related

Behavior
This chapter guides you step-by-step on how to enable a business object for actions and functions as well as
for static and dynamic feature control extensions for new fields.
Required enablement steps
In order to enable a business object for non-standard behavior and field-related behavior, you need to enable
the base behavior definition and the interface behavior definition. If the extended behavior needs to be
available for service consumption, the projection behavior definition needs to be enabled as well.
For more information about enabling business objects for behavior extensions, see Extensibility-Enablement
for Behavior Extensions [page 958].

Extend PUBLIC 971
Enabling the Base Behavior Definition
1. In the base behavior definition /DMO/R_AGENCYTP, add the keyword extensible; in the header section
to overall enable the base behavior definition for behavior extensions.
managed implementation in class /dmo/bp_r_agencytp unique;

strict(2);
with draft;

extensible;
2. Enable the node Agency for behavior extensions by adding the keyword extensible in the section of this
node.
define behavior for /DMO/R_AgencyTP alias /DMO/Agency

lock master
late numbering

extensible
 Note
Enabling the Interface Behavior Definition
In the interface behavior definition /DMO/I_AGENCYTP, add the keyword extensible; in the header section.
interface;

use draft;
extensible;

 Note
 Note
as a stable data source for consumption.

972 PUBLIC Extend
Enabling the Projection Behavior Definition
1. In the projection behavior definition /DMO/C_AGENCYTP, add the keyword extensible; in the header
section to overall enable the projection behavior definition for behavior extensions.
projection;

strict(2);
use draft;

extensible;
2. Enable the node Agency for behavior extensions by adding the keyword extensible in the section of this
node.
define behavior for /DMO/C_AgencyTP alias /DMO/Agency

extensible
 Note
Result
You have now enabled the business object for field-related behavior extensions and for non-standard behavior
extensions. Besides feature control implementations, actions and functions, this also includes the definition of
new field mappings (for own structures) and new foreign entities (only for own entities).
The chapter Develop Behavior Extensions [page 995] shows how to develop behavior extensions for the
reference business object based on the implemented behavior enablement.
5.2.2.3 Enabling Standard Behavior Extensions
To allow the extender to add validations, determinations and additional save implementations, you need to
enable these operations in the behavior definition of your business object.
The standard behavior enablement allows extenders to add validations, determinations and additional save
implementations with the specified trigger conditions via extensions. Note that adding these extensions may
change the behavior of the BO at runtime.

Extend PUBLIC 973
In order to enable the business object for standard behavior extensions, you need to enable the base behavior
definition. Since you have enabled the interface behavior definition and the projection behavior definition in the
previous step already, no further enablement steps are required for these layers.
Prerequisite
This guide assumes, that you have enabled the business object for non-standard behavior as described in
Enabling Non-Standard Behavior and Field-Related Behavior [page 971].
Procedure
1. In the header section of the base behavior definition /DMO/R_AGENCYTP, define that determinations,
validations and additional save implementations can be added by the extender.
managed implementation in class /dmo/bp_r_agencytp unique;

strict(2);
with draft;
extensible {
with determinations on modify;
with determinations on save;
with validations on save;

with additional save; }
In this guide, the extender will add determinations on modify and a validation on save to the original
business object.
2. Define the determine action Prepare as extensible. This allows extenders to add their validations and
determinations to this action, thus enabling adequate handling of state messages.
draft determine action Prepare extensible

{
validation validateEMailAddress;
validation validateCountryCode;
validation validateName;

}
 Note

974 PUBLIC Extend
Result
You have now enabled the business object for standard behavior extensions.
The chapter Develop Behavior Extensions [page 995] shows how to develop behavior extensions for the
reference business object based on the implemented behavior enablement.
5.2.2.4 Enabling Node Extensions
To allow extenders to add their own extension node to the data model, you need to enable node extensions in
the original business object.
Extenders need to be able to add their extension node using a composition from the root node of the original
business object to the node of the extension. Hence, the root node needs to be enabled for new compositions
by using the corresponding CDS annotation in the CDS views /DMO/R_AGENCYTP, /DMO/I_AGENCYTP
and /DMO/C_AGENCYTP.
Since extenders want to be able to include behavior in their new node, the behavior definition /DMO/
R_AGENCYTP needs to be extensibility-enabled in the header section. If you followed the previous implemtation
steps of this guide, you have already done this as part of chapter Enabling Non-Standard Behavior and
Field-Related Behavior [page 971].
In the last step, the service definition requires extensibility enabling, since the extension node needs to be
exposed for service consumption.
Prerequisite
This guide assumes, that you have enabled the business object for standard behavior as described in Enabling
Standard Behavior Extensions [page 973].
Enabling the CDS View Stack for new Compositions
1. In the CDS view /DMO/R_AGENCYTP, add the CDS annotation

@AbapCatalog.extensibility.allowNewCompositions: true to the existing
@AbapCatalog.extensibility block in the header section.

extensible: true,

Extend PUBLIC 975
dataSources: ['_Extension'],
quota: {
maximumFields: 500,
maximumBytes: 5000
},
allowNewCompositions: true

}
 Note
2. In the CDS view /DMO/I_AGENCYTP, add the CDS annotation


extensible: true,
dataSources: ['AGENCY'],
quota: {
maximumFields: 500,
maximumBytes: 5000
}, allowNewCompositions: true

}
 Note
 Note
intended as a stable data source for consumption.
3. In the CDS view /DMO/C_AGENCYTP, add the CDS annotation


extensible: true,
quota: {
maximumFields: 500,
maximumBytes: 5000
}, allowNewCompositions: true


976 PUBLIC Extend
}
 Note
4. In the behavior definitions /DMO/R_AGENCYTP, /DMO/I_AGENCYTP and /DMO/C_AGENCYTP, make sure

that the keyword extensible is specified in the header section. Additionally, make sure that the node for
which new compositions are allowed is enabled in the behavior definitions /DMO/R_AGENCYTP and /DMO/
C_AGENCYTP.
If you have followed the instructions of this guide, then you have done all this already in chapter Enabling
Non-Standard Behavior and Field-Related Behavior [page 971].
5. In the service definition /DMO/UI_AGENCY, add the CDS annotation
@AbapCatalog.extensibility.extensible: true to the header section.

@AbapCatalog.extensibility.extensible: true
define service /DMO/UI_AGENCY {
expose /DMO/C_AgencyTP as Agency;

}
 Note
It is currently not possible to release service definitions for extensions in other software components
(C0 contract). Node extenders can therefore not extend service definitions that originate from another
software component. The consumption of node extensions from other software components is only
possible via EML or via a service built on top of the business object interface.
Result
You have now enabled the business object for node extensions.
The chapter Develop Node Extensions [page 1004] shows how to extend a business object with an
exisiting node based on the implemented node extensibility enablement.

Extend PUBLIC 977
5.3 RAP Extensions
This section explains the concepts of how to extend an original RAP business object with data model
extensions, behavior extensions and node extensions.
About Building RAP Extensions
RAP extensions enable you to extend existing RAP BOs from other software components or SAP delivered
RAP BOs to optimize and adapt their functionality to your specific business requirements. The RAP extension
approach focuses on separation-of concerns between original BO as basis for your extensions and the actual
extension artifacts that contain your additions to the data model and behavior of the original BO. Each layer in
the stack of a RAP business object can be extended and adapted depending on your business use case. You
can add additional fields to the data model, add new validations or determinations, actions and functions. You
can also extend the BO with an additional BO entity and extend the service definition to include the new BO
node .The available extensibility options depend on the extensibility-enablement of the original BO.
Generally, the RAP runtime differentiates between elements of an original BO and elements of extensions.
Generally, an extension can't reference any elements from the original BO or redefine any behavior defined in
the original BO.
For more information about the enablement requirements as basis for extensions and the granularity, see
Learn about Extensibility-Enablement [page 952].
Building Extensions for Different Implementation Types
Similar to draft capabilities, extensions are always managed by the managed BO provider at runtime, so
extensions behave the same way for all implementation types and the described concepts apply to both
managed and unmanged RAP BOs.
 Note
It's not possible to define standard behavior extensions for unmanaged RAP BOs.
Extending Released RAP BOs
Released RAP BOs follow the same extension principles as described in About Building RAP Extensions [page
978]. Additionally, released BOs are always released with release contracts to ensure lifecycle stability and
upgrade-safety for customer extensions. For an overview of the release contract architecture of a released RAP
BO, see Development Objects with Release Contracts Overview [page 951].
Extensions implicitly inherit the release contract of the objects that they belong to. BDEF extensions always
use a BO interface that is C1 released. Consequently, a behavior extension can, for example, only reference

978 PUBLIC Extend
data sources that are also C1 released. Refer to the respective BO KTD documentation to get more information
about available extension options for released RAP BOs.
Learn about RAP Extensions [page 979]
Develop RAP Extensions [page 990]
5.3.1 Learn about RAP Extensions
This section offers you conceptual background about building RAP extensions for different use cases.
CDS Data Model Extensions [page 979]

Data model extensions allow you to add extensions fields to the database tables and corresponding
CDS View entities.
Behavior Extensions [page 981]
Node Extensions [page 985]
5.3.1.1 CDS Data Model Extensions
Data model extensions allow you to add extensions fields to the database tables and corresponding CDS View
entities.
Data Model Extension Architecture
The data model of a RAP BO consists of database tables for active data and draft tables in the case of a
draft-enabled BO. On top of the database tables, the actual data model is defined with CDS View entities on
the base and projection layers, which are then exposed for service consumption. Building extensions follows
a bottom up approach, meaning you first define your extensions on the base BO layer, and then continue on
to the projection layer and the service exposure level. Extension fields are added as extension to extension
include structures embedded in the active and draft database tables, so that the extension has to be
defined only once also for a draft-enabled RAP BO.
The following graphic extends an existing datamodel with an extension field of type abap.char(4) and
the name ext_field. This field is propagated throughout the stack to the projection level. Each CDS View
entity is extended with a View Extend, adding the extension field. The R_View adds the ext_field via the
associated extension inlcudeview E_View . The E_View itself selects directly from the active database table.
The draft query view Draft_Query_View adds the extension fields via CDS view extend. On the projection
layer both the business service projection C_View and the BO interface CDS View I_View add the field from
the base layer via the R_View. Since all entities are included in the service exposure, the field is automatically
exposed and no extension to the service definition is required.

Extend PUBLIC 979
Extending Database Tables
You extend both active and draft database tables by extending an extension include structure that is
included in both tables in the case of a BO with draft capabilities. This is also the standard architecture for
released RAP BOs. However, if a BO doesn't use this architecture, it's also possible to directly extend the
database table. This is only recommended for smaller BOs and BOs that don't use release contracts.
Extending CDS Views
When you've extended the database tables, you have to propagate the extension fields throughout the stack.
This means that you have to add a View Extend to every CDS View entity. The base CDS View extends add
the extension fields to the corresponding entities. Once all layers are extended, the new extension fields are
automatically exposed in the OData service and no extension of the Service Definition is required.

980 PUBLIC Extend
For more information about the syntax, see ABAP CDS - Extending CDS Views (ABAP- Keyword
Documentation) and CDS BDL - BDEF Projection Extension (ABAP- Keyword Documentation).
Exposing Extension Fields on the UI
If you want to include the new fields not only in the OData Service, but also on the UI, you have to define UI
annotations for the extension projection CDS view.
For more information about UI annotations, see UI Annotations [page 1260].
Adding Behavior for Extension Fields
You can use the extension fields and add additional behavior like determinations and validations for the
extensions fields.
For more information, see Behavior Extensions [page 981].
5.3.1.2 Behavior Extensions
Behavior Extension Architecture
 Note
You can only define behavior extensions on a projection level that doesn't require an implementation class.
Behavior Extensions allow you to add additional behavior to an original RAP Business Object or a released RAP
BO. This chapter only covers behavior extensions to existing BO entities. For adding a new BO entity with its
own behavior and data model, see Node Extensions [page 985].
Prerequisites
A prerequisite for behavior extensions is the extensibility-enablement for the required behavior. You can
only define validations and determinations and an additional save if they're explicitly defined as extensibility-
enabled in the base BO. For more details about the required extensibility-enablement for behavior extensions,
see Extensibility-Enablement for Behavior Extensions [page 958].
Relation between Behavior Extensions and BO Interfaces

You can extend the behavior of a business object with extension behavior on the base and projection levels
of a RAP BO. On base level, you can add behavior that requires an implementation like validations or
determinations or actions and functions. On projection level, you can only add behavior extensions that don't
require an implementation.

Extend PUBLIC 981
Behavior extensions are stored in a Behavior Definitions Extension, which must always use a BO
interface in its header. For more information about the development object and its definition, see CDS BDL -
BDEF Extension (ABAP- Keyword Documentation).
A BDEF extension can only reference entities exposed in the BO interface - if the BO interface includes
only a subset of BO entities of the underlying data model, only the exposed entities can be enriched with
extension behavior. The BO interface also decides which other capabilities are exposed to extensions, like,
for example, draft capabilities. Even if the underlying data model itself is draft-enabled, but the BO interface
doesn't explicitly expose the draft behavior, behavior extensions can only access active instances in their
implementation and can't use the %is-draft indicator.
For this example, the class definition for implementation_class is generated as follows:
 Sample Code
CLASS imlementation_class DEFINITION INHERITING FROM

cl_abap_behavior_handler.

IMPORTING keys REQUEST requested_features FOR Root RESULT result.
METHODS ext_val FOR VALIDATE ON SAVE
IMPORTING keys FOR Root~ext_val.
METHODS get_instance_authorizations FOR INSTANCE AUTHORIZATION
IMPORTING keys REQUEST requested_authorizations FOR Root RESULT result.
METHODS ext_action FOR MODIFY
IMPORTING keys FOR ACTION Root~ext_action RESULT result.

ENDCLASS.
Behavior Extensions on Base Level
The BDEF Extension on base level contains the actual new behavior you want to add to the data BO. You have
all of the behavior options available that are enabled on the original BO. The example extension defines an
extension action ext_action with instance feature control and a validation on save for the extension

982 PUBLIC Extend
field ext_field added in CDS Data Model Extensions [page 979]. The BDEF extension inherits its basic
characteristics, like numbering and authorization, from the original BO. Draft capabilities, etag handling, and
strict version are inherited from the used BO interface.
If the original BO is defined with authorization(global, instance), the behavior pool for the BDEF
extension is generated with implementation exits FOR INSTANCE AUTHORIZATION and FOR GLOBAL
AUTHORIZATION. In the example, only instance authorization is defined, so only an implementation exit FOR
INSTANCE AUTHORIZATION is generated. You can only implement the instance authorization for the action
ext_action. The derived types of the authorization implementation exit are reduced to elements from your
BDEF extension - it's not possible to define additional authorization for elements from the base BO. The
same applies to the derived types of the FOR INSTANCE FEATURES. The BDEF extension inherits the draft
capabilities exposed in the BO interface I_View_BDEF with use draft; and the properties of strict(2)
In the example, the determine action PREPARE is extended with the additional validation ext_val to ensure
the correct handling of state messages from this validation.
Behavior Extensions on Projection Level
The BDEF extension of the projection level exposes the extension behavior defined on base BO level. In this
example, the BDEF extension exposes the action ext_action to expose it in the OData service.
Numbering in Behavior Extensions
The numbering behavior for key fields is inherited from the original BO entity and can't be changed in a
behavior extension. For more information about numbering, see Numbering [page 23].
Authorization in Behavior Extensions
 Note
You can't extend prechecks, but you can implement your own prechecks in the implementation.
Generally, authorizations are inherited from the base RAP BO, and the respective implementation is called
during runtime for global authorizations and the standard operations. It's not possible to redefine authorization
implementations, that are defined in an original BO, in the implementation of an extension. If you define, for
example, an extension action with authorization:update, the update authorizations of the base BO are
always called.
You can define additional authorizations for extension elements in the behavior pool of the behavior definition
extension, for example for extension actions or functions you have added in the behavior definition extension.
For more information about authorizations, see Authorization Control [page 80].
Concurrency Control in Behavior Extensions
The concurrency control handling for BDEF extensions is determined by the BO interface. If the original BO
uses etag handling and the BO interface exposes the etag handling with use etag, the etag handling defined
in the original BO is also applied to behavior in the BDEF extension. For more information, see Optimistic
Concurrency Control [page 33]. If a BO interface exposes draft handling, the total Etag is always applied.
If the etag handling isn't exposed by the BO interface, pessimistic concurrency control is applied as a default.
For more information, see Pessimistic Concurrency Control (Locking) [page 38].

Extend PUBLIC 983
Draft-Specific Extension Behavior
Among the draft actions, only the determine action PREPARE is extensible. You can add determinations and
validations that you've defined in the BDEF extension to determine action PREPARE in the extension. This is
recommended to guarantee correct message handling.
Generally, determine actions can only be extended or defined in an extension if the BO interface is draft-
enabled. For more information, see Draft [page 46].
About Behavior and Operations in Behavior Extensions
Standard Operations in Extensions
The standard operations of a BO entity are defined as part of the original BO. If an original BO doesn't define
the Delete operation as part of its behavior, you can't add this operation in a BDEF extension. For more
information about standard operations, see Standard Operations [page 88].
Actions and Functions in Extensions
Actions and functions follow the same rules as in non-extension use cases. For more information, see
Nonstandard Operations [page 101].
Validations and Determinations in Behavior Extensions
You can only define validations and determinations with their trigger conditions if the original BO is enabled for
them, otherwise this results in a syntax error in the BDEF extension.
An extension validation or determination can use either extension fields or original fields as part of their trigger
conditions, but within the implementation, the fields are treated differently at runtime. For more details, see in
local mode in Extensions [page 985].
For the required enablement, see Extensibility-Enablement for Behavior Extensions [page 958].
 Note
If you define an extension field as mandatory and the base BO isn't extension-enabled for validations
on save, it's not possible to implement a check in the extension to reinforce the mandatory attribute, and
it's only used as consumer hint on the user interface.
Static and Dynamic Feature Control in Behavior Extensions
 Note
You can only define static feature control for extensions to projection views.
You can only define additional static and dynamic feature control for extension elements in the behavior
definition extension. It's not possible to redefine feature control for elements of the original BO.
For more information about feature control, see Feature Control [page 128].

984 PUBLIC Extend
Messages and EML-Specific Extension Behavior
Messages in Extensions
Messages of extensions are handled by the BO provider framework of the base BO and the same guidelines
apply regarding the differentiations between state and transition messages.
 Note
It's recommended to use different %state_area strings in your extension that differ from the strings
defined in the original BO. If you use the same %state_area, all state messages belonging to the
respective state_area are invalidated at the same time.
For more information about messages, refer to Messages [page 261].
in local mode in Extensions
From the consumer's perspective, you can't distinguish if you're consuming part of an extension or part of the
original base BO. The implicit framework behavior differs, however, depending on whether an element belongs
to an extension or an original BO.
If you use in local mode in the behavior pool of your extension, the behavior differs. Generally, in local
mode is used to circumvent authorization and feature control checks. This works as expected for all elements
belonging to an extension. If you execute an EML modify in the implementation of your extension on an
element of the original BO with the addition in local mode, the authorization and feature control checks of
the original BO are executed anyway and can't be bypassed in the implementation even if in local mode is
specified.
Exposing Extension Behavior on the UI
If you want to include behavior-like actions not only in the OData Service, but also on the UI, you must use the
respective UI annotations to make the actions or other behavior visible on the UI.
For more information about UI annotations, see UI Annotations [page 1260].
5.3.1.3 Node Extensions
With node extensibility, you can add an additional BO entity to an existing RAP BO. The new node contains
its own data model that is integrated as an extension entity into the existing data model. The behavior for an
extension entity is defined in a BDEF extension. Then the Service Definition is extended to include the
new node in the service exposure.

Extend PUBLIC 985
Node Extensibility Architecture
Data Model of Extension Node
 Note
As extension provider, you may want to use ancestor associations to support locking, authorization, and
etag handling later on in the BDEF. Node extensibility is not enabled for UI use cases with release contracts
or for the implementation type unmanaged.
A prerequisite is that you have defined an additional node with its own data model that you want to include
in an existing data model. The original BO must be enabled for node extensibility as described in Extensibility-
Enablement for Node Extensibility [page 960].
The node used in this example for illustration purposes consists essentially of the view R_View_ExtNode with
the key field ID and a to-parent association to the root view of the BO data model that the extension node is
to be added to. This association establishes the parent-child relationship required to add behavior in a behavior
extension. The projection view C_View_ExtNode projects the R_View_ExtNode CDS view and redirects the
association to _Root to the corresponding projection C_View. The CDS view entity I_View_ExtNode projects
the R_View_ExtNode CDS View and redirects to the I_View CDS view.

986 PUBLIC Extend
The following graphic shows the CDS view stack for this example:
Including the Extension Node in the Original BO

The extension node must be included in the existing data model. Like data model extensions, the
extension node must be included throughout the stack. The extension include view R_View is extended
with the obligatory composition relationship that defines _ExtNode as composition of the root view entity.
The corresponding to-parent relationship was modeled as part of R_View_ExtNode with the association
association to parent R_View as _Root. This reciprocal relationship defines the extension node as a

Extend PUBLIC 987
dependent BO entity. Then the association is propagated throughout the CDS View stack with the respective
redirects. In this aspect, the extension node is modeled like a regular BO entity:
For an example, see Adding the Extension Node to the Data Model [page 1009].
Defining Behavior for the Extension Node

The behavior for the extension node is defined in an extension BDEF. Extension nodes are always added
a to-parent relationship - so authorization and lock behavior is always modeled as dependent and the
behavior is derived from the root node. It's recommended to use an Etag master on the extension node.
You can also specify the numbering required for your use case. In this case, the ExtNode is defined with early
numbering. This child node provides the update and delete operation for the BO entity. The create operation
is enabled via a create by association on the root node with association _ExtNode{ create; with
draft; }. The ExtNode also contains the reverse association to _Root.
On the projection layer, the BDEF extension to C_View_BDEF exposes the behavior defined in the base layer
with the keyword use.

988 PUBLIC Extend
For an example, seeExtending the Behavior for the Node Extension [page 1011] and Adding the Extension Node
to the Data Model [page 1009].
Ancestor Associations
If an extension node is added as subnode to a subnode, the path to the root entity needs to be specified
explicitly by using ancestor associations. Take the following example:
 Example
BO Hierarchy: In this example the node hierarchy is as follows: Root -ChildNode --GrandChild (toParent)
---ExtensionNode (extension)
Then the behavior extension for ExtensionNode defines the BO hierarchy as follows:
 Sample Code
define behavior for ExtensionNode alias ExtNode using BO_Interface

persistent table perst_table
draft table table_d
etag master LastChangedAtTask
lock dependent
...
{
update;
delete;
field ( readonly ) ID;
...
association _GrandChild { with draft; }
ancestor association _ChildNode { with draft; }

Extend PUBLIC 989
ancestor association _Root { with draft; }

}
This indirect reference only references the association by alias and not the technical CDS View entity directly.
Because of this, the hierarchy is still stable, even if the nodes are changed.
For more information about the syntax, see CDS BDL - ancestor association (ABAP- Keyword Documentation).
Including the Extension Node in the OData Service
When the extensions node has been modeled as part of the data model and behavior, it also needs to
be included as part of the OData service. To include the extension node, you have to create a Service
Definition Extension for the original service definition.
For an example, see Including the Extension Node in the Service Exposure [page 1017].
5.3.2 Develop RAP Extensions
This section offers how-to information and implementation examples for extending a RAP BO.
Reference Scenario
We work with the example from the ABAP Flight Reference Scenario that was used in chapter Develop
Extensibility-Enablement [page 962] to demonstrate the process of enabling a RAP BO for extensibility.
In this guide, the business object /DMO/R_AGENCYTP, which has been extensibility-enabled, is now extended
with regard to different extensibility use cases. The contributing artifacts for each extensibility use case can be
found in the following sub packages of the package /DMO/FLIGHT_REUSE_AGENCY:
• Data model extensibility: /DMO/FLIGHT_REUSE_AGENCY_SLOGN

• Behavior extensibility: /DMO/FLIGHT_REUSE_AGENCY_CNTRY
• Node extensibility: /DMO/FLIGHT_REUSE_AGENCY_REV
Extensibility Enablement Scenarios
The following guide is structured by the different extensibility use cases and guides you through the respective
extension processes.
Develop Data Model Extensions [page 991]

In the following section, you will develop a data model extension which adds a new field for an agency
slogan to our reference business object /DMO/R_AgencyTP.

990 PUBLIC Extend
Develop Behavior Extensions [page 995]
In the following section, you will develop behavior extensions which add new behavior to the reference
business object /DMO/R_AgencyTP.
Develop Node Extensions [page 1004]

In the following section, you will extend the reference business object /DMO/R_AgencyTP with an
extension node. This extension node is thereby added as a sub node to the existing /DMO/Agency node
in the original business object.
5.3.2.1 Develop Data Model Extensions
In the following section, you will develop a data model extension which adds a new field for an agency slogan to
our reference business object /DMO/R_AgencyTP.
Required Extension Steps
Data model extensions affect the whole stack of a business object. Hence you will develop extension
artifacts for the database layer as well as for every involved layer of the CDS data model. The data model
extension artifacts will make use of the extension points you developed as part of the data model extensibility
enablement process.
Prerequisite
You have enabled your business object for data model extensions as described in chapter Enabling Data Model
Extending the Database Tables [page 992]

This chapter guides you through the necessary steps to extend the database tables of our reference
business object with a new field.
Extending the CDS Views [page 993]

This chapter guides you through the necessary steps to extend the CDS data model of our reference
business object with the field you added to the database tables in the previous step.

Extend PUBLIC 991
5.3.2.1.1 Extending the Database Tables
This chapter guides you through the necessary steps to extend the database tables of our reference business
object with a new field.
Adding a field to the database layer requires a structure extend which you need to create for the existing
extension include structure /DMO/S_EXT_INCL_AGENCY. Since the extension include stucture is referenced in
the active table and in the draft table, the new field specified in the structure extend extends both tables.
Prerequisite
You have enabled your database tables for extensions as described in chapter Enabling the Database Tables
[page 964].
Procedure
Create a structure called /DMO/ZZ_S_EXT_AGENCY_SLOGAN and define it as a structure extend for the
structure /DMO/S_EXT_INCL_AGENCY. Specify the new field as shown below:
@EndUserText.label : 'Extend structure'

extend type /dmo/s_ext_incl_agency with /dmo/zz_s_ext_agency_slogan {
/dmo/zzsloganzag : /dmo/zz_slogan;

}
 Note
The names of extension elements must start with the namespace prefix used by the related package. Since
the namespace /DMO/ is used to ship the whole agency reference scenario, the prefix /DMO/ is also used
for extension elements in this example. In a productive environment, the namespace prefix of extensions
elements differs from the namespace of the original business object. This is indicated by the addition ZZ
after the /DMO/ namespace.
Result
You have extended the database tables with the new field. You can now add the field to the CDS data model as
described in Extending the CDS Views [page 993].

992 PUBLIC Extend
5.3.2.1.2 Extending the CDS Views
This chapter guides you through the necessary steps to extend the CDS data model of our reference business
object with the field you added to the database tables in the previous step.
Prerequisites
• You have enabled your CDS data model for extensibility as described in chapter Enabling the CDS Views
[page 966].
• You have added the field /dmo/zzsloganzag to the active database table and to the draft database table
as described in chapter Extending the Database Tables [page 992].
In order to make the new field available in your CDS data model, you first need to create a CDS view extend for
the extension include view /DMO/E_Agency and add the field to this view. You have access to the new field in
the database table via the data source alias defined in the extension include view.
Next, create a CDS view extend for the CDS view /DMO/R_AGENCYTP and use the association to the extension
include view to add the new field to the CDS view /DMO/R_AGENCYTP.
In the last step, make the new field available also in the CDS projection view /DMO/C_AGENCYTP, in the
interface view /DMO/I_AGENCYTP and in the draft query view /DMO/R_AGENCYDRAFT. Access the field by
using the data source alias defined in the extended CDS view respectively.
Procedure
1. Create a CDS extension view called /DMO/ZZ_X_SLOGAN_E_AGENCY for the extension include view /DMO/
E_AGENCY and add the new field in the field list. Since you have already extended the database table /DMO/
AGENCY with the new field, you can use the data source alias Agency defined in the extension include view
in a path expression to access the field.
extend view entity /DMO/E_Agency with

{
Agency./dmo/zzsloganzag as /DMO/ZZSloganZAG
}

 Note
Aliasing that effects more than a change from lowercase to uppercase or vice versa should not be done
on the base layer. Aliasing is possible on the interface layer or on the projection layer of the business
object.

Extend PUBLIC 993
 Note
The names of extension elements must start with the namespace prefix used by the related package.
Since the namespace /DMO/ is used to ship the whole agency reference scenario, the prefix /DMO/ is
also used for extension elements in this example. In a productive environment, the namespace prefix
of extensions elements differs from the namespace of the original business object. This is indicated by
the addition ZZ after the /DMO/ namespace.
2. Create a CDS extension view called /DMO/ZZ_X_SLOGAN_R_AGENCY for the CDS view /DMO/R_AGENCYTP
and add the new field in the field list. In order to access the field, use the association _Extension to the
extension include view /DMO/E_AGENCY in a path expression.
extend view entity /DMO/R_AgencyTP with

{
_Extension./DMO/ZZSloganZAG
}

3. Create a CDS extension view called /DMO/ZZ_X_SLOGAN_C_AGENCY for the CDS projection view /DMO/
C_AGENCYTP and add the new field in the field list. In order to access the field, use the data source
alias Agency defined in the CDS projection view in a path expression. The field is available in the CDS
view /DMO/R_AGENCYTP as you have extended it in the previous step. Add UI annotations as well as search
annotations for the default search element and the fuzziness threshold of the field.
extend view entity /DMO/C_AgencyTP with

{
@UI: {
{ position: 10, type: #FOR_ACTION, dataAction: '/DMO/
createFromTemplate', label: 'Create from Template' } ],
fieldGroup: [ { position: 25, qualifier: 'General_FG' } ],
identification: [ { position: 10, type: #FOR_ACTION, dataAction: '/DMO/
createFromTemplate', label: 'Create from Template' } ]
}
Agency./DMO/ZZSloganZAG
}

4. Create a CDS extension view called /DMO/ZZ_X_SLOGAN_I_AGENCY for the CDS interface projection
view /DMO/I_AGENCYTP and add the new field in the field list. In order to access the field, use the data
source alias Agency defined in the interface projection view in a path expression. The field is available in
the CDS view /DMO/R_AGENCYTP as you have extended it in a previous step.
extend view entity /DMO/I_AgencyTP with

{
}

5. Create a CDS extension view called /DMO/ZZ_X_SLOGAN_R_AGENCYDRAFT for the draft query view /DMO/
R_AGENCYDRAFT and add the new field in the field list. Since you have already extended the database
table /DMO/AGENCY_D with the new field, you can use the data source alias Agency defined in the draft
query view in a path expression to access the field.
extend view entity /DMO/R_AgencyDraft with

{
Agency./dmo/zzsloganzag as /DMO/ZZSloganZAG
}


994 PUBLIC Extend
5.3.2.2 Develop Behavior Extensions
In the following section, you will develop behavior extensions which add new behavior to the reference business
object /DMO/R_AgencyTP.
Extension Behavior
The extensions added in this section involve the following behavior:
• Determination /DMO/determineCountryCode: Determines the country code of an agency instance

based on an entered dialling code.
• Determination /DMO/determineDiallingCode: Determines the dialling code of an agency instance
based on an entered country code.
• Validation /DMO/validateDiallingCode: Checks whether entered dialling codes have the valid format
and whether they exist in a reference table.
• Action /DMO/createFromTemplate: This is a factory action. For each instance that is provided to the
method, the action creates one agency instance with the location related values of the input instance.
In order to extend the business object with this new behavior, you need to develop a behavior definition
extension artifact, where the new behavior is defined as well as a behavior implementation artifact in which the
defined behavior is implemented.
Prerequisites
Extending the business object with the above mentioned behavior requires the business object to be
extensibility enabled accordingly. The required extensibility enablement depends on the type of the behavior to
be added respectively:
• Determinations and validations: For adding determinations and validations, the business object needs to
be enabled for standard behavior as described in Enabling Standard Behavior Extensions [page 973]
• Actions: For adding actions, the business object needs to be enabled for non-standard behavior as
described in Enabling Non-Standard Behavior and Field-Related Behavior [page 971].
Defining the Extension Behavior [page 996]

In this chapter, you create a behavior definition extension and define the behavior to be added via the
extension.
Implementing the Extension Behavior [page 998]

In this chapter, you implement the extension behavior you have defined in the previous step.
Exposing the Action Extension for UI Consumption [page 1003]

Extend PUBLIC 995
In this chapter, you define CDS annotations to expose the action implemented in the previous step on
the UI.
5.3.2.2.1 Defining the Extension Behavior

In this chapter, you create a behavior definition extension and define the behavior to be added via the
extension.
Procedure
1. In the context menu of the behavior definition /DMO/R_AGENCYTP, choose the option New Behavior
Extension.
2. In the BDEF extension creation dialogue, enter the name of the package where the BDEF extension is to be
stored as well as the name /DMO/ZZ_X_COUNTRY_R_AGENCYTP, a description and the BO interface /DMO/
I_AGENCYTP.
The resulting BDEF extension looks like this and is ready for defining the extension behavior as described in
the following section.
extension using interface /dmo/i_agencytp

implementation in class /dmo/zz_bp_x_cntry_r_agencytp unique;
3. Below the generated code in the behavior definition extension, add the keywords extend behavior
for /DMO/Agency { }. The extension behavior can now be defined within the curly brackets.


{ }
4. Within the curly brackets, define the validation /DMO/validateDiallingCode with the trigger time on
save and the field trigger PhoneNumber.
validation /DMO/validateDiallingCode on save { field PhoneNumber; }
5. Extend the draft determine action Prepare with the defined validation /DMO/validateDiallingCode to
ensure the adequate handling of state messages.
extend draft determine action Prepare

{
validation /DMO/validateDiallingCode;

}
6. Define the determination /DMO/determineCountryCode with the trigger time on modify and the field
trigger PhoneNumber.
determination /DMO/determineCountryCode on modify { field PhoneNumber; }
7. Define the determination /DMO/determineDiallingCode with the trigger time on modify and the field
trigger CountryCode.
determination /DMO/determineDiallingCode on modify { field CountryCode; }

996 PUBLIC Extend
8. Define the factory action /DMO/createFromTemplate with the result cardinality [1]. Use
( authorization: global ) for the action.
factory action /DMO/createFromTemplate [1];
The resulting behavior definition extension looks like this:

{
validation /DMO/validateDiallingCode on save { field PhoneNumber; }
determination /DMO/determineCountryCode on modify { field PhoneNumber; }
determination /DMO/determineDiallingCode on modify { field CountryCode; }
extend draft determine action Prepare
{
validation /DMO/validateDiallingCode;
}
factory action ( authorization : global ) /DMO/createFromTemplate [1];

}
 Note
also used for extension elements in this example. In a productive environment, the namespace prefix of
extensions elements differs from the namespace of the original business object.
9. Use the quickfix offered for the line implementation in class /dmo/zz_bp_x_cntry_r_agencytp
unique; to create the behavior implementation class for the behavior definition extension.
10. In the context menu of the behavior definition /DMO/C_AGENCYTP, choose the option New Behavior
Extension.
stored as well as the name /DMO/ZZ_X_COUNTRY_C_AGENCYTP and a description.
In the generated BDEF, remove the keywords in the line after extension for projection. The resulting
BDEF extension looks like this and and is ready for defining the extension behavior as described in the
following section.
extension for projection;

extend behavior for /DMO/Agency {

}
12. Extend the projection layer of the original business object with the action /DMO/createFromTemplate
from the base BDEF extension.

{
use action /DMO/createFromTemplate;

}

Extend PUBLIC 997
Result
You have defined the extension behavior in the behavior definition extension. You can now implement the
behavior in the created implentation class, see Implementing the Extension Behavior [page 998].
5.3.2.2.2 Implementing the Extension Behavior
In this chapter, you implement the extension behavior you have defined in the previous step.
The implementation of behavior defined in a behavior extension follows the same approach as the
implementation of behavior defined for an original business object. There is no special class syntax required
related to extensibility. However, there are differences when it comes to accessing the original business object
from extensions via EML.
 Note
An interface is the consolidated consumption point of a business object, which needs to be used by
every consumer. This also applies to extenders who access the original business object via EML in their
extensions. This is why EML statements in behavior extension implementations must always address the
original business object via its interface.
If the keywords IN LOCAL MODE are used in an EML statement of a behavior extension, only the
feature control and authorization implementations of this extension are bypassed. Feature control and
authorization implementations of the original business object are not bypassed with such a statement.
The following sections describe the required steps to implement the extension behavior.
Prerequisite
You have defined the extension behavior and created the behavior implementation class for the extension as
described in chapter Defining the Extension Behavior [page 996].
Defining required Class Components
As a preparational step for the implementation of the validation and the determinations, you need to define
a state area for the messages reported by the validation. Furthermore, the validation and the determinations
require a lookup table for the dialling and country codes to work with. Define these components as follows:
1. In the public section of the behavior implementation class, define the constant
validate_dialling_code with the type string and the value VALIDATE_DIALLING_CODE. You will
use this constant as the state area for messages reported by the validation validateDiallingCode.
CLASS lhc_Agency DEFINITION INHERITING FROM cl_abap_behavior_handler.

PUBLIC SECTION.
CONSTANTS:

998 PUBLIC Extend

validate_dialling_code TYPE string VALUE 'VALIDATE_DIALLING_CODE'
##NO_TEXT.
2. The validation and the determinations to be developed will use a lookup table for the dialling codes and
country codes. The content of the lookup table is initialized in the class constructor. Define the necessary
types and the lookup table in the public section and populate the table with sample values in the method
class constructor.
CLASS lhc_Agency DEFINITION INHERITING FROM cl_abap_behavior_handler.

PUBLIC SECTION.
CONSTANTS:
validate_dialling_code TYPE string VALUE 'VALIDATE_DIALLING_CODE'
##NO_TEXT.
TYPES: BEGIN OF t_countries,
number TYPE /dmo/phone_number,
code TYPE land1,
END OF t_countries.
CLASS-DATA: countries TYPE STANDARD TABLE OF t_countries WITH KEY number.
CLASS-METHODS: class_constructor.
PRIVATE SECTION.
METHODS validateDiallingCode FOR VALIDATE ON SAVE
IMPORTING keys FOR /DMO/Agency~/DMO/validateDiallingCode.
METHODS determineCountryCode FOR DETERMINE ON MODIFY
IMPORTING keys FOR /DMO/Agency~/DMO/determineCountryCode.
METHODS determineDiallingCode FOR DETERMINE ON MODIFY
IMPORTING keys FOR /DMO/Agency~/DMO/determineDiallingCode.
IMPORTING REQUEST requested_authorizations FOR /DMO/Agency RESULT
result.
METHODS createFromTemplate FOR MODIFY
IMPORTING keys FOR ACTION /DMO/Agency~/DMO/createFromTemplate.
ENDCLASS.
CLASS lhc_Agency IMPLEMENTATION.
METHOD validateDiallingCode.
ENDMETHOD.
METHOD determineCountryCode.
ENDMETHOD.
METHOD determineDiallingCode.
ENDMETHOD.
ENDMETHOD.
METHOD createFromTemplate.
ENDMETHOD.
METHOD class_constructor.
countries = VALUE #( ( number = '+1' code = 'US' )
( number = '+49' code = 'DE' )
( number = '+39' code = 'IT' )
( number = '+43' code = 'AT' )
( number = '+44' code = 'GB' )
( number = '+81' code = 'JP' )
( number = '+33' code = 'FR' )
( number = '+358' code = 'FI' )
( number = '+385' code = 'HR' ) ).
ENDMETHOD.

ENDCLASS.
Implementing the Validation validateDiallingCode
1. Read the fields PhoneNumber and CountryCode of all instances to be validated along with their keys and
store the result in an internal table.

Extend PUBLIC 999
2. Loop over all instances to be validated. For every instance, do the following:
• Invalidate the state messages for the state area validate_dialling_code to avoid that messages
with the same state area are continously added for the agency instance.
• If the field PhoneNumber is initial, continue with the next instance. Instances with an empty phone
number don't need to be validated.
• If the first two characters of the phone number are 00, then replace them with the + sign.
• If the first character of the phone number is not +, then append an appropriate message to the
reported structure for this instance using the state area validate_dialling_code. Mark the field
PhoneNumber in the element component.
• If there is no entry in the lookup table countries where the phone number matches the first two,
three and four phone number characters of the looped instance and where the country code matches
the one of the looped instance, then append an appropriate message to the reported structure for
this instance using the state area validate_dialling_code. Mark the field PhoneNumber in the
element component.
METHOD validateDiallingCode.

ENTITY /DMO/Agency
FIELDS ( PhoneNumber CountryCode ) WITH CORRESPONDING #( keys )
LOOP AT agencies INTO DATA(agency).
APPEND VALUE #( %tky = agency-%tky
%state_area = validate_dialling_code ) TO reported-/DMO/
Agency.
IF agency-PhoneNumber IS INITIAL.
CONTINUE.
ENDIF.
IF agency-PhoneNumber(2) = '00'.
REPLACE FIRST OCCURRENCE OF '00' IN agency-Phonenumber WITH '+'.
ENDIF.
IF agency-PhoneNumber(1) <> '+'.
%state_area = validate_dialling_code
%msg = NEW /dmo/zz_cx_agency_country( textid
= /dmo/zz_cx_agency_country=>number_invalid
phonenumber =
agency-PhoneNumber )
%element-PhoneNumber = if_abap_behv=>mk-on )
TO reported-/DMO/Agency.
ELSEIF NOT line_exists( countries[ number = agency-phonenumber(2) code =
agency-CountryCode ] )
AND NOT line_exists( countries[ number = agency-phonenumber(3) code =
agency-CountryCode ] )
AND NOT line_exists( countries[ number = agency-phonenumber(4) code =
agency-CountryCode ] ).
%state_area = validate_dialling_code
%msg = NEW /dmo/zz_cx_agency_country( textid
= /dmo/zz_cx_agency_country=>combination_invalid )
%element-PhoneNumber = if_abap_behv=>mk-on )
TO reported-/DMO/Agency.
ENDIF.
ENDLOOP.

ENDMETHOD.

1000 PUBLIC Extend
Implementing the Determination determineCountryCode
1. Read the fields PhoneNumber and CountryCode of all instances to be processed along with their keys and
store the result in the internal table agencies.
2. Delete all instances from the internal table agencies that already have a country code. This prevents
the unnecessary execution and an infinite loop between the determinations determineCountryCode and
determineDiallingCode.
3. Declare a table called agencies_to_update with the derived type for EML updates on the interface of the
original BO.
4. Add the content of the %tky component of all instances from the internal table agencies to the table
agencies_to_update whose phone number starts with one of the numbers from the lookup table
countries. Add the corresponding country code from the lookup table.
5. Perform the EML update using the internal table agencies_to_update.
METHOD determineCountryCode.

ENTITY /DMO/Agency
DELETE agencies WHERE CountryCode IS NOT INITIAL.
DATA: agencies_to_update TYPE TABLE FOR UPDATE /dmo/i_agencytp.
LOOP AT countries INTO DATA(country).
DATA(country_with_00) = country-number.
REPLACE FIRST OCCURRENCE OF '+' IN country_with_00 WITH '00'.
LOOP AT agencies INTO DATA(agency)
WHERE PhoneNumber CP country-number && '*'
OR PhoneNumber CP country_with_00 && '*'.
countrycode = country-code ) TO agencies_to_update.
ENDLOOP.
ENDLOOP.
MODIFY ENTITIES OF /dmo/i_agencytp IN LOCAL MODE
ENTITY /DMO/Agency
UPDATE FIELDS ( countrycode ) WITH agencies_to_update

ENDMETHOD.
Implementing the Determination determineDiallingCode
1. Read the fields PhoneNumber and CountryCode of all instances to be processed along with their keys and
store the result in the internal table agencies.
2. Delete all instances from the internal table agencies that already have a phone number. This prevents the
unnecessary execution and an infinite loop between the determinations determineDiallingCode and
determineCountryCode.
3. Declare a table called agencies_to_update with the derived type for EML updates on the interface of the
original BO.
4. Add the content of the %tky component of all instances from the internal table agencies to the table
agencies_to_update whose country code matches one of the country codes from the lookup table
countries. Add the corresponding phone number from the lookup table.

Extend PUBLIC 1001
5. Perform the EML update using the internal table agencies_to_update.
METHOD determineDiallingCode.

ENTITY /DMO/Agency
DELETE agencies WHERE PhoneNumber IS NOT INITIAL.
DATA: agencies_to_update TYPE TABLE FOR UPDATE /dmo/i_agencytp.
DATA(PhoneNumber) = VALUE #( countries[ code = agency-countrycode ]-
number OPTIONAL ) .
IF PhoneNumber IS NOT INITIAL.
phonenumber = PhoneNumber ) TO agencies_to_update.
ENDIF.
ENDLOOP.
ENTITY /DMO/Agency
UPDATE FIELDS ( PhoneNumber ) WITH agencies_to_update

ENDMETHOD.
Implementing the Action createFromTemplate
1. Read the values of the fields CountryCode, PostalCode, City and Street of all provided instances.
2. Declare an internal table called agencies_to_create with the derived type for create operations on the
BO interface /DMO/I_AgencyTP.
3. Append all read agency instances to the table agencies_to_create. For each instance in
agencies_to_create, assign the %cid from the read result and set the draft indicator to
if_abap_behv=>mk-on respectively.
4. Finally, create the instances using the prepared internal table agencies_to_create. Forward the mapped
response of the EML CREATE statement to the mapped response of the factory action.
METHOD createFromTemplate.

READ ENTITIES OF /DMO/I_AgencyTP IN LOCAL MODE
ENTITY /DMO/Agency
FIELDS ( CountryCode PostalCode City Street ) WITH CORRESPONDING
#( keys )
RESULT DATA(agencies)
FAILED failed.
DATA: agencies_to_create TYPE TABLE FOR CREATE /DMO/I_AgencyTP.
APPEND CORRESPONDING #( agency EXCEPT agencyid ) TO agencies_to_create
ASSIGNING FIELD-SYMBOL(<agency_to_create>).
<agency_to_create>-%cid = keys[ KEY id %tky = agency-%tky ]-%cid.
<agency_to_create>-%is_draft = if_abap_behv=>mk-on.
ENDLOOP.
MODIFY ENTITIES OF /DMO/I_AgencyTP IN LOCAL MODE
ENTITY /DMO/Agency
CREATE FIELDS ( CountryCode PostalCode City Street ) WITH
agencies_to_create
MAPPED mapped.

ENDMETHOD.

1002 PUBLIC Extend
Result
You have implemented the behavior of the extension. You can now expose the action for UI consumption as
described in chapter Exposing the Action Extension for UI Consumption [page 1003].
5.3.2.2.3 Exposing the Action Extension for UI

Consumption
In this chapter, you define CDS annotations to expose the action implemented in the previous step on the UI.
Required Steps
In order to expose action extensions on the UI, any field in the CDS view extend of the projection layer
is required, which the UI annotations for the action extensions can refer to. In the following example, the
field /DMO/ZZSloganZAG added in chapter Develop Data Model Extensions [page 991] is used as reference
destination for the action annotations.
Procedure
In the CDS view extend /DMO/ZZ_X_SLOGAN_C_AGENCY, add UI annotations for the action /DMO/
createFromTemplate to the field /DMO/ZZSloganZAG in order to display the action on the UI list report
page and on the UI object page.

{
@UI: {
{ position: 10, type: #FOR_ACTION, dataAction: '/DMO/
createFromTemplate', label: 'Create from Template' } ],
fieldGroup: [ { position: 25, qualifier: 'General_FG' } ],
identification: [ { position: 10, type: #FOR_ACTION, dataAction: '/DMO/
createFromTemplate', label: 'Create from Template' } ]
}
}


Extend PUBLIC 1003
5.3.2.3 Develop Node Extensions
In the following section, you will extend the reference business object /DMO/R_AgencyTP with an extension
node. This extension node is thereby added as a sub node to the existing /DMO/Agency node in the original
business object.
Extension Node
The extension node /DMO/ZZ_Review is to be added to the original business object and shall enable the end
user to create and evaluate reviews for each agency instance. A review includes a rating between one and five
stars as well as a textual description. Readers of a review can rate it as helpful or not helpful. The number of
helpful reviews is then displayed for each review instance.
At first, you need to define the data model for the extension node that you want to include in the existing data
model. The created CDS view /DMO/ZZ_R_Agency_ReviewTP must hereby contain a to-parent association
to the CDS view /DMO/R_AgencyTP. This association needs to be propagated to the projection views /DMO/
ZZ_C_Agency_ReviewTP and /DMO/ZZ_I_Agency_ReviewTP and redirected to the corresponding layers.
Next, you need to extend the data model of the original BO with a composition that defines the node /DMO/
ZZ_R_AGENCY_REVIEWTP as a sub node of the /DMO/R_AgencyTP node. This compositional relationship
needs to be then propagated throughout the stack and redirected to the corresponding layers.
In the next step, you need to create a behavior definition extension for the original BDEF /DMO/R_AgencyTP.
This BDEF extension defines the behavior of the /DMO/ZZ_Review node and extends the behavior of the
original BO with a create-by-association operation using the defined composition. This extension is needed to
enable creating Review instances for a given Agency instance. The added create-by-association needs to be
exposed in a projection BDEF extension. Furthermore, you need to extend the draft determine action prepare
of the original BO with the validation /DMO/ratingInRange which is part of the node logic, in order to ensure
an adequate handling of state messages.
Afterwards, you need to implement the behavior defined in the behavior definition extension.
Lastly, you need to extend the service definition /DMO/UI_AGENCY with the CDS view /DMO/
ZZ_C_Agency_ReviewTP to include the node into the exposure for service consumption.
Prerequisite
You have enabled the business object for node extensibility as described in Enabling Node Extensions [page
975].
Defining the Data Model for the Extension Node [page 1005]

1004 PUBLIC Extend
In this chapter, you define the database table and the CDS data model for the extension node.
Adding the Extension Node to the Data Model [page 1009]

In this chapter, you extend the data model of the original business object with a composition that
defines the /DMO/ZZ_Review node as a subnode of the /DMO/Agency node.
Extending the Behavior for the Node Extension [page 1011]

In this chapter, you define the behavior for the extension node and integrate it into the behavior of the
original business object.
Implementing the Behavior for the Node Extension [page 1013]

In this chapter, you implement the behavior defined for the node in the previous chapter.
Including the Extension Node in the Service Exposure [page 1017]

In this step, you create a service definition extension for the review node and add it to service of the
original BO.
5.3.2.3.1 Defining the Data Model for the Extension Node
In this chapter, you define the database table and the CDS data model for the extension node.
Creating the Database Table
Create the active database table with the fields required for persisting review data:
@EndUserText.label : 'Agency Review: Review. Active Instances'

define table /dmo/zz_agn_reva {
key agency_id : /dmo/agency_id not null;
key review_id : /dmo/zz_review_id not null;
rating : /dmo/zz_rating;
free_text_comment : /dmo/zz_free_text_comment;
helpful_count : /dmo/zz_helpful_count;
helpful_total : /dmo/zz_helpful_total;
reviewer : abp_creation_user;

}
The draft database table can be generated once the BDEF extension for the node has been defined.

Extend PUBLIC 1005
Defining the CDS Data Model
1. Create a CDS view called /DMO/ZZ_I_Agency_Review which selects from the database table /dmo/
zz_agn_reva.

@EndUserText.label: 'Agency Review'
serviceQuality: #X,
sizeCategory: #S,
dataClass: #MIXED
}
define view entity /DMO/ZZ_I_Agency_Review
as select from /dmo/zz_agn_reva as Review
{
key Review.agency_id as AgencyId,
key Review.review_id as ReviewId,
Review.rating as Rating,
Review.free_text_comment as FreeTextComment,
Review.helpful_count as HelpfulCount,
Review.helpful_total as HelpfulTotal,
Review.reviewer as Reviewer,
Review.local_created_at as LocalCreatedAt,
Review.local_last_changed_at as LocalLastChangedAt
}

2. Create a CDS view called /DMO/ZZ_R_Agency_ReviewTP which selects from the created CDS view /DMO/
ZZ_I_Agency_Review. Add an association to the parent entity /DMO/R_AgencyTP and expose this
association in the field list. You will add the corresponding composition to the Ageny node in chapter
Adding the Extension Node to the Data Model [page 1009].

define view entity /DMO/ZZ_R_Agency_ReviewTP
as select from /DMO/ZZ_I_Agency_Review
association to parent /DMO/R_AgencyTP as _Agency on $projection.AgencyId =
_Agency.AgencyID
{
key AgencyId,
key ReviewId,
Rating,
FreeTextComment,
HelpfulCount,
HelpfulTotal,
Reviewer,
LocalCreatedAt,
LocalLastChangedAt,
_Agency
}

3. Create the interface projection CDS view called /DMO/ZZ_I_Agency_ReviewTP which projects the
CDS view /DMO/ZZ_R_Agency_ReviewTP. Redirect the association _Agency to the interface layer of
the /DMO/Agency node.

define view entity /DMO/ZZ_I_Agency_ReviewTP
as projection on /DMO/ZZ_R_Agency_ReviewTP

1006 PUBLIC Extend
{
key AgencyId,
key ReviewId,
Rating,
FreeTextComment,
HelpfulCount,
HelpfulTotal,
Reviewer,
LocalCreatedAt,
LocalLastChangedAt,
/* Associations */
_Agency : redirected to parent /DMO/I_AgencyTP
}

4. Create the CDS projection view called /DMO/ZZ_C_Agency_ReviewTP which projects the CDS
view /DMO/ZZ_R_Agency_ReviewTP. Redirect the association _Agency to the projection layer of
the /DMO/Agency node.

@ObjectModel.semanticKey: ['Reviewer']
define view entity /DMO/ZZ_C_Agency_ReviewTP
as projection on /DMO/ZZ_R_Agency_ReviewTP
{
key AgencyId,
key ReviewId,
Rating,
FreeTextComment,
HelpfulCount,
HelpfulTotal,
Reviewer,
LocalCreatedAt,
LocalLastChangedAt,
/* Associations */
_Agency : redirected to parent /DMO/C_AgencyTP
}

5. Create a metadata extension for the CDS projection view /DMO/ZZ_C_Agency_ReviewTP for the display
on the UI.
 Expand the following code sample to view the source code of the metadata extension /DMO/
ZZ_C_Agency_ReviewTP.
 Sample Code
@Metadata.layer: #CUSTOMER

@UI: { headerInfo: {
typeName: 'Review',
typeNamePlural: 'Reviews',
title: { type: #STANDARD, value: 'ReviewId' }
},
presentationVariant: [{
sortOrder: [{ by: 'LocalCreatedAt', direction: #DESC }],
visualizations: [{type: #AS_LINEITEM}]
}]
}
annotate view /DMO/ZZ_C_Agency_ReviewTP with
{
@UI.facet: [
{
id: 'Review',
purpose: #STANDARD,
label: 'Review',
position: 10

Extend PUBLIC 1007
},
{
id: 'HelpfulID',
purpose: #HEADER,
type: #DATAPOINT_REFERENCE,
label: 'Helpful',
position: 10,
targetQualifier: 'HelpfulCount'
}
]
@UI.hidden: true
AgencyId;
@UI.hidden: true
ReviewId;
@UI:{
dataPoint: {
title: 'Rating'
,visualization: #RATING
,targetValue: 5
},
lineItem:
[
{
position: 10,
label: 'Rating',
importance: #HIGH
,valueQualifier: 'Rating'
,type: #AS_DATAPOINT
}
],
identification: [
{
position: 10,
label: 'Rating',
importance: #HIGH
}
]
}
Rating;
@UI.multiLineText: true
FreeTextComment;
@UI:{
dataPoint: {
title: 'Helpful',
targetValueElement: 'HelpfulTotal'
,visualization: #PROGRESS
},
lineItem: [
{
position: 50,
label: 'Helpful',
importance: #HIGH
,valueQualifier: 'Progress'
}
]
}
HelpfulCount;
@UI.hidden: true
HelpfulTotal;
@UI.lineItem: [
{ type: #FOR_ACTION, dataAction: '/DMO/reviewWasHelpful', label:
'Helpful' },
{ type: #FOR_ACTION, dataAction: '/DMO/reviewWasNotHelpful', label:
'Not Helpful' },

1008 PUBLIC Extend
{ position: 3 }
]
@UI.identification: [
{ type: #FOR_ACTION, dataAction: '/DMO/reviewWasHelpful', label:
'Helpful' },
{ type: #FOR_ACTION, dataAction: '/DMO/reviewWasNotHelpful', label:
'Not Helpful' },
{ position: 3 }
]
Reviewer;
@UI.hidden: true
LocalCreatedAt;
@UI.hidden: true
LocalLastChangedAt;

}
Result
You have defined the data model for the extension node. You can now add it to the data model of the original
business object, see Adding the Extension Node to the Data Model [page 1009].
5.3.2.3.2 Adding the Extension Node to the Data Model
In this chapter, you extend the data model of the original business object with a composition that defines
the /DMO/ZZ_Review node as a subnode of the /DMO/Agency node.
Procedure
1. Create a CDS extension view called /DMO/ZZ_X_REVIEW_R_AGENCY for the CDS view /DMO/R_AgencyTP.
Extend the CDS view /DMO/R_AgencyTP with a compositional association to the entity /DMO/
ZZ_R_Agency_ReviewTP and define the alias /DMO/ZZ_ReviewZAG for the composition. Expose this
alias in the field list of the view.
extend view entity /DMO/R_AgencyTP with

composition [0..*] of /DMO/ZZ_R_Agency_ReviewTP as /DMO/ZZ_ReviewZAG
{
/DMO/ZZ_ReviewZAG
}

 Note
also used for extension elements in this example. In a productive environment, the namespace prefix
of extensions elements differs from the namespace of the original business object. This is indicated by
the addition ZZ after the /DMO/ namespace.

Extend PUBLIC 1009
2. Create a CDS extension view called /DMO/ZZ_X_REVIEW_I_AGENCY for the CDS view /DMO/I_AgencyTP.
Extend the CDS view /DMO/I_AgencyTP with the composition added to the CDS view /DMO/R_AgencyTP
in the previous step and redirect it to the CDS view /DMO/ZZ_I_Agency_ReviewTP. Since you have
already extended the CDS view /DMO/R_AgencyTP with the composition, you can use the data source
alias Agency defined in the CDS view /DMO/I_AgencyTP in a path expression to access the composition
via its alias /DMO/ZZ_ReviewZAG.
extend view entity /DMO/I_AgencyTP with

{
Agency./DMO/ZZ_ReviewZAG : redirected to composition child /DMO/
ZZ_I_Agency_ReviewTP
}

3. Create a CDS extension view called /DMO/ZZ_X_REVIEW_C_AGENCY for the CDS view /DMO/C_AgencyTP.
Extend the CDS view /DMO/C_AgencyTP with the composition added to the CDS view /DMO/R_AGENCYTP
in step one and redirect it to the CDS view /DMO/ZZ_C_Agency_ReviewTP. Since you have already
extended the CDS view /DMO/R_AGENCYTP with the composition, you can use the data source alias
Agency defined in the CDS view /DMO/C_AgencyTP in a path expression to access the composition via its
alias /DMO/ZZ_ReviewZAG.
Define UI annotations that enable the display of corresponding review instances on the UI object page of
agency instances.

{
@UI.facet: [
{
id: 'Review',
purpose: #STANDARD,
label: 'Review',
position: 20,
targetElement: '/DMO/ZZ_ReviewZAG'
}
]
Agency./DMO/ZZ_ReviewZAG : redirected to composition child /DMO/
ZZ_C_Agency_ReviewTP
}

Result
You have added the extension node to the CDS data model. In the next step, you define its behavior and include
it in the behavior of the original business object, see Extending the Behavior for the Node Extension [page
1011].

1010 PUBLIC Extend
5.3.2.3.3 Extending the Behavior for the Node Extension
In this chapter, you define the behavior for the extension node and integrate it into the behavior of the original
business object.
Procedure
1. In the context menu of the behavior definition /DMO/R_AGENCYTP, choose the option New Behavior
Extension.
stored as well as the name /DMO/ZZ_X_REVIEW_R_AGENCYTP, a description and the BO interface /DMO/
I_AGENCYTP.
The resulting BDEF extension looks like this and is ready for defining the extension behavior as described in
the following section.

implementation in class /dmo/zz_bp_x_review_r_agencytp unique;
3. Below the generated code in the behavior definition extension, add the keywords extend behavior
for /DMO/Agency { }. The extension behavior can now be defined within the curly brackets.

{

}
4. In order to ensure adequate message handling, you need to add validations of the extension node to the
draft determine action Prepare of the original business object.
 Note
The validation /DMO/ratingInRange has not been defined so far. You will catch up on that in the
definition section of the extension node.

{
extend draft determine action Prepare{
validation /DMO/ZZ_Review~/DMO/ratingInRange;
}

}
5. You will define the update and the delete operation in the definition section of the extension node. However,
in order to enable the creation of Review instances from a given Agency instance of the root node,
you need to extend the original business object with a create-by-association operation using the defined
composition /DMO/ZZ_ReviewZAG.

{
}
association /DMO/ZZ_ReviewZAG { create; with draft; }


Extend PUBLIC 1011
}
6. Define the behavior for the extension node below the curly brackets of the extend behavior section.
Use the keywords using /DMO/ZZ_I_AGENCY_REVIEWTP behind the define behavior statement to
establish a symmetrical relation between the node of the original BO and the node of the extension with
respect to their interfaces.
Since extension nodes are always in a to-parent relationship, the lock and authorization behavior is
modeled as dependent. An etag master is defined as recommended for extension nodes. Note that
the extension node contains the reverse association _Agency to the root node.
Ancestor associations don't need to be defined in this case as the root node is reachable directly via the
_Agency association.

{
}
association /DMO/ZZ_ReviewZAG { create; with draft; }
}
define behavior for /DMO/ZZ_R_AGENCY_REVIEWTP alias /DMO/ZZ_Review using /DMO/
ZZ_I_AGENCY_REVIEWTP
persistent table /DMO/ZZ_AGN_REVA
draft table /DMO/ZZ_AGN_REVD
lock dependent
late numbering
{
update ( features : instance );
delete ( features : instance );
field ( readonly ) ReviewID, AgencyID, HelpfulCount, HelpfulTotal, Reviewer;
action ( authorization: global ) /DMO/reviewWasHelpful result [1] $self;
action ( authorization: global ) /DMO/reviewWasNotHelpful result [1] $self;
validation /DMO/ratingInRange on save { create; field Rating; }
association _Agency { with draft; }
mapping for /dmo/zz_agn_reva
{
AgencyId = agency_id;
ReviewId = review_id;
Rating = rating;
FreeTextComment = free_text_comment;
HelpfulCount = helpful_count;
HelpfulTotal = helpful_total;
Reviewer = reviewer;
}

}
7. Use the quickfix offered for the line implementation in class zbp_cs_r_agency_ext_review
unique;
8. Generate the draft table by using the quick fix offered for line draft table /DMO/ZZ_AGN_REVD.
9. In the context menu of the behavior definition /DMO/C_AGENCYTP, choose the option New Behavior
Extension.
stored as well as the name /DMO/ZZ_X_REVIEW_C_AGENCYTP and a description.

1012 PUBLIC Extend
In the generated BDEF, remove the keywords in the line after extension for projection. The resulting
BDEF extension looks like this and is ready for defining the extension behavior as described in the following
section.

extend behavior for /DMO/Agency {

}
11. Extend the projection layer of the original business object with the composition /DMO/ZZ_ReviewZAG
from the base BDEF extension.

{
use association /DMO/ZZ_ReviewZAG { create; with draft; }

}
12. Define the behavior for the extension node on the projection layer. Use the update and the delete
operation, the actions /DMO/reviewWasHelpful and /DMO/reviewWasNotHelpful as well as the
reverse association to the parent from the base BDEF extension.

{
use association /DMO/ZZ_ReviewZAG { create; with draft; }
}
define behavior for /DMO/ZZ_C_Agency_ReviewTP alias /DMO/ZZ_Review
{
use update;
use delete;
use action /DMO/reviewWasHelpful;
use action /DMO/reviewWasNotHelpful;
use association _Agency { with draft; }

}
Result
You have extended the behavior of the original business object for the node extension. You can now implement
the defined behavior, see Implementing the Behavior for the Node Extension [page 1013].
5.3.2.3.4 Implementing the Behavior for the Node

Extension
In this chapter, you implement the behavior defined for the node in the previous chapter.
The implementation of behavior defined in a behavior extension follows the same approach as the
implementation of behavior defined for an original business object. There is no special class syntax required
related to extensibility. However, there are differences when it comes to accessing the original business object
from extensions via EML.
 Note
An interface is the consolidated consumption point of a business object, which needs to be used by
every consumer. This also applies to extenders who access the original business object via EML in their

Extend PUBLIC 1013
extensions. This is why EML statements in behavior extension implementations must always address the
original business object via its interface.
If the keywords IN LOCAL MODE are used in an EML statement of a behavior extension, only the
feature control and authorization implementations of this extension are bypassed. Feature control and
authorization implementations of the original business object are not bypassed with such a statement.
The following sections describe the required steps to implement the extension behavior.
Implementing the Method get_instance_features
Read all reviewers of review instances that need to be validated.
Enable the update and the delete operation for all reviewers with an existing user.

ENTITY /dmo/zz_review
FIELDS ( reviewer )
RESULT DATA(reviews)
FAILED failed.
result = VALUE #(
FOR review IN reviews
LET enabled = COND #( WHEN review-reviewer =
cl_abap_context_info=>get_user_technical_name( )
THEN if_abap_behv=>fc-o-enabled
ELSE if_abap_behv=>fc-o-disabled ) IN
(
%tky = review-%tky
%update = enabled
%delete = enabled
)
).

ENDMETHOD.
Implementing the Method reviewWasHelpful
Read all fields of review instances the action is executed on.
Increment the number of helpful votes as well as the number of total votes by 1 for every review instance in an
internal table and append the instances to the result table of the action.
Update the number of helpful votes and the number of total votes for the respective instances using the
updated internal table.
METHOD reviewwashelpful.

FAILED failed.
LOOP AT reviews ASSIGNING FIELD-SYMBOL(<review>).
<review>-helpfulcount += 1.

1014 PUBLIC Extend
<review>-helpfultotal += 1.
APPEND VALUE #(
%tky = <review>-%tky
%param = CORRESPONDING #( <review> )
) TO result.
ENDLOOP.
UPDATE FIELDS ( helpfulcount helpfultotal )
WITH CORRESPONDING #( reviews ).

ENDMETHOD.
Implementing the Method reviewWasNotHelpful
Read all fields of review instances the action is executed on.
Increment the number of total votes by 1 for every review instance in an internal table and append the instances
to the result table of the action.
Update the number of total votes for the respective instances using the updated internal table.
METHOD reviewwasnothelpful.

FAILED failed.
LOOP AT reviews ASSIGNING FIELD-SYMBOL(<review>).
<review>-helpfultotal += 1.
APPEND VALUE #(
%tky = <review>-%tky
%param = CORRESPONDING #( <review> )
) TO result.
ENDLOOP.
UPDATE FIELDS ( helpfultotal )
WITH CORRESPONDING #( reviews ).

ENDMETHOD.
Implementing the Method ratingInRange
Read the ratings of all review instances to be validated as well as the keys of their corresponding agency
instances.
For every read review instance, clear the state area. If the rating of a review instance is higher than 5 or lower
than 1, append a message to the reported structure that identifies the affected review and the corresponding
agency instance.
METHOD ratinginrange.

FIELDS ( rating )
ENTITY /dmo/zz_review BY \_agency

Extend PUBLIC 1015
FROM CORRESPONDING #( keys )
LINK DATA(agency_links).
LOOP AT reviews INTO DATA(review).
APPEND VALUE #(
%tky = review-%tky
%state_area = rating_in_range
) TO reported-/dmo/zz_review.
IF review-rating > 5 OR review-rating < 1.
APPEND VALUE #(
%tky = review-%tky
%state_area = rating_in_range
%msg = NEW /dmo/zz_cx_agency_review( /dmo/
zz_cx_agency_review=>rating_invalid )
%element-rating = if_abap_behv=>mk-on
%path-/DMO/Agency-%tky = VALUE #( agency_links[ KEY draft source-
%tky = review-%tky ]-target-%tky OPTIONAL )
) TO reported-/dmo/zz_review.
APPEND VALUE #( %tky = review-%tky ) TO failed-/dmo/zz_review.
ENDIF.
ENDLOOP.

ENDMETHOD.
Implementing the Method adjust_numbers
Perform late numbering only, if the mapped response for the review node is not empty - in other words, if there
are review instances that require keys.
Store all distinct agency IDs contained in the mapped response for the review in an internal table called
agencies. Terminate the execution if there are no agency IDs in this internal table.
Create an internal table called max_reviews that contains the highest review ID from the table /dmo/
zz_agn_reva for each agency ID of the agencies table.
For every distinct agency ID in the mapped response of the review node, store the highest review ID in the
variable max_review_id. For every review with the current agency ID, assign a new review ID. The new review
ID is calculated by incrementing the variable max_review_id by 1.

TYPES: t_mapped_review TYPE STRUCTURE FOR MAPPED LATE /dmo/
zz_i_agency_reviewtp.
DATA: agencies TYPE STANDARD TABLE OF /dmo/agency_id WITH KEY table_line.
FIELD-SYMBOLS: <mapped_review> TYPE t_mapped_review.
CHECK mapped-/dmo/zz_review IS NOT INITIAL.
LOOP AT mapped-/dmo/zz_review ASSIGNING <mapped_review> GROUP BY
<mapped_review>-%tmp-agencyid.
APPEND <mapped_review>-%tmp-agencyid TO agencies.
ENDLOOP.
ASSERT agencies IS NOT INITIAL.
SELECT
FROM /dmo/zz_agn_reva AS db
JOIN @agencies AS itab
ON db~agency_id = itab~table_line
FIELDS DISTINCT
db~agency_id,
MAX( db~review_id ) AS max_review_id
GROUP BY db~agency_id
INTO TABLE @DATA(max_reviews).
LOOP AT mapped-/dmo/zz_review INTO DATA(mapped_review_group) GROUP BY
mapped_review_group-%tmp-agencyid.
DATA(max_review_id) = VALUE #( max_reviews[ agency_id =
mapped_review_group-%tmp-agencyid ]-max_review_id OPTIONAL ).

1016 PUBLIC Extend
LOOP AT mapped-/dmo/zz_review ASSIGNING <mapped_review> WHERE %tmp-
agencyid = mapped_review_group-%tmp-agencyid.
<mapped_review>-agencyid = <mapped_review>-%tmp-agencyid.
max_review_id += 1.
<mapped_review>-reviewid = max_review_id.
ENDLOOP.
ENDLOOP.

ENDMETHOD.
Result
You have implemented the behavior for the extension node. You can now add the service definition of the
original business object with the extension node to provide it for service consumption, see Including the
Extension Node in the Service Exposure [page 1017].
5.3.2.3.5 Including the Extension Node in the Service

Exposure
In this step, you create a service definition extension for the review node and add it to service of the original BO.
 Note
It is currently not possible to release service definitions for extensions in other software components (C0
contract). Node extenders can therefore not extend service definitions that originate from another software
component. The consumption of node extensions from other software components is only possible via
EML or via a service built on top of the business object interface.
Procedure
1. In the context menu of the service definition /DMO/UI_AGENCY, choose the option New Service
Definition.
2. In the service definition creation dialogue, enter the name of the package where the service definition
extension is to be stored as well as the name /DMO/ZZ_X_REVIEW_UI_AGENCY, a description and the type
Extension.
The resulting service definition extension looks like this and is ready for defining the extension behavior as
described in the following section.
extend service /DMO/UI_AGENCY with {

}
3. Expose the CDS projection view /DMO/ZZ_C_Agency_ReviewTP with the alias /DMO/ZZ_Review.
extend service /DMO/UI_AGENCY with {

expose /DMO/ZZ_C_Agency_ReviewTP as /DMO/ZZ_Review;

}

Extend PUBLIC 1017
Result
You have added the extension node to the service of the original business object. The node can now be
consumed using the service /DMO/UI_AGENCY.

1018 PUBLIC Extend
6 Test
This section provides detailed step-by-step descriptions on how to develop automated tests for the different
artifacts of RAP business objects and for related OData services.
Motivation
In times of ever shortening development cycles, continuous delivery and cloud deployments, manual
regression tests of business applications are no reasonable choice for efficient software quality assurance.
Regression tests are time and cost consuming and bear the risk of slips as they are performed for every
new software release manually. Automated tests, however, guarantee an ever-constant test execution with a
significantly lower consumption of resources.
Fiori applications built with the ABAP RESTful Application Programming model require automated tests
tailored for the different artefact types on multiple test levels.
Scope
The current version of this guide focuses on unit tests and on integration tests. Use the links below to navigate
to the particular sections of this guide.
Test Design
The test classes you will develop in this section serve as examples on how automated tests can be developed.
The chosen test design, however, is not supposed to serve as a blueprint. How the test classes are structured,
how many test methods are created respectively and how the test code is allocated among these test methods,
depends on the individual logic to be tested and on the desired degree of test granularity.
Content of this Guide
Prerequisites [page 1020]
Test Concepts [page 1020]
Unit Tests [page 1026]
Integration Tests [page 1059]

Test PUBLIC 1019
Dependency Management with RAP BO Test Double Framework
The RAP BO Test Double Framework enables the isolation of RAP Business Objects as dependencies, thus
helping to focus on the logic to be tested.
For more information about the RAP BO Test Double Framework, see . The RAP BO Test Double Framework is
not used in this version of the Test Guide.
6.1 Prerequisites
ABAP Unit
You are familiar with the ABAP Unit framework and know the main components and syntax elements of ABAP
test classes.
For more information, see ABAP Unit (ABAP - Keyword Documentation).
ABAP Unit in ABAP Development Tools
You know how to write, launch and evaluate ABAP Unit tests in ABAP Development Tools.
Dependency Management
You know the concepts of dependency management and are familiar with the CDS Test Double Framework and
the SQL Test Double Framework.
6.2 Test Concepts
This chapter contains information about the different test concepts applied when testing RAP business
objects.

1020 PUBLIC Test
Unit Tests
Unit tests focus on the smallest software components in the overall system architecture. Every unit is isolated
from other units as much as possible in order to prevent the impact from external factors. Thus, the reason for
failed unit tests can be directly traced back to the component, which has been tested.
Integration Tests
Whereas a unit test focuses on an individual software component, an integration test validates the integration
of multiple software components contributing to the same application scenario. Even though every single
software component of such a group might have been validated successfully by a unit test, the application
scenario might not work as expected. For example, when the result determined by a software component is
processed incorrectly by another software component. Integration tests check the correct interaction between
software components and ensure the correct operability of their interfaces.
6.3 Basic Test Class Structure
There are essential test class elements that can be applied to any RAP test class. These elements form a
basic test class structure which is explained in this chapter. The explained test class structure can serve as a
template for RAP test classes.
Test Class Definition
The definition section of the test class contain basic meta information, reference variables and declarations for
the fixture and test methods.
Assigning Test Properties

Depending on the complexity of your tests, choose a suiting duration time for your test class. Smaller test
classes usually have an execution time of less than 5 seconds. In this case, you can use the DURATION SHORT.
Depending on the respective run mode and runtime monitor, exceeding the chosen execution time can affect
the results of your test.
By using test doubles, you prevent persistent data from being changed during your tests. If no persistent data
or system settings are changed, you can use the RISK LEVEL HARMLESS. If the chosen risk level is higher than
allowed in your system, your tests are not executed.
CLASS ltc_class_name DEFINITION FINAL FOR TESTING

DURATION SHORT

RISK LEVEL HARMLESS.

Test PUBLIC 1021
Specifying the Test Relation
A test relation links your test class to the object to be tested. After specifying a test relation for a behavior
implementation, a CDS view or a service, all of their related tests can be executed directly from their context
menu in the Project Explorer of ADT. A test relation is specified above the class definition statement. For
behavior implementations, the name of the corresponding behavior definition follows after the keyword BDEF:.
For service bindings, the prefix SRVB is used.
"! @testing [BDEF:BDEF_name] | [CDS_view_name] | [SRVB:SRVB_name]

CLASS ltc_class_name DEFINITION FINAL FOR TESTING

Declaring Reference Variables

For unit tests of a behavior implementation, instantiate the corresponding class. For this purpose, declare a
reference variable for this class in the private section. In the example below, the name of the tested behavior
implementation class is lhc_name.
The CDS and SQL test double framework can be used to create test doubles that will be used in your tests. In
order to use one of these frameworks, you need to declare reference variables for their interfaces as well.
For OData tests using the Local Client Proxy, declare a reference variable for its interface.
PRIVATE SECTION.

CLASS-DATA: class_under_test TYPE REF TO lhc_name,
cds_test_environment TYPE REF TO if_cds_test_environment,
sql_test_environment TYPE REF TO if_osql_test_environment,

go_client_proxy TYPE REF TO /iwbep/if_cp_client_proxy.
Declaring Fixture and Test Methods

In addition to the declaration of your test methods, declare fixture methods. Fixture methods are used to set up
and tear down the test environment which produces unique test behavior for every executed test. The declared
test methods may have the same name as the methods to be tested.
CLASS-METHODS:

class_setup,
class_teardown.
METHODS:
setup,
teardown,

method_name FOR TESTING.
Test Class Implementation
This section contains the implementation of the fixture and test methods declared above.
Implementing the Method class_setup

For unit tests of a behavior implementation, create an object of the corresponding class using the reference
variable declared above. The addition FOR TESTING enables instantiating handler classes of behavior
implementations.
For OData tests, create an instance of the Local Client Proxy and assign it to a reference variable which you will
use in your test method to create the desired OData request. For a concrete example class which uses the Local

1022 PUBLIC Test
Client Proxy interface to create Proxy instances for different systems, see Refining the Test Class Structure
[page 1076].
Now, create a test double for the required database tables with the CDS test double framework or the SQL test
double framework. Choose the CDS test double framework, if the data access is performed via the CDS entities
in your code under test. Choose the SQL test double framework, if your test involves direct database access
using OpenSQL.
To create a test double using the CDS test double framework, you can use the create method and provide
the name of the CDS view selecting the database table that is to be doubled. As a result, the test double
is called for data access during the test instead of the real database table. Assign the reference to the
created test environment object to the interface reference variable declared above. For creating multiple
test doubles, the CDS test double framework offers the method create_for_multiple_cds. If the test
double is to be accessed not only via the CDS view, but also via Open SQL calls, additionally use the method
enable_double_redirection. The SQL test double framework does not need to be used additionally for
this case. The double redirection is automatically enabled if the method create_for_multiple_cds is used.
To create a test double using the SQL test double framework, you can use the create method and provide the
name of the database tables that are to be doubled. As a result, the test doubles are called for data access
during the test instead of the real database tables. Assign the reference to the created test environment object
to the interface reference variable declared above.
If the data for your test doubles don't depend on the particular test cases of your test methods, you can insert
the test data into your test doubles already in the class setup method. To do so, declare a table, type it with the
created test double and insert the desired test data into the table. Next, insert the test data into your double by
means of the populated table.
METHOD class_setup.

CREATE OBJECT class_under_test FOR TESTING. "For unit tests of behavior
implementations
go_client_proxy = [Call of creation methods for Local Client Proxy]
cds_test_environment = cl_cds_test_environment=>create( i_for_entity =
'CDS_view1' ).
cds_test_environment = cl_cds_test_environment=>create_for_multiple_cds(
VALUE #(
( i_for_entity = 'CDS_view1' )
)
). "For multiple test doubles
cds_test_environment->enable_double_redirection( ). "For Open SQL access to
the test double
sql_test_environment = cl_osql_test_environment=>create( i_dependency_list
= VALUE #(
( 'database1' )
( 'database2' )
( 'database3' )
) ) .
" Insert test data into CDS test double
DATA cds_mock_data TYPE STANDARD TABLE OF test_double.
cds_mock_data = VALUE #( ( instance_data ) ).
cds_test_environment->insert_test_data( cds_mock_data ).
" Insert test data into SQL test double
DATA sql_mock_data TYPE STANDARD TABLE OF test_double.
sql_mock_data = VALUE #( ( instance_data ) ).
sql_test_environment->insert_test_data( sql_mock_data ).

ENDMETHOD.

Test PUBLIC 1023
Implementing the Method setup
To make sure that your test methods are not influenced by data of other test methods, clear the contents of the
test doubles before every test method execution if required.
METHOD setup.

cds_test_environment->clear_doubles( ).
sql_test_environment->clear_doubles( ).
ENDMETHOD.

Implementing the Method teardown

To make sure that the transactional buffer is reset for the involved entities after every test method execution,
use the EML statement ROLLBACK ENTITIES in the teardown method.
METHOD teardown.

ROLLBACK ENTITIES.

ENDMETHOD.
Implementing the Method class_teardown

At the end of the test, clear the test environments and the created test doubles.
METHOD class_teardown.

cds_test_environment->destroy( ).
sql_test_environment->destroy( ).

ENDMETHOD.
Implementing the Test Methods for Unit Tests

Irrespective of the object to be tested, implementing test methods for unit tests usually involves a number of
fundamental steps.
At first, insert the test data into the test doubles using the respective test double framework. To do so, declare
a table, type it with the created test double and insert the desired test data into the table. Next, insert the test
data into your double by means of the populated table.
Next, the object under test is called. If you want to test a behavior implementation, call the method to be tested
and provide the data required respectively, usually the keys of the instances in the test double. If you want to
test a CDS view, perform a SELECT operation on the tested fields of the CDS view and save the results in an
internal table.
Finally use assertion methods of the class cl_abap_unit_assert to check the returned values against
the expected ones. For example, you can check whether a value returned by the test method equals an
expected value. The assert checks are usually preceded by some preparatory tasks like reading the result of
the operation performed during the test or populating internal tables used to compare with the result. Which of
these tasks is relevant, depends on the respective RAP artefact and the logic to be tested.
 Expand the following code sample to view the source code of the method method_name.
 Sample Code
METHOD method_name.

" Insert test data into CDS test double
DATA cds_mock_data TYPE STANDARD TABLE OF test_double.
cds_mock_data = VALUE #( ( instance_data ) ).
cds_test_environment->insert_test_data( cds_mock_data ).
" Insert test data into SQL test double
DATA sql_mock_data TYPE STANDARD TABLE OF test_double.

1024 PUBLIC Test
sql_mock_data = VALUE #( ( instance_data ) ).
sql_test_environment->insert_test_data( sql_mock_data ).
" Run test for behavior implementation method
class_under_test->method_under_test(
keys = CORRESPONDING #( mock_data ) ).
" Run test for CDS view
SELECT * FROM cds_view INTO TABLE @DATA(act_results).
" Preparatory tasks for assert checks
...
" Perform assert checks
cl_abap_unit_assert=>assert_equals( msg = 'message when assert fails' act =
returned_value exp = expected_value ).

ENDMETHOD.
Implementing the Test Methods for EML Integration Tests

Every EML integration test involves a number of fundamental steps. At first, perform the desired EML call and
save the response parameters in respective variables. You can then use these variables to check whether the
EML call has been executed as expected.
In cases where instance data needs to be read to validate the test result, you can now perform an EML READ
call on the business object. Save the result in respective variables.
Finally use assertion methods of the class cl_abap_unit_assert to check the actual values against the
expected ones. For example, you can check whether a value returned in the read result equals an expected
value.
The EML statements used in the following code block are just examples and need to be chosen according to the
given test case.
 Sample Code
METHOD method_name.

" Create a Travel
MODIFY ENTITIES OF /dmo/i_travel_m
ENTITY travel
CREATE FIELDS ( ) WITH
VALUE #( ( ) )
MAPPED DATA(mapped_create)
FAILED DATA(failed_create)
REPORTED DATA(reported_create).
" Perform assert checks to validate intermediate result
" Read result
READ ENTITIES OF /dmo/i_travel_m
ENTITY travel
FIELDS ( )
WITH VALUE #( ( ) )
RESULT DATA(result)
FAILED DATA(failed_read).
" Perform assert checks to validate test result

ENDMETHOD.

Test PUBLIC 1025
Implementing the Test Methods for OData Integration Tests
Every OData integration test involves a number of fundamental steps. At first, create the desired OData request
and assign a reference to it to a variable.
Execute the created request and assign a reference to its response to another variable.
Check whether there is a response to the executed request.
Get the business data of the response and perform the desired assert checks on them.
 Sample Code
METHOD method_name.

"Create OData request
DATA(lo_request) = go_client_proxy-
>create_resource_for_entity_set( 'Booking' )->create_request_for_read( ).
"Execute OData request
"Check request response
cl_abap_unit_assert=>assert_not_initial( lo_response ).
"Get the business data from the response
DATA ls_response_data TYPE STANDARD TABLE OF [CDS entitiy].
ls_response_data ).
"Compare the business data to the expected result
cl_abap_unit_assert=>assert_equals( exp = [expected values] act =
ls_response_data ).

ENDMETHOD.
6.4 Unit Tests
This section shows how the described concepts of unit tests apply in RAP. It contains step-by-step guides
explaining how to develop unit tests for CDS views and behavior implementations.
6.4.1 Developing Unit Tests for a CDS View
In this chapter, you are guided through all the steps necessary to develop unit tests for a CDS view by an
example test implementation.
Test Scope
The CDS logic you will focus on in your unit tests is a calculation, which uses the value of a field Price
and applies a discount of 10% if the price is greater than 1000 in the respective currency. The discount
is subtracted from the difference between the price and 1000. The result is used as the value of the field

1026 PUBLIC Test
PriceWithDiscount. If the price is equal to or lower than 1000 or if the price is initial, the price itself is used
as the field value.
Calculation Result
The price after discount is calculated by the formula 1000 + (Price - 1000) * 0.9. This calculation logic
can be implemented in a CDS view using the following code snippet. Add it to the CDS view /DMO/I_Flight_R
of the read-only flight reference scenario (package /DMO/FLIGHT_READONLY) and then develop the unit tests
for this logic as described in the following chapters.

...
case
when price <= 1000 or price is initial
then cast(price as /dmo/flight_price preserving type )
else
cast( 1000 +
( cast(
price as abap.dec(16,2)
) - 1000
) * division( 9, 10, 2 )
as /dmo/flight_price
)
end as PriceWithDiscount,
...

}
Contents
Creating the Test Class [page 1028]
Refining the Test Class Structure [page 1029]
Implementing the Test Methods [page 1031]

Test PUBLIC 1027
6.4.1.1 Creating the Test Class
In this step, you will create the test class which will serve as the basis for the unit tests to be developed.
Test classes for CDS views can be created using a wizard, which considers the database dependencies to be
doubled as well the data to be inserted into the test doubles. The result is a test class that already contains a
basic structure, which you will refine in the following chapter.

2. In your ABAP project (or ABAP cloud project), select the CDS view /DMO/I_Flight_R.
3. Open the context menu and select New ABAP Test Class to launch the creation wizard.
In the creation wizard, provide the name /DMO/CL_DISCOUNTCALC, select the test type Unit Test, and
make sure that the database table /dmo/flight to be doubled is selected. There is no need to specify the
name of a test method or to provide data for the test double. You will perform these tasks in the code as
part of the following chapter.
By completing the wizard, you created the basic structure of your test class in the tab Test Classes. The test
class is named according to the tested CDS view.
Further information: (Tool Reference).
 Expand the following code sample to view the source code of the test class ltc_/DMO/I_FLIGHT_R.
 Sample Code
"!@testing /DMO/I_FLIGHT_R

CLASS ltc_/DMO/I_FLIGHT_R
DEFINITION FINAL FOR TESTING
DURATION SHORT
PRIVATE SECTION.
CLASS-DATA:
environment TYPE REF TO if_cds_test_environment.
CLASS-METHODS:
class_setup RAISING cx_static_check,
class_teardown.
DATA:
act_results TYPE STANDARD TABLE OF /DMO/I_FLIGHT_R WITH EMPTY KEY,
lt_/dmo/flight TYPE STANDARD TABLE OF /dmo/flight WITH EMPTY KEY.
METHODS:
setup RAISING cx_static_check,
prepare_testdata_set,
aunit_for_cds_method FOR TESTING RAISING cx_static_check.
ENDCLASS.
CLASS ltc_/DMO/I_FLIGHT_R IMPLEMENTATION.
METHOD class_setup.
environment = cl_cds_test_environment=>create( i_for_entity = '/DMO/
I_FLIGHT_R' ).
ENDMETHOD.
METHOD setup.
environment->clear_doubles( ).
ENDMETHOD.
environment->destroy( ).
ENDMETHOD.
METHOD aunit_for_cds_method.
prepare_testdata_set( ).
SELECT * FROM /DMO/I_FLIGHT_R INTO TABLE @act_results.
cl_abap_unit_assert=>fail( msg = 'Place your assertions here' ).
ENDMETHOD.
METHOD prepare_testdata_set.
"Prepare test data for '/dmo/flight'

1028 PUBLIC Test
lt_/dmo/flight = VALUE #(
(
client = '100'
) ).
environment->insert_test_data( i_data = lt_/dmo/flight ).
ENDMETHOD.

ENDCLASS.
6.4.1.2 Refining the Test Class Structure
Now that you have created the basic test class structure, you can refine this structure and provide the basis for
the test methods that you will implement in the following chapter.
This topic covers the specific structure of the test class for the CDS view. For general information on the
structure of RAP test classes, see Basic Test Class Structure [page 1021].
Used Test Class Components
The test class you created using the wizard in the previous chapter already contains components which you
can use in your test class:
• Test properties
The DURATION SHORT and the RISK LEVEL HARMLESS have already been added to your test class. Since
the tested code has a relatively small size and you will not change persistent data or system settings with
your unit tests, these properties are suitable for your test class.
• Test relation
The test relation of your test class to the tested CDS view is specified using the expression "!
@testing /DMO/I_FLIGHT_R. This test relation enables you to run the unit tests directly via the context
menu of the CDS view.
• Reference variable for CDS Test Double Framework
The reference variable environment pointing to the interface of the CDS Test Double Framework has
been specified. You will use this reference variable to create an instance of the test environment and a test
double for the database table selected by the tested CDS view.
• Fixture methods
The fixture method class_setup creates the test environment and a test double for the database table
selected by the tested CDS view /DMO/I_FLIGHT_R before the execution of the test methods.
The fixture method setup clears the CDS test double before every test method execution, thus preventing
interferences from previous test method executions.
The fixture method class_teardown deletes the CDS test environment and the test double after all test
methods have been executed.
• Test execution statement
The following statement contained in the generated test method aunit_for_cds_method executes the
test by reading all data selected by the CDS view.
SELECT * FROM /DMO/I_FLIGHT_R INTO TABLE @act_results.

Test PUBLIC 1029
The table act_results is declared in the private section using the type of the CDS view /DMO/
I_FLIGHT_R.
Adjusting the Test Class
The following components of your test class need to be adjusted before you can start with the implementation
of the test methods.
Declaring the Test Methods

Declare the following test methods to test the calculation logic of the CDS view and insert their signatures in
the implementation part of the class using the offered quick fix.
METHODS:

...
"! Check for value greater than 1000
above_threshold FOR TESTING,
"! Check for value lower than 1000
below_threshold FOR TESTING,
"! Check for initial value
initial_value FOR TESTING,
"! Check for value 1000
equal_to_threshold FOR TESTING.

Adjusting the SELECT statement

Your unit test only checks the field PriceWithDiscount in a single dataset. Hence, adjust the SELECT
statement as follows:
SELECT SINGLE PriceWithDiscount FROM /DMO/I_FLIGHT_R INTO @DATA(act_result).
Removing unused code

Remove the generated method prepare_testdata_set from the definition and from the implementation
part of the class. The method inserts the test data into the double and can be called from each test method
before the tests are executed. Since you will provide different data for the test double in every test method, the
method prepare_testdata_set is not required.
Copy the SELECT statement from the method aunit_for_cds_method to the implementation of each of
your test methods. Next, delete the method aunit_for_cds_method from the definition and from the
implementation part of the class.
Remove the declarations for the tables act_results and lt_/dmo/flight.
After performing the described adjustments, your test class looks like this and is ready for the implementation
of the test methods:
 Expand the following code sample to view the source code of the test class ltc_/DMO/I_FLIGHT_R.
 Sample Code
"!@testing /DMO/I_FLIGHT_R

CLASS ltc_/DMO/I_FLIGHT_R DEFINITION FINAL FOR TESTING
DURATION SHORT

1030 PUBLIC Test
PRIVATE SECTION.
CLASS-DATA:
environment TYPE REF TO if_cds_test_environment.
CLASS-METHODS:
"! Setup CDS Test Double Framework
"! Destroy CDS Test Environment and test double
class_teardown.
METHODS:
"! Reset test double
setup RAISING cx_static_check,
"! Check for value greater than 1000
above_threshold FOR TESTING,
"! Check for value lower than 1000
below_threshold FOR TESTING,
"! Check for initial value
initial_value FOR TESTING,
"! Check for value 1000
equal_to_threshold FOR TESTING.
ENDCLASS.
CLASS ltc_/DMO/I_FLIGHT_R IMPLEMENTATION.
METHOD class_setup.
environment = cl_cds_test_environment=>create( i_for_entity = '/DMO/
I_FLIGHT_R' ).
ENDMETHOD.
METHOD setup.
environment->clear_doubles( ).
ENDMETHOD.
environment->destroy( ).
ENDMETHOD.
METHOD above_threshold.
SELECT SINGLE PriceWithDiscount FROM /DMO/I_FLIGHT_R INTO
@DATA(act_result).
ENDMETHOD.
METHOD below_threshold.
@DATA(act_result).
ENDMETHOD.
METHOD initial_value.
@DATA(act_result).
ENDMETHOD.
METHOD equal_to_threshold.
@DATA(act_result).
ENDMETHOD.

ENDCLASS.
6.4.1.3 Implementing the Test Methods
This chapter shows how you can implement unit tests for the calculation logic in the CDS view /DMO/
I_Flight_R.
The documentation in this topic only refers to the respective test method. For information on the other parts
of the test class, see Refining the Test Class Structure [page 1029]. For general information on the structure of
RAP test classes, see Basic Test Class Structure [page 1021].

Test PUBLIC 1031
Test Design
The test class contains four test methods, which reflect different cases that are covered by the CDS field
definition. The first test method refers to the case where the price is above the threshold of 1000. The second
one covers the case for a value below the threshold whereas the third case covers the initial value. In the fourth
case, the price is equal to the threshold.
Breaking down the test code into separate test methods facilitates the test maintenance. For instance, if a
dedicated handling for initial price values is implemented, then only the respective test method needs to be
adjusted, all other test methods can be left as they are.
Test Method above_threshold
The test method first adds a travel instance with a price higher than 1000 to the test double. Since the addition
WITH EMPTY KEY is used, there is no need to provide values for the primary key fields.
The actual test is executed by an SQL SELECT statement on the CDS view. The query result is stored in the
variable act_result declared using the type derived from the flight CDS entity.
Finally, the method asserts that the query result is 1450.
METHOD above_threshold.

" Fill in test data
DATA flight_mock_data TYPE STANDARD TABLE OF /dmo/flight WITH EMPTY KEY.
flight_mock_data = VALUE #( ( price = '1500' ) ).
environment->insert_test_data( i_data = flight_mock_data ).
" Execute test
SELECT SINGLE PriceWithDiscount FROM /dmo/i_flight_r INTO @DATA(act_result).
" Check result
cl_abap_unit_assert=>assert_equals( act = act_result exp = '1450' msg =
'PriceWithDiscount' ).

ENDMETHOD.
Test Method below_threshold
This test method follows the same approach as the test method above, but this time, a price below 1000 is
chosen. The same price is used as the expected value in the assert check.
METHOD below_threshold.

" Fill in test data
" Execute test
" Check result

ENDMETHOD.

1032 PUBLIC Test
Test Method initial_value
This test method follows the same approach as the test methods above, but this time, an initial value is used
for the price. Consequently, the value "0" is used as the expected value in the assert check.
METHOD initial_value.

" Fill in test data
flight_mock_data = VALUE #( ( price = '' ) ).
" Execute test
" Check result

ENDMETHOD.
Test Method equal_to_threshold
This test method follows the same approach as the test methods above, but this time, the value "1000" is used
for the price. The same price is used as the expected value in the assert check.
METHOD equal_to_threshold.

" Fill in test data
" Execute test
" Check result

ENDMETHOD.
6.4.2 Developing Unit Tests for a Behavior Implementation
In this chapter, you are guided through all the steps necessary to develop unit tests for behavior
implementations.
The unit tests described in this section test methods from the managed and from the draft flight reference
scenario. The tests cover typical RAP methods such as actions, determinations and validations, but don't test
draft characteristics in particular.
Unit tests test the smallest functional units of an application. When accessing a business object from a
consumer's perspective, e.g. via EML, a series of methods can be called by the framework. For instance,
an EML MODIFY CREATE statement does not only trigger the create method, but also all determinations,
validations as well as feature control and authorization implementations affected by the create method. On
the other hand, methods like a validation cannot be called directly from a consumer's perspective as they are
always triggered by another method, e.g. a create method. In order to limit the scope of a test on one single
method, your unit tests will not act from a consumer's perspective, but they will instantiate the class under test

Test PUBLIC 1033
and then call the methods to be tested directly. This enables you to prevent the impact from other methods
and to focus on the methods that you actually want to test.
6.4.2.1 Developing a Test Class for the Managed Flight

Reference Scenario
The test class you develop in this chapter tests methods for the travel entity in the managed flight reference
scenario (package /DMO/FLIGHT_MANAGED).
Tested Methods
The validation validateTravelStatus checks if the value of the overall_status field is valid. In case of an
invalid value, the key of the failed travel instance is appended to the failed structure and a corresponding
message is stored in the reported structure.
The method get_features enables or disables the actions rejectTravel and acceptTravel as well as the
association _Booking depending on the value of the overall_status field.
The validation validate_customer checks if the value of the customer_id field is valid. If the value is initial
or not contained in the database table /dmo/customer, the key of the failed travel instance is appended to the
failed structure and a corresponding message is stored in the reported structure.
The action set_status_accepted sets the value of the field overall status to Accepted.
Contents
Providing Access to Tested Methods [page 1035]
Refining the Test Class Structure [page 1035]
6.4.2.1.1 Creating the Test Class
In this step, you will create the test class, which serves as the basis for the test methods to be developed.
To create the test class, proceed as follows:

2. In your ABAP project (or ABAP cloud project), select the behavior implementation /DMO/BP_TRAVEL_M.

1034 PUBLIC Test
3. In the tab Test Classes, click the button Create Test Class, type the word "test" and use code completion to
insert the test class template.
4. Name the class as ltc_managed and remove the declaration and implementation of the dummy method
first_test.
 Expand the following code sample to view the source code of the test class ltc_managed.
 Sample Code
CLASS ltc_managed DEFINITION FINAL FOR TESTING

DURATION SHORT
PRIVATE SECTION.
ENDCLASS.
CLASS ltc_managed IMPLEMENTATION.

ENDCLASS.
6.4.2.1.2 Providing Access to Tested Methods
The tested methods are private methods. Since you will want to call the methods in order to test them, you
need to set the test class ltc_managed as a friend of the local handler class lhc_travel in the Local Types
tab of the class /DMO/BP_TRAVEL_M. Since the test class is not known to the local handler class at this point,
you need to specify the test class before using the addition DEFINITION DEFERRED FOR TESTING.


FRIENDS ltc_managed.
6.4.2.1.3 Refining the Test Class Structure
Now that you have created the basic test class structure, you can refine this structure by defining basic test
properties, the test relation, variables, and fixture methods that provide the desired test configuration. The
defined test class forms the basis for the test methods that you will implement in the upcoming chapters.
This topic covers the specific structure of the test class for the behavior implementation of the managed flight
reference scenario. For general information on the structure of RAP test classes, see Basic Test Class Structure
[page 1021].
The definition section of the test class contains basic meta information, reference variables and declarations
for the fixture and test methods.

Test PUBLIC 1035
Since the tested methods have a relatively small size, the test code is not expected to have a longer execution
time than 5 seconds. Hence, you can use the DURATION SHORT. Depending on the respective run mode and
runtime monitor, exceeding the chosen execution time can affect the results of your test.
As you won´t change persistent data or system settings with your unit tests, the RISK LEVEL HARMLESS can
be used. If the chosen risk level is higher than allowed in your system, your tests are not executed.

DURATION SHORT


You will develop the unit tests for the business object /DMO/I_Travel_M. Specifying a test relation to this
business object enables you to run your unit tests directly via the context menu of the business object´s
"! @testing BDEF:/DMO/I_Travel_M


...
Declaring Reference Variables

In order to call the methods to be tested, you need to instantiate their class before. For this purpose, declare a
reference variable for the class lhc_travel in the private section.
Since you will use the interfaces of the CDS Test Double Framework and of the SQL Test Double Framework to
mock your test data, you need to declare reference variables for these interfaces as well.
PRIVATE SECTION.

CLASS-DATA: class_under_test TYPE REF TO lhc_travel,

sql_test_environment TYPE REF TO if_osql_test_environment.

In addition to the declaration of your test methods, declare fixture methods. Fixture methods are used to set up
and tear down the test environment which produces unique test behavior for every executed test. The declared
test methods may have the same name as the methods to be tested. For some of the methods, you will develop
multiple test methods to ensure test stability and ease of maintenance.
 Expand the following code sample to view the source code.
 Sample Code
CLASS-METHODS:

"! Instantiate class under test and setup test double frameworks
class_setup,
"! Destroy test environments and test doubles
class_teardown.
METHODS:
"! Reset test doubles
setup,
"! Reset transactional buffer
teardown,
"! Check instance with overall status 'Open'
validate_travel_status_open FOR TESTING,

1036 PUBLIC Test
"! Check instance with overall status 'Accepted'
validate_travel_status_acpt FOR TESTING,
"! Check instance with overall status 'Rejected'
validate_travel_status_rej FOR TESTING,
"! Check instance with invalid overall status
validate_travel_status_invalid FOR TESTING,
"! Check returned features for instance with overall status 'Open'
get_features_open FOR TESTING,
"! Check returned features for instance with overall status 'Accepted'
get_features_accepted FOR TESTING,
"! Check returned features for instance with overall status 'Rejected'
get_features_rejected FOR TESTING,
"! Check returned features for instance with invalid overall status
get_features_invalidstatus FOR TESTING,
"! Check returned features for instance with invalid key
get_features_invalidkey FOR TESTING,
"! Check instance with valid customer ID
validate_customer_valid FOR TESTING,
"! Check instance with invalid customer ID
validate_customer_invalid FOR TESTING,
"! Check instance with initial customer ID
validate_customer_initial FOR TESTING,
"! Check set_status_accepted action

set_status_accepted FOR TESTING.
For information on the design of the particular tests, see:
• Testing the Validation Method validate_travel_status [page 1040]

• Testing the Feature Control Method get_features [page 1043]
• Testing the Validation Method validate_customer [page 1048]
• Testing the Action Method set_status_accepted [page 1051]
This section covers the implementation of the fixture methods that specify the test configuration used by the
test methods.

In order to call a method of the tested class lhc_travel, you need to instantiate this class before. The
addition FOR TESTING enables instantiating handler classes of behavior implementations.
The tested methods contain EML statements that access instance data via the CDS entity Travel. In order to
make these EML statements access the data of a test double database instead of the real database table,
you now need to create a test double using the CDS Test Double Framework. Specify the CDS view /DMO/
I_TRAVEL_M to ensure that the database table /dmo/travel_m is doubled.
The tested method validate_customer contains Open SQL statements for direct database access. In order
to make these SQL statements access the data of a test double instead of the real database, you also need to
create a test double for the database table /DMO/CUSTOMER using the SQL Test Double Framework.
METHOD class_setup.

CREATE OBJECT class_under_test FOR TESTING.
cds_test_environment = cl_cds_test_environment=>create( i_for_entity = '/DMO/
I_TRAVEL_M' ).
sql_test_environment = cl_osql_test_environment=>create( i_dependency_list =
VALUE #( ( '/DMO/CUSTOMER' ) ) ).

Test PUBLIC 1037

ENDMETHOD.

To make sure that your test methods are not influenced by data of other test methods, clear the contents of the
test doubles before every test method execution.
METHOD setup.


ENDMETHOD.

To make sure that the transactional buffer is reset for the involved entities after every test method execution,
use the EML statement ROLLBACK ENTITIES in the teardown method.
METHOD teardown.

ROLLBACK ENTITIES.

ENDMETHOD.



ENDMETHOD.
Resulting Test Class
After following the steps described above, your test class looks like this and is ready for the implementation of
the test methods:
 Expand the following code sample to view the source code of the test class ltc_managed.
 Sample Code
"! @testing BDEF:/DMO/I_Travel_M

DURATION SHORT
PRIVATE SECTION.
sql_test_environment TYPE REF TO if_osql_test_environment.
CLASS-METHODS:
"! Instantiate class under test and setup test double frameworks
class_setup,
"! Destroy test environments and test doubles
class_teardown.
METHODS:
"! Reset test doubles
setup,
teardown,

1038 PUBLIC Test
"! Check instance with overall status 'Open'
validate_travel_status_open FOR TESTING,
"! Check instance with overall status 'Accepted'
validate_travel_status_acpt FOR TESTING,
"! Check instance with overall status 'Rejected'
validate_travel_status_rej FOR TESTING,
"! Check instance with invalid overall status
validate_travel_status_invalid FOR TESTING,
"! Check returned features for instance with overall status 'Open'
get_features_open FOR TESTING,
"! Check returned features for instance with overall status 'Accepted'
get_features_accepted FOR TESTING,
"! Check returned features for instance with overall status 'Rejected'
get_features_rejected FOR TESTING,
"! Check returned features for instance with invalid overall status
get_features_invalidstatus FOR TESTING,
"! Check returned features for instance with invalid key
get_features_invalidkey FOR TESTING,
"! Check instance with valid customer ID
validate_customer_valid FOR TESTING,
"! Check instance with invalid customer ID
validate_customer_invalid FOR TESTING,
"! Check instance with initial customer ID
validate_customer_initial FOR TESTING,
"! Check set_status_accepted action
set_status_accepted FOR TESTING.
ENDCLASS.
CLASS ltc_managed IMPLEMENTATION.
METHOD class_setup.
'/DMO/I_TRAVEL_M' ).
sql_test_environment =
cl_osql_test_environment=>create( i_dependency_list = VALUE #( ( '/DMO/
CUSTOMER' ) ) ).
ENDMETHOD.
METHOD setup.
ENDMETHOD.
METHOD teardown.
ROLLBACK ENTITIES.
ENDMETHOD.
ENDMETHOD.
METHOD validate_travel_status_open.
ENDMETHOD.
METHOD validate_travel_status_acpt.
ENDMETHOD.
METHOD validate_travel_status_rej.
ENDMETHOD.
METHOD validate_travel_status_invalid.
ENDMETHOD.
METHOD get_features_open.
ENDMETHOD.
METHOD get_features_accepted.
ENDMETHOD.
METHOD get_features_rejected.
ENDMETHOD.
METHOD get_features_invalidstatus.
ENDMETHOD.
METHOD get_features_invalidkey.
ENDMETHOD.
METHOD validate_customer_valid.
ENDMETHOD.
METHOD validate_customer_invalid.

Test PUBLIC 1039
ENDMETHOD.
METHOD validate_customer_initial.
ENDMETHOD.
ENDMETHOD.

ENDCLASS.
6.4.2.1.4 Implementing the Test Methods
This section shows how you can implement the test methods for methods of the managed flight reference
scenario.
Contents
Testing the Validation Method validate_travel_status [page 1040]
Testing the Feature Control Method get_features [page 1043]
Testing the Validation Method validate_customer [page 1048]
Testing the Action Method set_status_accepted [page 1051]
6.4.2.1.4.1 Testing the Validation Method

validate_travel_status
This topic shows a possible unit test for the validation method validate_travel_status.
The documentation in this topic only refers to the respective test methods. For information on the other parts
of the test class, see Refining the Test Class Structure [page 1035].
Test Design
The test contains four test methods, which reflect different cases that are covered by the tested method. The
first three methods refer to cases where a travel instance contains a valid overall status value - Accepted,
Rejected, and Open. The fourth test method covers the case where the travel instance contains an overall
status value different from the ones mentioned above. Such a value is considered as invalid by the validation.
Breaking down the test code into separate test methods facilitates the test maintenance. For instance, if the
implementation for invalid overall statuses changes, then only the respective test method needs to be adjusted,
all other test methods can be left as they are.

1040 PUBLIC Test
Test Method validate_travel_status_open
The test method first adds a travel instance with the value O (meaning "open") for the overall status to the test
double.
Since the method under test expects structures for the failed and reported responses as changing
parameters, two structures are declared using the respective types derived from the travel CDS entity and
its behavior definition.
Now, the method to be tested is called. The travel ID of the instance, which has been inserted into the
test double is provided as an exporting parameter, the declared failed and reported structures as changing
parameters.
Finally, the failed and reported structures returned by the tested method are evaluated using assert checks.
Since the value for the overall status field is accepted by the validation, the failed and reported structures are
expected to be empty.
 Expand the following code sample to view the source code of the method validate_travel_status_open.
 Sample Code
METHOD validate_travel_status_open.

" Fill in test data
DATA travel_mock_data TYPE STANDARD TABLE OF /DMO/TRAVEL_M.
travel_mock_data = VALUE #( ( travel_id = '52' overall_status = 'O' ) ).
cds_test_environment->insert_test_data( travel_mock_data ).
" Declare required structures
DATA failed TYPE RESPONSE FOR FAILED LATE /DMO/I_TRAVEL_M.
DATA reported TYPE RESPONSE FOR REPORTED LATE /DMO/I_TRAVEL_M.
" Call method to be tested
class_under_test->validate_travel_status(
EXPORTING
keys = CORRESPONDING #( travel_mock_data )
CHANGING
failed = failed
reported = reported
).
" Check for content in failed and reported
cl_abap_unit_assert=>assert_initial( msg = 'failed' act = failed ).
cl_abap_unit_assert=>assert_initial( msg = 'reported' act = reported ).

ENDMETHOD.
Test Method validate_travel_status_acpt
This test method follows the same approach as the test method for the overall status open, but this time using
the overall status accepted, which is valid as well.
 Expand the following code sample to view the source code of the method validate_travel_status_acpt.
 Sample Code
METHOD validate_travel_status_acpt.

" Fill in test data
travel_mock_data = VALUE #( ( travel_id = '52' overall_status = 'A' ) ).

Test PUBLIC 1041
EXPORTING
CHANGING
failed = failed
reported = reported
).

ENDMETHOD.
Test Method validate_travel_status_rej
the overall status rejected, which is valid as well.
 Expand the following code sample to view the source code of the method validate_travel_status_rej.
 Sample Code
METHOD validate_travel_status_rej.

" Fill in test data
travel_mock_data = VALUE #( ( travel_id = '52' overall_status = 'X' ) ).
EXPORTING
CHANGING
failed = failed
reported = reported
).

ENDMETHOD.
Test Method validate_travel_status_invalid
This test method follows the same approach as the test method for the expected values, but this time, the
overall status is set to a value different from the ones expected by the validation.
The method asserts that the failed and reported structures each contain exactly one row in their travel
tables. This prevents a dump, which would occur during the subsequent assert check when trying to access a

1042 PUBLIC Test
row in a table that is not available. The subsequent check asserts that the failed and reported travel ID equals
to the one provided for the CDS test double. For the reported structure, the method additionally asserts that
the correct element is flagged in the %element component and that it contains a valid message reference.
validate_travel_status_invalid.
 Sample Code
METHOD validate_travel_status_invalid.

" Fill in test data
travel_mock_data = VALUE #( ( travel_id = '52' overall_status = 'T' ) ).
EXPORTING
CHANGING
failed = failed
reported = reported
).
" Check number of returned instances in failed-travel
cl_abap_unit_assert=>assert_equals( act = lines( failed-travel ) exp = 1
msg = 'lines in failed-travel' ).
" Check travel id in failed-travel
cl_abap_unit_assert=>assert_equals( act = failed-travel[ 1 ]-travel_id
exp = '52' msg = 'travel id in failed-travel' ).
" Check number of returned instances in reported-travel
cl_abap_unit_assert=>assert_equals( act = lines( reported-travel ) exp =
1 msg = 'lines in reported-travel' ).
" Check travel id in reported-travel
cl_abap_unit_assert=>assert_equals( act = reported-travel[ 1 ]-travel_id
exp = '52' msg = 'travel id in reported-travel' ).
" Check marked field in reported-travel
cl_abap_unit_assert=>assert_equals( act = reported-travel[ 1 ]-%element-
overall_status exp = if_abap_behv=>mk-on msg = 'field overall status in
reported-travel' ).
" Check message reference in reported-travel
cl_abap_unit_assert=>assert_bound( act = reported-travel[ 1 ]-%msg msg =
'message reference in reported-travel' ).

ENDMETHOD.
6.4.2.1.4.2 Testing the Feature Control Method get_features
This topic shows a possible unit test for the feature control method get_features.
The documentation in this topic only refers to the respective test method. For information on the other parts of
the test class, see Refining the Test Class Structure [page 1035].

Test PUBLIC 1043
Test Design
The test contains five test methods, which reflect different cases that are covered by the tested method.
There is one test method for each overall status value, which is considered to be valid by the validation
validate_travel_status. The fourth test method covers the case for an invalid overall status value. The
fifth one covers the case where the test method processes a travel instance with an invalid travel ID.
dedicated handling of the overall status Open is implemented in the tested method, then only the respective
test method needs to be adjusted, all other test methods can be left as they are.
Test Method get_features_open
The test method first adds a travel instance with the value O (meaning "Open") to the test double.
Since the method under test expects structures for the result, failed and reported responses as
changing parameters, three structures are declared using the respective types derived from the travel CDS
entity and its behavior definition.
Now, the method to be tested is called. The travel ID of the instance, which has been inserted into the test
double as well as the features to be checked are provided as exporting parameters. The declared result, failed
and reported structures are provided as changing parameters.
The last part of the code checks whether the result has been populated with the expected feature control
information. To be able to compare the expected result to the actual result, the internal table expected
is declared by referencing the data type of the result table. The declared table is then populated with
the expected content - a travel instance containing the mocked travel ID and the expected operation
control constant enabled for the actions acceptTravel and rejectTravel as well as for the association
_Booking.
 Expand the following code sample to view the source code of the test method get_features_open.
 Sample Code
METHOD get_features_open.

" Fill in test data
travel_mock_data = VALUE #( ( travel_id = '43' overall_status = 'O' ) ).
" Declare required table and structures
DATA result TYPE TABLE FOR INSTANCE FEATURES RESULT /DMO/I_TRAVEL_M\
\travel.
DATA failed TYPE RESPONSE FOR FAILED EARLY /DMO/I_TRAVEL_M.
DATA reported TYPE RESPONSE FOR REPORTED EARLY /DMO/I_TRAVEL_M.
" Call the method to be tested
class_under_test->get_features(
EXPORTING
requested_features = VALUE #( %action-accepttravel =
if_abap_behv=>mk-on
%action-rejectTravel =
if_abap_behv=>mk-on
%assoc-_Booking =
if_abap_behv=>mk-on )
CHANGING

1044 PUBLIC Test
result = result
failed = failed
reported = reported
).
" Check result
DATA expected LIKE result.
expected = VALUE #( ( travel_id = '43'
%action-accepttravel = if_abap_behv=>fc-o-enabled
%action-rejectTravel = if_abap_behv=>fc-o-enabled
%assoc-_Booking = if_abap_behv=>fc-o-
enabled ) ).
cl_abap_unit_assert=>assert_equals( msg = 'result' exp = expected act =
result ).

ENDMETHOD.
Test Method get_features_accepted
the overall status accepted. In this case, the action accepttravel is expected to be disabled whereas the
action rejecttravel and the association _Booking are expected to be enabled.
 Expand the following code sample to view the source code of the test method get_features_accepted.
 Sample Code
METHOD get_features_accepted.

" Fill in test data
travel_mock_data = VALUE #( ( travel_id = '43' overall_status = 'A' ) ).
\travel.
EXPORTING
if_abap_behv=>mk-on
if_abap_behv=>mk-on
%assoc-_Booking =
CHANGING
result = result
failed = failed
reported = reported
).
" Check result
%action-accepttravel = if_abap_behv=>fc-o-disabled
enabled ) ).
result ).
ENDMETHOD.

Test PUBLIC 1045

Test Method get_features_rejected
This test method follows the same approach as the test methods for the previously covered overall statuses,
but this time using the overall status rejected. In this case, the action accepttravel is expected to be
enabled whereas the action rejecttravel and the association _Booking are expected to be disabled.
 Expand the following code sample to view the source code of the test method get_features_rejected.
 Sample Code
METHOD get_features_rejected.

" Fill in test data
travel_mock_data = VALUE #( ( travel_id = '43' overall_status = 'X' ) ).
\travel.
EXPORTING
if_abap_behv=>mk-on
if_abap_behv=>mk-on
%assoc-_Booking =
CHANGING
result = result
failed = failed
reported = reported
).
" Check result
%action-rejectTravel = if_abap_behv=>fc-o-disabled
disabled ) ).
result ).

ENDMETHOD.
Test Method get_features_invalidstatus
This test method follows the same approach as the test methods for the previously covered overall statuses,
but this time using an invalid overall status value. In this case, the actions and the association are expected to
be enabled.

1046 PUBLIC Test
 Expand the following code sample to view the source code of the test method
get_features_invalidstatus.
 Sample Code
METHOD get_features_invalidstatus.

" Fill in test data
travel_mock_data = VALUE #( ( travel_id = '43' overall_status = 'T' ) ).
\travel.
EXPORTING
if_abap_behv=>mk-on
if_abap_behv=>mk-on
%assoc-_Booking =
CHANGING
result = result
failed = failed
reported = reported
).
" Check result
enabled ) ).
result ).

ENDMETHOD.
Test Method get_features_invalidkey
This test method calls the tested method with a travel ID which is not available in the test double. Hence the
tested method is expected to return one failed travel instance with the travel ID provided during the method call
and the fail cause NOT_FOUND. The first assert check prevents a dump, which would occur during the following
assert checks when trying to access a row in a table that is not available.
 Expand the following code sample to view the source code of the test method get_features_invalidkey.
 Sample Code
METHOD get_features_invalidkey.

\travel.
" Call the method to be tested with invalid/not existing key

Test PUBLIC 1047
EXPORTING
keys = VALUE #( ( travel_id = '43' ) )
if_abap_behv=>mk-on
if_abap_behv=>mk-on
%assoc-_Booking =
CHANGING
result = result
failed = failed
reported = reported
).
cl_abap_unit_assert=>assert_equals( msg = 'lines in failed-travel' act =
lines( failed-travel ) exp = 1 ).
cl_abap_unit_assert=>assert_equals( msg = 'travel id in failed-travel'
act = failed-travel[ 1 ]-travel_id exp = '43' ).
" Check fail-cause in failed-travel
cl_abap_unit_assert=>assert_equals( msg = 'fail-cause in failed-travel'
act = failed-travel[ 1 ]-%fail-cause exp = if_abap_behv=>cause-not_found ).

ENDMETHOD.
6.4.2.1.4.3 Testing the Validation Method validate_customer
This topic shows a possible unit test for the validation method validate_customer.
Test Design
The test class contains three test methods, which reflect different cases that are covered by the tested method.
The first test method covers the case for a valid customer ID, the second one for invalid customer ID whereas
the third one covers the case, where no customer ID has been provided for the travel instance.
dedicated handling for travel instances with an initial customer ID is implemented, then only the respective test
method needs to be adjusted, all other test methods can be left as they are.
Test Method validate_customer_valid
The test method first adds a travel instance with the customer ID 1 to the CDS test double.
Next, the method adds a customer dataset with the customer ID 1 to the SQL test double.

1048 PUBLIC Test
Since the method under test expects structures for the failed and reported responses as changing
parameters, three structures are declared using the respective types derived from the travel CDS entity and its
Now, the method to be tested is called. The travel ID of the instance, which has been inserted into the
test double is provided as an exporting parameter, the declared failed and reported structures as changing
parameters.
Finally, the failed and reported structures returned by the tested method are evaluated using assert checks.
Since the customer ID of the validated travel instance is contained in the doubled customer table, the failed
and reported structures are expected to be empty.
 Expand the following code sample to view the source code of the test method validate_customer_valid.
 Sample Code
METHOD validate_customer_valid.

" Fill in test data for entity travel
travel_mock_data = VALUE #( ( travel_id = '43' customer_id = '1' ) ).
" Fill in test data for customer table
DATA customer_mock_data TYPE STANDARD TABLE OF /DMO/CUSTOMER.
customer_mock_data = VALUE #( ( customer_id = '1' ) ).
sql_test_environment->insert_test_data( customer_mock_data ).
class_under_test->validate_customer(
EXPORTING
CHANGING
failed = failed
reported = reported
).

ENDMETHOD.
Test Method validate_customer_invalid
This test method covers the case where the customer ID of the travel instance is not contained in the customer
table, hence the travel instance is considered as invalid. To realize this case, the method adds a travel instance
containing a customer ID to the CDS test double, but no test data to the SQL test double.
The method asserts that the failed and reported tables for the travel entity each contain exactly one row.
This prevents a dump, which would occur during the subsequent assert check when trying to access a row in
the table that is not available. The subsequent check asserts that the failed and reported travel ID equals to
the one provided for the CDS test double. For the reported structure, the method additionally asserts that the
correct element is flagged in the %element component and that it contains a reference to an existing message
object.
validate_customer_invalid.

Test PUBLIC 1049
 Sample Code
METHOD validate_customer_invalid.

travel_mock_data = VALUE #( ( travel_id = '43' customer_id = '1' ) ).
EXPORTING
CHANGING
failed = failed
reported = reported
).
cl_abap_unit_assert=>assert_equals( msg = 'lines in reported-travel' act
= lines( reported-travel ) exp = 1 ).
cl_abap_unit_assert=>assert_equals( msg = 'travel id in reported-travel'
act = reported-travel[ 1 ]-travel_id exp = '43' ).
cl_abap_unit_assert=>assert_equals( msg = 'field customer id in
reported-travel' act = reported-travel[ 1 ]-%element-customer_id exp =
if_abap_behv=>mk-on ).
cl_abap_unit_assert=>assert_bound( msg = 'message reference in reported-
travel' act = reported-travel[ 1 ]-%msg ).

ENDMETHOD.
Test Method validate_customer_initial
This test method covers the case where no customer ID is provided for the travel instance, hence the travel
instance is considered as invalid by the validation. To realize this case, the method adds a travel instance
containing no customer ID to the CDS test double. Test data for the SQL test double don´t need to be inserted.
The method asserts that the failed and reported tables for the travel entity each contain exactly one row.
This prevents a dump, which would occur during the subsequent assert check when trying to access a row in
the table that is not available. The subsequent check asserts that the failed and reported travel ID equals to
the one provided for the CDS test double. For the reported structure, the method additionally asserts that the
correct element is flagged in the %element component and that it contains a reference to an existing message
object.
validate_customer_initial.
 Sample Code
METHOD validate_customer_initial.

1050 PUBLIC Test

travel_mock_data = VALUE #( ( travel_id = '43' customer_id = '' ) ).
EXPORTING
CHANGING
failed = failed
reported = reported
).
cl_abap_unit_assert=>assert_equals( msg = 'lines in reported-travel' act
= lines( reported-travel ) exp = 1 ).
cl_abap_unit_assert=>assert_equals( msg = 'travel id in reported-travel'
act = reported-travel[ 1 ]-travel_id exp = '43' ).
cl_abap_unit_assert=>assert_equals( msg = 'field customer id in
reported-travel' act = reported-travel[ 1 ]-%element-customer_id exp =
if_abap_behv=>mk-on ).
cl_abap_unit_assert=>assert_bound( msg = 'message reference in reported-
travel' act = reported-travel[ 1 ]-%msg ).

ENDMETHOD.
6.4.2.1.4.4 Testing the Action Method set_status_accepted
This topic shows a possible unit test for the action method set_status_accepted.
Test Design
The method to be tested can be divided into two parts: The first part performs an EML modify operation on the
respective instances. The second part reads the modified instances and assigns the read result to the result
parameter of the action. In contrast to the methods discussed earlier, the method set_status_accepted
does not distinguish between different cases, e.g. existing overall statuses. Both parts of the method are run
during every method execution, hence the whole method can be covered by a single test method.

Test PUBLIC 1051
Test Method set_status_accepted
The test method first adds four travel instances with different overall statuses to the test double, two with a
valid status, one with an invalid status and one with an initial status.
Since the tested method expects an internal table for the result of the action as well as structures for the
mapped, failed and reported responses as changing parameters, four structures are declared using the
respective types derived from the travel CDS entity and its behavior definition.
Now, the method to be tested is called. The travel IDs of the instances, which have been inserted into the test
double are provided as exporting parameters, the declared table and structures as changing parameters.
To determine whether errors occurred during the modify operation that updates the overall status field, the
method asserts that the failed and reported structures are empty. Since the mapped structure is not
populated in the action implementation, an analogous assert check is specified.
The following part of the code checks whether the action result has been populated correctly. According to
the behavior definition, the action is expected to return one travel instance for each instance the action has
been executed on in the result. To be able to compare the expected action result to the actual action result,
two internal tables are required. The table exp is declared by referencing the data type of the result table and
is then populated with the expected content - four travel instances containing the mocked travel IDs and the
overall status A. The travel IDs need to be specified twice: Once for the field travel_id in order to identify
the source instance and once for the field %param-travel_id to identify the target instance. The table act
is also declared with the data type of the action result. To ensure that the act table only gets values for fields
that are also contained in the exp table, the assignment of the action result content is done by means of the
corresponding operator using mapping rules for the required fields. Finally, the method asserts that the
contents of the tables exp and act are equal.
The last part of the method checks whether the instances themselves have been updated correctly. To do so,
the method reads the travel IDs and the overall statuses of the mocked travel instances from the transactional
buffer. The result of the read operation is then assigned to the act table, thus overriding the content of the
action result. Finally, the method asserts that the contents of the tables exp and act are equal.
 Expand the following code sample to view the source code of the method set_status_accepted.
 Sample Code

" Fill in test data
travel_mock_data = VALUE #( ( travel_id = '42' overall_status = 'A' )
( travel_id = '43' overall_status = 'B' )
( travel_id = '44' overall_status = 'X' )
( travel_id = '45' overall_status = '' ) ).
DATA result TYPE TABLE FOR ACTION RESULT /DMO/I_TRAVEL_M\
\travel~accepttravel.
DATA mapped TYPE RESPONSE FOR MAPPED EARLY /DMO/I_TRAVEL_M.
class_under_test->set_status_accepted(
EXPORTING
CHANGING
result = result

1052 PUBLIC Test
mapped = mapped
failed = failed
reported = reported
).
" Check for content in mapped, failed and reported
cl_abap_unit_assert=>assert_initial( msg = 'mapped' act = mapped ).
" Check action result for fields of interest: travel_id, %param-
travel_id, %param-overall_status.
DATA exp LIKE result.
exp = VALUE #( ( travel_id = 42 %param-travel_id = '42' %param-
overall_status = 'A' )
( travel_id = 43 %param-travel_id = '43' %param-
overall_status = 'A' ) ).
DATA act LIKE result.
act = CORRESPONDING #( result MAPPING travel_id = travel_id
( %param = %param MAPPING travel_id =
travel_id
overall_status = overall_status
EXCEPT * )
EXCEPT * ).
cl_abap_unit_assert=>assert_equals( msg = 'action result' exp = exp act =
act ).
" Additionally check modified instances
READ ENTITY /DMO/I_TRAVEL_M
FIELDS ( travel_id overall_status ) WITH CORRESPONDING
#( travel_mock_data )
RESULT DATA(read_result).
act = VALUE #( FOR t IN read_result ( travel_id = t-travel_id
%param-travel_id = t-travel_id
%param-overall_status = t-
overall_status ) ).
cl_abap_unit_assert=>assert_equals( msg = 'read result' exp = exp act =
act ).

ENDMETHOD.
6.4.2.2 Developing a Test Class for the Draft Flight

Reference Scenario
The test class you develop in this chapter tests a method for the travel entity in the draft flight reference
scenario (package /DMO/FLIGHT_DRAFT).
Tested Method
The determination setTravelNumber sets a travel ID for newly created travel instances. The new travel ID is
calculated based on the highest travel ID available.

Test PUBLIC 1053
Contents
6.4.2.2.1 Creating the Test Class

2. In your ABAP project (or ABAP cloud project), select the behavior implementation /DMO/BP_TRAVEL_D.
3. In the tab Test Classes, click the button Create Test Class, type the word "test" and use code completion to
insert the test class template.
4. Name the class as ltc_draft and remove the declaration and implementation of the dummy method
first_test.
5. Activate your changes.
For further information on the creation of test classes, see (Tool Reference).
6. Add the created test class as a friend of the local handler class lhc_travel in order to enable the access
to its private methods. Proceed as described in Providing Access to Tested Methods [page 1035].
7. Refine the test class structure as described in Refining the Test Class Structure [page 1035]. In addition to
the instructions linked above, consider the following aspects for your test class:
• Test Methods
Declare the test methods setTravelNumber_idempotence, setTravelNumber_newTravelID and
settravelnumber_mixed and insert their signatures in the implementation part of the class using
the offered quick fix. For information on the test design, see Implementing the Test Methods [page
1055].
• Constants for UUIDs
Declare four constants for travel UUIDs to be used as test data.
• CDS Test Double Framework
You need the CDS Test Double Framework to make the EML calls of the tested method access the
doubled database dependency via the CDS view /DMO/I_TRAVEL_D. Provide this CDS view name as
the importing parameter for the create method of the class cl_cds_test_environment.
• Double Redirection for Open SQL calls
The tested method contains an Open SQL call that accesses the database table /dmo/a_travel_d
directly. To make this Open SQL call access the test double instead of the real database table, call
the method enable_double_redirection in the class setup after the creation of the CDS test
environment and the test double.
After following the steps described above, your test class looks like this and is ready for the implementation of
the test method:
 Expand the following code sample to view the source code of the test class ltc_draft.

1054 PUBLIC Test
 Sample Code
"! @testing BDEF:/DMO/I_TRAVEL_D

CLASS ltc_draft DEFINITION FINAL FOR TESTING
DURATION SHORT
PRIVATE SECTION.
cds_test_environment TYPE REF TO if_cds_test_environment.
CONSTANTS: uuid1 TYPE sysuuid_x16 VALUE '66657221A8E4645C17002DF03754A1',
uuid2 TYPE sysuuid_x16 VALUE '66657221A8E4645C17002DF03754A2',
uuid3 TYPE sysuuid_x16 VALUE '66657221A8E4645C17002DF03754A3',
uuid4 TYPE sysuuid_x16 VALUE '66657221A8E4645C17002DF03754A4'.
CLASS-METHODS:
"! Instantiate class under test and set up CDS Test Double Framework
class_setup,
"! Destroy test environment and test double
class_teardown.
METHODS:
"! Reset test double
setup,
teardown,
"! Check instance with already existing travel id
setTravelNumber_idempotence FOR TESTING,
"! Check instances with new travel ids
settravelnumber_newtravelids FOR TESTING,
"! Check instances with and without travel ids
settravelnumber_mixed FOR TESTING.
ENDCLASS.
CLASS ltc_draft IMPLEMENTATION.
METHOD class_setup.
'/DMO/I_TRAVEL_D' ).
cds_test_environment->enable_double_redirection( ).
ENDMETHOD.
METHOD setup.
ENDMETHOD.
METHOD teardown.
ROLLBACK ENTITIES.
ENDMETHOD.
ENDMETHOD.
METHOD setTravelNumber_idempotence.
ENDMETHOD.
METHOD settravelnumber_newtravelids.
ENDMETHOD.
METHOD settravelnumber_mixed.
ENDMETHOD.

ENDCLASS.
6.4.2.2.2 Implementing the Test Methods
This topic shows a possible unit test for the determination method setTravelNumber.
the test class, see Creating the Test Class [page 1054].

Test PUBLIC 1055
Test Design
The method to be tested can be divided into two parts: The first part reads the travel instances with the
imported keys and removes those travel instances from the read result table travels that already have a
travel ID. This ensures idempotence for the determination. If the table travels is empty after this step, the
method is terminated. If the table is not empty, the second part of the method calculates new travel IDs and
assigns them to the travel instances.
The first test method checks the idempotence by providing a travel instance with an already existing travel ID.
The second test method checks whether new travel IDs are calculated correctly for instances without travel ID.
The third test method checks a combination of the first two test cases.
Test Method settravelnumber_idempotence
The test method first adds a travel instance with a travel ID to the CDS test double.
Since the method under test expects the structure for the reported response as a changing parameter, the
structure reported is declared using the respective type derived from the travel CDS entity and its behavior
definition.
Now, the method to be tested is called. The travel UUID of the instance, which has been inserted into the test
double is provided as an exporting parameter, the declared reported structure as changing parameter.
The reported structure may contain messages in case of a failed update operation, so the method asserts
that the reported structure is initial.
The method now checks whether the instance still has its travel ID. To do so, it first reads the travel UUID
and the travel ID from the transactional buffer. Next, the method performs the assert checks: The first one
asserts that the read result table contains one row. This assert check ensures the correct number of read
instances and is used to prevent a dump, which would occur during the next assert check in case that the table
read_result is empty. The second check asserts that the travel ID has not changed.
 Expand the following code sample to view the source code of the method settravelnumber_idempotence.
 Sample Code
METHOD settravelnumber_idempotence.

" Fill in test data
DATA travel_mock_data TYPE STANDARD TABLE OF /DMO/A_Travel_D.
travel_mock_data = VALUE #( ( travel_uuid = uuid1 travel_id = '1' ) ).
" Declare required structure
DATA reported TYPE RESPONSE FOR REPORTED LATE /DMO/I_Travel_D.
class_under_test->setTravelNumber(
EXPORTING
keys = VALUE #( ( TravelUUID = travel_mock_data[ 1 ]-
travel_uuid ) )
CHANGING
reported = reported
).
" Check for content in reported
" Read instance data
READ ENTITY /DMO/I_Travel_D

1056 PUBLIC Test
FIELDS ( TravelID ) WITH VALUE #( ( TravelUUID = travel_mock_data[ 1 ]-
travel_uuid ) )
" Check number of returned instances in read_result
cl_abap_unit_assert=>assert_equals( msg = 'lines in read result' exp = 1
act = lines( read_result ) ).
" Check idempotence
cl_abap_unit_assert=>assert_equals( msg = 'idempotence' exp = '1' act =
read_result[ 1 ]-TravelID ).
ENDMETHOD.

Test Method settravelnumber_newtravelids
This test method covers the case where the determination is executed for travel instances that do not contain
travel IDs yet. Since the test double contains no other travel instances with a travel ID, the method asserts that
the calculated travel IDs for the instance are 1 and 2.
settravelnumber_newtravelids.
 Sample Code
METHOD settravelnumber_newtravelids.

" Fill in test data
travel_mock_data = VALUE #( ( travel_uuid = uuid1 )
( travel_uuid = uuid2 ) ).
EXPORTING
keys = VALUE #( FOR key IN travel_mock_data
( TravelUUID = key-travel_uuid ) )
CHANGING
reported = reported
).
" Read and sort instance data
FIELDS ( TravelID ) WITH VALUE #( FOR key IN travel_mock_data
SORT read_result BY travelid.
" Check number of returned instances in read_result
" Check new travel ids
cl_abap_unit_assert=>assert_equals( msg = 'new travel id' exp = '1' act =
cl_abap_unit_assert=>assert_equals( msg = 'new travel id' exp = '2' act =

ENDMETHOD.

Test PUBLIC 1057
Test Method settravelnumber_mixed
The last test method checks the combination of the previous test cases: two travel instances that need a travel
ID and one travel instance that already has a travel ID. To make sure, that the expected travel IDs belong to the
correct travel instances, the method additionally checks the travel UUIDs in the read result.
settravelnumber_newtravel_mixed.
 Sample Code
METHOD settravelnumber_newtravel_mixed.

" Fill in test data
travel_mock_data = VALUE #( ( travel_uuid = uuid1 )
( travel_uuid = uuid2 travel_id = '1' )
( travel_uuid = uuid3 ) ).
EXPORTING
keys = VALUE #( FOR key IN travel_mock_data
CHANGING
reported = reported
).
" Read and sort instance data
FIELDS ( TravelID ) WITH VALUE #( FOR key IN travel_mock_data
SORT read_result BY travelid.
" Check number of returned instances in read result
" Check travel uuid of first instance
cl_abap_unit_assert=>assert_equals( msg = 'travel uuid' act =
read_result[ 1 ]-TravelUUID exp = uuid2 ).
" Check idempotence
cl_abap_unit_assert=>assert_equals( msg = 'idempotence' act =
read_result[ 1 ]-TravelID exp = '1' ).
" Check travel uuid of second instance
" Check new travel id
cl_abap_unit_assert=>assert_equals( msg = 'new travel id' act =
" Check travel uuid of third instance
" Check new travel id
cl_abap_unit_assert=>assert_equals( msg = 'new travel id' act =
ENDMETHOD.


1058 PUBLIC Test
6.5 Integration Tests
The following section shows how the described concepts of integration tests apply in RAP. It contains step-by-
step guides explaining how to develop integration tests for a RAP business object.
Whereas unit tests operate within a business object to validate each functional unit of a particular RAP artefact,
integration tests work outside of business objects and validate consumption use cases via EML and OData,
where multiple fuctional units are involved. Reading or creating instances from outside for example make
use of the whole RAP application and involve dependent operations, such as determinations and validations.
Integration tests validate the consumption result and show whether the interaction between the involved
functional units works as expected.
6.5.1 EML Integration Tests
The test class you will develop in this chapter contains a selection of EML integration tests, that test the
interaction between the create operation and various dependencies. The business object that the test class
refers to is the managed flight reference scenario (package /DMO/FLIGHT_MANAGED). The name of the test
class containing the result of this section is called /DMO/TC_TRAVEL_M. You can use it as a reference to build
your own test class as decribed in the following chapter.

2. In your ABAP Project (or ABAP cloud project), create an ABAP class with the name /DMO/TC_TRAVEL_M as
described in .
3. In the tab Global Class, add the keywords FOR TESTING below the keywords CLASS /DMO/TC_TRAVEL_M
DEFINITION.
 Expand the following code sample to view the source code of the test class /DMO/TC_TRAVEL_M.
 Sample Code
CLASS /DMO/TC_TRAVEL_M DEFINITION

FOR TESTING
PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
PROTECTED SECTION.
PRIVATE SECTION.

Test PUBLIC 1059
ENDCLASS.
CLASS /DMO/TC_TRAVEL_M IMPLEMENTATION.

ENDCLASS.
properties, the test relation, variables and fixture methods that provide the desired test configuration. The
defined test class forms the basis for the test methods that you will implement in the upcoming chapters.
This topic covers the specific integration test class structure for the managed flight reference scenario. For
general information on the structure of RAP test classes, see Basic Test Class Structure [page 1021].
for the fixture and test methods.

Since the execution of the test methods is not expected to last longer than 5 seconds, you can use the
DURATION SHORT. Depending on the respective run mode and runtime monitor, exceeding the chosen
execution time can affect the results of your test.
be used. If the chosen risk level is higher than allowed in your system, your tests won't be executed.

FOR TESTING
DURATION SHORT

RISK LEVEL HARMLESS

You will develop the integration tests for the business object /DMO/I_TRAVEL_M. Specifying a test relation to
this business object enables you to run your integration tests directly via the context menu of the business
object´s behavior definition.
"! @testing BDEF:/DMO/I_TRAVEL_M

Declaring Class Components

Since you will be using the interfaces of the CDS Test Double Framework and of the SQL Test Double
Framework to mock your test data, you need to declare reference variables for these interfaces in the CLASS-
DATA section.
Additionally, declare variables for the begin and end date using the respective types from the flight reference
scenario. You will use these variables to prepare the flight data for the travel instances to be created.

1060 PUBLIC Test
Declare two tables for agency and customer data that will be used to store the respective mock data. Choose
the suiting type from the flight reference scenario.
Lastly, declare constants for the content IDs used for each entity level.
PRIVATE SECTION.

CLASS-DATA:
begin_date TYPE /dmo/begin_date,
end_date TYPE /dmo/end_date,
agency_mock_data TYPE STANDARD TABLE OF /dmo/agency,
customer_mock_data TYPE STANDARD TABLE OF /dmo/customer.
CONSTANTS cid TYPE abp_behv_cid VALUE 'ROOT1'.
CONSTANTS cid_node TYPE abp_behv_cid VALUE 'NODE1'.

CONSTANTS cid_subnode TYPE abp_behv_cid VALUE 'SUBNODE1'.

Declare the required test and fixture methods. Fixture methods are used to set up and tear down the test
environment which produces unique test behavior for every executed test.
CLASS-METHODS:

class_setup,
class_teardown.
METHODS:
setup,
teardown,
create_validation_negative FOR TESTING RAISING cx_static_check,
create_validation_positive FOR TESTING RAISING cx_static_check,
cba_fc_negative FOR TESTING RAISING cx_static_check,
cba_fc_positive FOR TESTING RAISING cx_static_check,
deep_create_determination FOR TESTING RAISING cx_static_check,
create_action_fc_negative FOR TESTING RAISING cx_static_check,
create_action_fc_positive FOR TESTING RAISING cx_static_check,

create_additional_save FOR TESTING RAISING cx_static_check.
This section covers the implementation of the fixture methods that specify the test configuration used by the
test methods.

Populate the tables agency_mock_data and customer_mock_data with sample content.
Your test methods will contain EML statements that access instance data via the CDS entities Travel, Booking
and Booking Supplement. In order to make these EML statements access the data of test double databases
instead of the real database tables, you now need to create test doubles using the CDS Test Double Framework.
Specify the CDS views /DMO/I_TRAVEL_M, /DMO/I_BOOKING_M and /DMO/I_BOOKSUPPL_M to ensure that
the underlying database tables are doubled.
The tested business object contains validations and an additional save implementation with OpenSQL
statements that access the database tables /DMO/AGENCY, /DMO/CUSTOMER and /DMO/LOG_TRAVEL. In order
to make these OpenSQL statements access the test doubles instead of the real databases, you also need to
create test doubles for these database tables using the SQL Test Double Framework.

Test PUBLIC 1061
Lastly, insert the agency and customer mock data into the test doubles. For the mocked database table /DMO/
LOG_TRAVEL, no test data are required.
METHOD class_setup.

agency_mock_data = VALUE #( ( agency_id = '987654' name = 'Miles
and More' ) ).
customer_mock_data = VALUE #( ( customer_id = '987653' last_name =
'Buchholm' ) ).
VALUE #(
( i_for_entity = '/DMO/
I_TRAVEL_M' )
I_BOOKING_M' )
( i_for_entity = '/DMO/I_BOOKSUPPL_M' )
)
).
sql_test_environment = cl_osql_test_environment=>create( i_dependency_list =
VALUE #(
( '/DMO/AGENCY' )
( '/DMO/CUSTOMER' )
( '/DMO/LOG_TRAVEL' )
) ) .
sql_test_environment->insert_test_data( agency_mock_data ).

ENDMETHOD.

To make sure that your test methods won't be influenced by data of other test methods, clear the contents of
the CDS test doubles before every test method execution.
METHOD setup.


ENDMETHOD.

To make sure that the transactional buffer is reset for the involved CDS entities after every test method
execution, use the EML statement ROLLBACK ENTITIES in the teardown method.
METHOD teardown.

ROLLBACK ENTITIES.

ENDMETHOD.



ENDMETHOD.

1062 PUBLIC Test
After following the steps described above, your test class should look like this and is ready for the
implementation of the test methods:
 Expand the following code sample to view the source code of the test class /DMO/TC_TRAVEL_M.
 Sample Code
"! @testing BDEF:/DMO/I_TRAVEL_M

CLASS /dmo/tc_travel_m DEFINITION
FOR TESTING
RISK LEVEL HARMLESS
DURATION SHORT
PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
PROTECTED SECTION.
PRIVATE SECTION.
CLASS-DATA:
begin_date TYPE /dmo/begin_date,
end_date TYPE /dmo/end_date,
agency_mock_data TYPE STANDARD TABLE OF /dmo/agency,
customer_mock_data TYPE STANDARD TABLE OF /dmo/customer.
CONSTANTS cid TYPE abp_behv_cid VALUE 'ROOT1'.
CONSTANTS cid_node TYPE abp_behv_cid VALUE 'NODE1'.
CONSTANTS cid_subnode TYPE abp_behv_cid VALUE 'SUBNODE1'.
CLASS-METHODS:
class_setup,
class_teardown.
METHODS:
setup,
teardown,
create_validation_negative FOR TESTING RAISING cx_static_check,
create_validation_positive FOR TESTING RAISING cx_static_check,
deep_create_determination FOR TESTING RAISING cx_static_check,
create_action_fc_negative FOR TESTING RAISING cx_static_check,
create_action_fc_positive FOR TESTING RAISING cx_static_check,
cba_fc_negative FOR TESTING RAISING cx_static_check,
cba_fc_positive FOR TESTING RAISING cx_static_check,
create_additional_save FOR TESTING RAISING cx_static_check.
ENDCLASS.
CLASS /dmo/tc_travel_m IMPLEMENTATION.
METHOD class_setup.
agency_mock_data = VALUE #( ( agency_id = '987654' name =
'Miles and More' ) ).
customer_mock_data = VALUE #( ( customer_id = '987653' last_name =
'Buchholm' ) ).
VALUE #(
I_TRAVEL_M' )
I_BOOKING_M' )
( i_for_entity = '/DMO/I_BOOKSUPPL_M' )
)
).
sql_test_environment =
cl_osql_test_environment=>create( i_dependency_list = VALUE #(
( '/DMO/AGENCY' )
( '/DMO/CUSTOMER' )
( '/DMO/LOG_TRAVEL' )

Test PUBLIC 1063
) ) .
sql_test_environment->insert_test_data( agency_mock_data ).
ENDMETHOD.
METHOD setup.
ENDMETHOD.
METHOD teardown.
ROLLBACK ENTITIES.
ENDMETHOD.
ENDMETHOD.
METHOD create_validation_negative.
ENDMETHOD.
METHOD create_validation_positive.
ENDMETHOD.
METHOD deep_create_determination.
ENDMETHOD.
METHOD create_action_fc_negative.
ENDMETHOD.
METHOD create_action_fc_positive.
ENDMETHOD.
METHOD cba_fc_negative.
ENDMETHOD.
METHOD cba_fc_positive.
ENDMETHOD.
METHOD create_additional_save.
ENDMETHOD.

ENDCLASS.
The test class you develop in this chapter tests the business object from the managed flight reference scenario
(package /DMO/FLIGHT_MANAGED).
Test Methods
The test method create_validation_negative triggers the creation of a travel instance with invalid flight
data and checks whether the validation validateDates returns the expected results. The test method
create_validation_positive tests the case where the specified flight data are correct.
The test method deep_create_determination triggers a create operation and two create-by-association
operations on the booking and supplement entity. The test method tests whether the triggered determination
calculateTotalPrice returns the correct total price.
The test method create_action_fc_negative creates a travel instance and then triggers the action
acceptTravel. Since the overall status of the created travel instance already is accepted, the execution of the
action is expected to be prevented by the instance feature control implementation. The test method checks the
result of the instance feature control implementation. The test method create_action_fc_positive tests
the case where the execution of the action is allowed.

1064 PUBLIC Test
The test method cba_fc_negative creates a travel instance and then triggers a create-by-association
operation to create a booking instance. Since the overall status of the created travel instance is rejected, the
execution of the create-by-association operation is prevented by the instance feature control implementation.
The test method cba_fc_positive tests the case where the execution of the create-by-association operation
is allowed.
The test method create_additional_save creates a travel instance and then tests whether the used
operation and the changed fields have been logged correctly by the triggered additional save implementation.
Contents
Test Scenario Create + Validation [page 1065]
Test Scenario Deep Create + Determination [page 1067]
Test Scenario Create + Feature Control + Action [page 1069]
Test Scenario Create + Feature Control + Create-by-Association [page 1071]
Test Scenario Create + Additional Save [page 1074]
6.5.1.3.1 Test Scenario Create + Validation
This integration test checks whether the validation validateDates prevents the persistance of a created
travel instance containing invalid flight data.
Test Method create_validation_negative
This test method tests the case where a consumer tries to create the travel instance with an invalid flight date.
Hence, in the given example, a begin date which lies in the past is assigned to the variable begin_date. The
variable end_date gets a valid flight date.
The method now performs an EML modify create call on the business object using the prepared variables.
Since the method only focuses on the validation validateDates, valid agency and cusomer data are
provided.
The create operation is expected to run correctly as the validation validateDates is only executed as part
of the save sequence, which will be triggered in a subsequent EML statement. Hence, the method asserts that
the mapped response from the EML create statement contains the expected content and travel ID and that the
failed and reported responses are empty.
Using the COMMIT ENTITIES statement, the test method now triggers the save sequence during which the
validation validateDates is executed.
Since the provided start date lies in the past, the method asserts that the failed response of the COMMIT
ENTITIES operation contains the travel ID of the failed instance.

Test PUBLIC 1065
According to the logic of the validation implementation, both the fields for the start and the end date are
marked in the reported response, if a wrong start date is provided. The test methods specifies respective
assert statements to check this. Additionally, the method asserts the correct message information is contained
in the reported response.
 Expand the following code sample to view the source code of the method create_validation_negative.
 Sample Code
METHOD create_validation_negative.

begin_date = cl_abap_context_info=>get_system_date( ) - 10.
end_date = cl_abap_context_info=>get_system_date( ) + 30.
" Create a Travel with invalid begin_date
ENTITY travel
CREATE FIELDS ( agency_id customer_id begin_date end_date description
booking_fee currency_code overall_status ) WITH
VALUE #( ( %cid = cid
agency_id = agency_mock_data[ 1 ]-agency_id
customer_id = customer_mock_data[ 1 ]-
customer_id
begin_date = begin_date
end_date = end_date
description = 'TestTravel 1'
booking_fee = '10.5'
currency_code = 'EUR'
overall_status = 'O' ) )
" Travel was created successfully
cl_abap_unit_assert=>assert_equals( exp = 1 act = lines( mapped_create-
travel ) ).
DATA(key_of_new_travel) = mapped_create-travel[ 1 ].
cl_abap_unit_assert=>assert_equals( exp = cid act = key_of_new_travel-
%cid ).
cl_abap_unit_assert=>assert_not_initial( act = key_of_new_travel-
travel_id ).
cl_abap_unit_assert=>assert_initial( act = failed_create ).
cl_abap_unit_assert=>assert_initial( act = reported_create ).
" Trigger Validations
COMMIT ENTITIES
RESPONSE OF /DMO/I_Travel_M
" Commit failed as begin_date is invalid ( must be after system date )
cl_abap_unit_assert=>assert_equals( act = lines( failed_commit-travel )
exp = 1 ).
cl_abap_unit_assert=>assert_not_initial( act = failed_commit-travel[ 1 ]-
travel_id ).
cl_abap_unit_assert=>assert_equals( act = lines( reported_commit-travel )
exp = 1 ).
cl_abap_unit_assert=>assert_not_initial( act = reported_commit-
travel[ 1 ]-travel_id ).
cl_abap_unit_assert=>assert_equals( act = reported_commit-travel[ 1 ]-
%element-begin_date exp = if_abap_behv=>mk-on ).
cl_abap_unit_assert=>assert_equals( act = reported_commit-travel[ 1 ]-
%element-end_date exp = if_abap_behv=>mk-on ).
cl_abap_unit_assert=>assert_equals( exp = 004 act = reported_commit-
travel[ 1 ]-%msg->if_t100_message~t100key-msgno ).
cl_abap_unit_assert=>assert_equals( exp = '/DMO/CM_FLIGHT' act =
reported_commit-travel[ 1 ]-%msg->if_t100_message~t100key-msgid ).

ENDMETHOD.

1066 PUBLIC Test
Test Method create_validation_positive
The second test method tests the case where a consumer creates a travel instance with valid flight data. In
contrast to the negative case shown above, the failed and reported responses of the COMMIT ENTITIES
statement are now expected to be empty.
 Expand the following code sample to view the source code of the method create_validation_positive.
 Sample Code
METHOD create_validation_positive.

begin_date = cl_abap_context_info=>get_system_date( ) + 10.
" Create a Travel with valid begin_date
ENTITY travel
CREATE FIELDS ( agency_id customer_id begin_date end_date description
booking_fee currency_code overall_status ) WITH
customer_id
end_date = end_date
travel ) ).
%cid ).
travel_id ).
cl_abap_unit_assert=>assert_initial( act = failed_create ).
cl_abap_unit_assert=>assert_initial( act = reported_create ).
" Trigger Validations
COMMIT ENTITIES
" Commit was successful
cl_abap_unit_assert=>assert_initial( act = failed_commit ).
cl_abap_unit_assert=>assert_initial( act = reported_commit ).

ENDMETHOD.
6.5.1.3.2 Test Scenario Deep Create + Determination
This integration test checks whether the determination calculateTotalPrice returns the correct total price
for a created travel instance containing a booking and a supplement instance.
First, the test method populates variables for the begin and end date.

Test PUBLIC 1067
Next, the method performs an EML modify call which creates a travel and corresponding booking and
supplement instances. To ensure that the create and create-by-association operations are performed correctly,
valid data are provided for the flight dates as well as for the agency and customer IDs.
Now the method performs an EML read call to get the calculation result of the determination
calculateTotalPrice. In this EML read statement, the travel instance is identified via the travel ID taken
from the mapped response of the preceding EML create statement.
The method finally asserts that the read calculation result equals the expected value.
 Expand the following code sample to view the source code of the method deep_create_determination.
 Sample Code
METHOD deep_create_determination.

" Create a Travel, Booking and Supplement
ENTITY travel
CREATE FIELDS ( agency_id customer_id begin_date end_date
description booking_fee currency_code overall_status ) WITH
customer_id
end_date = end_date
CREATE BY \_booking FIELDS ( booking_date customer_id carrier_id
connection_id flight_date flight_price currency_code
booking_status )
WITH VALUE #( ( %cid_ref = cid
%target = VALUE #( ( %cid = cid_node
booking_date = begin_date
customer_id =
customer_mock_data[ 1 ]-customer_id
carrier_id = '1'
connection_id = '1'
flight_date = begin_date
flight_price = '200'
booking_status = 'N' ) )
) )
ENTITY booking
CREATE BY \_booksupplement FIELDS ( supplement_id price
currency_code ) WITH
VALUE #( ( %cid_ref = cid_node
%target = VALUE #( ( %cid = cid_subnode
supplement_id = '100'
price = '1000'
currency_code = 'EUR' ) )
) )
MAPPED DATA(mapped_cba)
FAILED DATA(failed_cba)
REPORTED DATA(reported_cba).
" Read determination result
ENTITY travel
FIELDS ( total_price )
WITH VALUE #( ( travel_id = mapped_cba-travel[ 1 ]-%tky ) )
RESULT DATA(result)

1068 PUBLIC Test
" Determination calculation was successful
cl_abap_unit_assert=>assert_equals( exp = 1 act = lines( result ) ).
cl_abap_unit_assert=>assert_equals( act = result[ 1 ]-total_price exp =
'1210.50' ).

ENDMETHOD.
6.5.1.3.3 Test Scenario Create + Feature Control + Action
This integration test checks whether the instance feature control implementation get_features prevents the
execution of the action acceptTravel, which is performed on a created travel instance.
Test Method create_action_fc_negative
The method now performs an EML modify create call on the business object using the prepared date variables
as well as prepared agency and customer IDs. Since the method tests the case where the execution of the
action acceptTravel is prevented, the overall status A is provided.
The create operation is expected to run correctly. Hence, the method asserts that the mapped response from
the EML create statement contains the expected content and travel ID and that the failed and reported
responses are empty.
Now, the method triggers the action acceptTravel on the created travel instance. In this EML modify
statement, the travel instance is identified via the travel ID taken from the mapped response of the preceding
EML create statement.
According to the logic of the get_features method, the action acceptTravel is disabled for travel instances
with the overall status A. Hence, the method asserts the failed response of the action contains a travel ID and
that the action acceptTravel is marked respectively.
No messages are expected to be returned by the action, hence the method asserts that the reported
response is empty.
 Expand the following code sample to view the source code of the method create_action_fc_negative.
 Sample Code
METHOD create_action_fc_negative.

" Create a travel
ENTITY travel
customer_id = customer_mock_data[ 1 ]-customer_id

Test PUBLIC 1069
end_date = end_date
overall_status = 'A' ) )
travel ) ).
%cid ).
travel_id ).
cl_abap_unit_assert=>assert_initial( failed_create ).
cl_abap_unit_assert=>assert_initial( reported_create ).
" Execute action
ENTITY travel
EXECUTE acceptTravel FROM VALUE #( ( travel_id = mapped_create-
travel[ 1 ]-%tky ) )
FAILED DATA(failed_action)
REPORTED DATA(reported_action).
" Action failed as overall status is already accepted
cl_abap_unit_assert=>assert_equals( act = lines( failed_action-travel )
exp = 1 ).
cl_abap_unit_assert=>assert_not_initial( act = failed_action-travel[ 1 ]-
travel_id ).
cl_abap_unit_assert=>assert_equals( exp = if_abap_behv=>mk-on act =
failed_action-travel[ 1 ]-%action-accepttravel ).
cl_abap_unit_assert=>assert_initial( reported_action ).

ENDMETHOD.
Test Method create_action_fc_positive
The second test method tests the case where a consumer creates a travel instance with the overall status X. In
this case, the action can be executed successfully.
 Expand the following code sample to view the source code of the method create_action_fc_positive.
 Sample Code
METHOD create_action_fc_positive.

" Create a Travel
ENTITY travel
end_date = end_date
overall_status = 'X' ) )

1070 PUBLIC Test
travel ) ).
%cid ).
travel_id ).
" Execute action
ENTITY travel
EXECUTE acceptTravel FROM VALUE #( ( travel_id = mapped_create-
travel[ 1 ]-%tky ) )
FAILED DATA(failed_action)
REPORTED DATA(reported_action).
" Read action result
ENTITY travel
FIELDS ( overall_status )
WITH VALUE #( ( travel_id = mapped_create-travel[ 1 ]-%tky ) )
RESULT DATA(result)
" Read was executed successfully
cl_abap_unit_assert=>assert_initial( failed_read ).
" Action was executed successfully
cl_abap_unit_assert=>assert_equals( exp = 1 act = lines( result ) ).
cl_abap_unit_assert=>assert_equals( act = result[ 1 ]-overall_status exp
= 'A' ).
ENDMETHOD.

6.5.1.3.4 Test Scenario Create + Feature Control + Create-

by-Association
This integration test checks whether the instance feature control implementation get_features prevents the
execution of a create-by-association operation which is performed on a created instance.
Test Method cba_fc_negative
Next, the method performs an EML modify create call which creates a travel instance. To ensure that the create
operation is performed correctly, valid data are provided for the flight dates as well as for the agency and
customer IDs. Since the method tests the case where the execution of the subsequent create-by-association
operation is prevented, the overall status X is provided.
The create operation is expected to run correctly. Hence, the method asserts that the mapped response from
the EML create statement contains the expected content and travel ID and that the failed and reported
responses are empty.

Test PUBLIC 1071
Now, the method triggers a create-by-association operation.
According to the logic of the get_features method, the association _booking is disabled for travel
instances with the overall status X. Hence, the method asserts that the mapped response of the create-by-
association operation is empty. Additionally, the method asserts that the failed response contains a travel
ID and that the association _booking is marked respectively. No messages are expected to be returned, hence
the method asserts that the reported response is empty.
 Expand the following code sample to view the source code of the method cba_fc_negative.
 Sample Code
METHOD cba_fc_negative.

" Create a Travel with overall status "Cancelled"
ENTITY travel
end_date = end_date
overall_status = 'X' ) )
travel ) ).
%cid ).
travel_id ).
" Create a Booking for the created Travel
ENTITY travel
connection_id flight_date flight_price currency_code booking_status ) WITH
VALUE #( ( travel_id = mapped_create-travel[ 1 ]-%tky
customer_id =
carrier_id = '1'
connection_id = '1'
booking_status = 'B' ) )
) )
" Booking was not created as overall status of Travel is "Cancelled"
(should be "Open" or "Accepted")
cl_abap_unit_assert=>assert_initial( act = mapped_cba-booking ).

1072 PUBLIC Test
cl_abap_unit_assert=>assert_equals( act = lines( failed_cba-travel ) exp
= 1 ).
cl_abap_unit_assert=>assert_not_initial( act = failed_cba-travel[ 1 ]-
travel_id ).
cl_abap_unit_assert=>assert_equals( exp = if_abap_behv=>mk-on act =
failed_cba-travel[ 1 ]-%assoc-_Booking ).
cl_abap_unit_assert=>assert_initial( act = reported_cba ).

ENDMETHOD.
Test Method cba_fc_positive
The second test method tests the case where a consumer creates a travel instance with the overall status A. In
contrast to the negative case shown above, the mapped response of the create-by-association operation is now
expected to contain the respective IDs and the failed response is expected to be empty.
 Expand the following code sample to view the source code of the method cba_fc_positive.
 Sample Code
METHOD cba_fc_positive.

" Create a Travel with overall status "Accepted"
ENTITY travel
end_date = end_date
travel ) ).
%cid ).
travel_id ).
" Create a Booking for the created Travel
ENTITY travel
connection_id flight_date flight_price currency_code booking_status ) WITH
VALUE #( ( travel_id = mapped_create-travel[ 1 ]-%tky
customer_id =
carrier_id = '1'

Test PUBLIC 1073
connection_id = '1'
booking_status = 'B' ) )
) )
" Booking was created successfully
cl_abap_unit_assert=>assert_equals( exp = 1 act = lines( mapped_cba-
booking ) ).
DATA(key_of_new_booking) = mapped_cba-booking[ 1 ].
cl_abap_unit_assert=>assert_equals( exp = cid_node act =
key_of_new_booking-%cid ).
cl_abap_unit_assert=>assert_not_initial( act = key_of_new_booking-
booking_id ).
cl_abap_unit_assert=>assert_initial( act = failed_cba ).
cl_abap_unit_assert=>assert_initial( act = reported_cba ).

ENDMETHOD.
6.5.1.3.5 Test Scenario Create + Additional Save
This integration test checks whether the additional save implementation logs the used operation and the
changed fields correctly for a performed modify create operation.
Next, the method performs an EML modify create call which creates a travel instance. To ensure that the create
operation is performed correctly, valid data are provided for the flight dates as well as for the agency and
customer IDs.
The create operation is expected to be performed without errors. Hence, the method asserts that the mapped
response from the EML create statement contains the expected content and travel ID and that the failed and
reported responses are empty.
Using the COMMIT ENTITIES statement, the test method now triggers the save sequence during which the
additional save implementation is executed.
The save sequence is expected to be executed without errors. Hence, the method asserts that the failed and
reported responses of the commit operation are empty.
Finally, the method asserts that the table /dmo/log_travel, which is used by the additional save
implementation, contains the expected log entries for the used operation and the changed fields.
 Expand the following code sample to view the source code of the method create_additional_save.
 Sample Code
METHOD create_additional_save.

" Create a Travel
ENTITY travel

1074 PUBLIC Test
end_date = end_date
travel ) ).
%cid ).
travel_id ).
" Trigger additional save
COMMIT ENTITIES
cl_abap_unit_assert=>assert_initial( act = failed_commit ).
cl_abap_unit_assert=>assert_initial( act = reported_commit ).
" Ensure that a create operation has been executed
SELECT changed_field_name FROM /dmo/log_travel WHERE changing_operation =
'CREATE' ORDER BY changed_field_name INTO TABLE @DATA(log_fields).
cl_abap_unit_assert=>assert_equals( act = lines( log_fields ) exp = 2 ).
cl_abap_unit_assert=>assert_equals( act = log_fields[ 1 ] exp =
'booking_fee' ).
cl_abap_unit_assert=>assert_equals( act = log_fields[ 2 ] exp =
'overall_status' ).

ENDMETHOD.
6.5.2 OData Integration Tests
The test class you will develop in this chapter tests an OData service exposing a business object with a virtual
element implementation which is described in chapter Using Virtual Elements in CDS Projection Views [page
910]. Use the linked chapter to implement a virtual element in your existing business object. You can then use
the instructions of this chapter to develop OData integration tests for it.
 Note
The test class described in this chapter is not part of the /DMO/FLIGHT package.
The described test class uses the OData Client Proxy to execute OData calls on a BO which is exposed as an
OData service. Your test class will then evaluate the results of these OData calls in order to ensure, that the
OData service works as a whole and that it fulfills typical UI use cases.
For more information on the OData Client Proxy, see OData Client Proxy.

Test PUBLIC 1075
The test class uses the Local Client Proxy since its OData calls run in the same ABAP session as the OData
service itself. This enables the usage of the CDS Test Double Framework and other test double frameworks to
mock dependencies.
For information on OPA (One Page Acceptance) tests of SAP Fiori Elements for OData V4 Applications, see
https://developers.sap.com/group.fiori-elements-mockserver-opa.html .
In this step, you will create the test class, which serves as the basis for the test method to be developed.
ADT provides the option to generate an OData test class template containing the basic structure for different
calls executed by the OData Client Proxy. This option is available in the context menu of a selected entity set in
a service binding. In the following guide, however, you will start from scratch and develop the OData test class
individually.

2. In your ABAP Project (or ABAP cloud project), create an ABAP class with the name /DMO/
TC_BOOKING_ODATA as described in .
3. In the tab Global Class, add the keywords FOR TESTING below the keywords CLASS /DMO/
TC_BOOKING_ODATA DEFINITION.
 Expand the following code sample to view the source code of the test class /DMO/TC_BOOKING_ODATA.
 Sample Code
CLASS /DMO/TC_BOOKING_ODATA DEFINITION

FOR TESTING
PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
PROTECTED SECTION.
PRIVATE SECTION.
ENDCLASS.
CLASS /DMO/TC_BOOKING_ODATA IMPLEMENTATION.

ENDCLASS.
properties, the test relation, variables and fixture methods that provide the desired test configuration. The
defined test class forms the basis for the test methods that you will implement in the upcoming chapter.
This topic covers the specific integration test class structure for OData tests. For general information on the
structure of RAP test classes, see Basic Test Class Structure [page 1021].

1076 PUBLIC Test
for the used methods.

Since the execution of the test methods is not expected to last longer than 5 seconds, you can use the
DURATION SHORT. Depending on the respective run mode and runtime monitor, exceeding the chosen
execution time can affect the results of your test.
be used. If the chosen risk level is higher than allowed in your system, your tests won't be executed.

FOR TESTING
DURATION SHORT

RISK LEVEL HARMLESS

You will develop the integration tests for the service binding /DMO/UI_BOOKING_O2 which exposes the
business object as an OData V2 service. Specifying a test relation enables you to run your integration tests
directly via the context menu of the service binding.
"!@testing SRVB:/DMO/UI_BOOKING_O2

Declaring Class Components

Since you will be using the Local Client Proxy, filter APIs for the OData response and the CDS Test Double
Framework to mock the database dependencies, you need to declare reference variables for the respective
interfaces in the CLASS-DATA section. Furthermore, a structure type is required which will be later used to
identify an entity instance for an OData request.
The filter criteria for the OData response will be built using a ranges table. Hence you need to type a ranges
table with the field the filter will be applied for.
Lastly, declare a table and a variable used to prepare the booking instance data for the test double.
PRIVATE SECTION.

CLASS-DATA: go_client_proxy TYPE REF TO /iwbep/if_cp_client_proxy,
lo_filter_factory TYPE REF TO /iwbep/if_cp_filter_factory,
lo_filter_node TYPE REF TO /iwbep/if_cp_filter_node,
lt_range_currencycode TYPE RANGE OF /dmo/currency_code,
date TYPE /dmo/begin_date,
booking_mock_data TYPE TABLE OF /dmo/booking,
booksupplement_mock_data TYPE STANDARD TABLE OF /dmo/book_suppl.
TYPES:
BEGIN OF ts_key,
travelid TYPE /dmo/travel_id,
bookingid TYPE /dmo/booking_id,
END OF ts_key.

Declaring required Methods

Declare the required test and fixture methods. Fixture methods are used to set up and tear down
the test environment which produces unique test behavior for every executed test. The method

Test PUBLIC 1077
create_local_client_proxy is used to create an instance of the Local Client Proxy in the method
class_setup.
CLASS-METHODS :

class_teardown,
create_local_client_proxy
IMPORTING
service_key TYPE /iwbep/if_cp_client_proxy=>ty_s_service_key_v2
RETURNING
VALUE(client_proxy) TYPE REF TO /iwbep/if_cp_client_proxy .
METHODS:
setup,
teardown,
virtual_element FOR TESTING RAISING cx_static_check,

rba_with_filter FOR TESTING RAISING cx_static_check.
This section covers the implementation of the fixture methods that specify the test configuration used by
the test methods as well as the method create_local_client_proxy used to create the local client proxy
instance.

Call the mehod create_local_client_proxy with the service binding /DMO/UI_BOOKING_O2 and the
service ID 0001 as parameters and assign the result to the reference variable go_client_proxy declared
above.
In order to make the OData requests access the data of test doubles instead of the real database
tables, you now need to create test doubles using the CDS Test Double Framework. Specify
the CDS views /DMO/C_Booking_VE and /DMO/C_BOOKINGSUPPLEMENT_U and enable the parameter
i_select_base_dependencies for both of the views. Since the database tables to be doubled are not
reachable directly via the specified CDS views, this parameter is required to enable hierarchy testing. It ensures
that test doubles are created for all leaf nodes of the underlying structure.
Next, populate the variable date with a date that is in the future using the method get_system_date. This
method is also used in the tested virtual element implementation to calculate the difference between the flight
date and the respective current date.
Lastly, populate the tables booking_mock_data and booksupplement_mock_data with instance data to be
inserted into the test doubles. Use the content of the variable date for the field flight_date.
METHOD class_setup.

go_client_proxy = create_local_client_proxy( VALUE #(
service_id =
'/DMO/UI_BOOKING_O2'
service_version =
'0001' ) ).
CDS_TEST_ENVIRONMENT =
cl_cds_test_environment=>create_for_multiple_cds( i_for_entities = VALUE #(
( i_for_entity = '/DMO/C_Booking_VE' i_select_base_dependencies =
abap_true )
( i_for_entity = '/DMO/C_BOOKINGSUPPLEMENT_U' i_select_base_dependencies =
abap_true )
) ) .

1078 PUBLIC Test
date = cl_abap_context_info=>get_system_date( ) + 10.
booking_mock_data = VALUE #( ( travel_id = '1' booking_id ='1'
flight_date = date )
( travel_id = '1' booking_id ='2'
) .
booksupplement_mock_data = VALUE #( ( travel_id = '1' booking_id = '1'
booking_supplement_id = '1' currency_code = 'EUR' price = '5' )
( travel_id = '1' booking_id = '1'
booking_supplement_id = '2' currency_code = 'USD' price = '7' )
).

ENDMETHOD.

To make sure that your test methods won't be influenced by data of other test methods, clear the contents of
the CDS test doubles before every test method execution.
METHOD setup.


ENDMETHOD.

To make sure that the transactional buffer is reset for the involved CDS entities after every test method
execution, use the EML statement ROLLBACK ENTITIES in the teardown method.
METHOD teardown.

ROLLBACK ENTITIES.

ENDMETHOD.



ENDMETHOD.
Implementing the Method create_local_client_proxy

This method creates a V2 local client proxy instance used to execute OData V2 calls on the OData service.
Depending on the respective system, the method returns the cloud version or an on premise version of the
local client proxy instance.
Since both classes might not be available in a system, use dynamic calls to avoid syntax errors.

Test PUBLIC 1079
If none of the two called methods returns a local client proxy instance, stop the test execution with an assertion
error.
METHOD create_local_client_proxy.

TRY.
" the Cloud version
DATA(class1) = 'CL_WEB_ODATA_CLIENT_FACTORY'.
CALL METHOD (class1)=>create_v2_local_proxy
EXPORTING
is_service_key = service_key
RECEIVING
ro_client_proxy = client_proxy.
CATCH cx_root.
ENDTRY.
IF client_proxy IS NOT BOUND.
TRY.
" the onPrem version
DATA(class2) = '/IWBEP/CL_CP_CLIENT_PROXY_FACT'.
EXPORTING
RECEIVING
CATCH cx_root.
ENDTRY.
ENDIF.
cl_abap_unit_assert=>assert_bound( msg = 'cannot get client proxy factory or
service binding not active' act = client_proxy ).

ENDMETHOD.
After following the steps described above, your test class should look like this and is ready for the
implementation of the test methods:
 Expand the following code sample to view the source code of the test class /DMO/TC_BOOKING_ODATA.
 Sample Code
"!@testing SRVB:/DMO/UI_BOOKING_O2

FOR TESTING
DURATION SHORT
RISK LEVEL HARMLESS
PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.
PROTECTED SECTION.
PRIVATE SECTION.
CLASS-DATA: go_client_proxy TYPE REF TO /iwbep/
if_cp_client_proxy,
lo_filter_factory TYPE REF TO /iwbep/
if_cp_filter_factory,
lo_filter_node TYPE REF TO /iwbep/if_cp_filter_node,
lt_range_currencycode TYPE RANGE OF /dmo/currency_code,
date TYPE /dmo/begin_date,
booking_mock_data TYPE TABLE OF /dmo/booking,
booksupplement_mock_data TYPE STANDARD TABLE OF /dmo/
book_suppl.

1080 PUBLIC Test
TYPES:
BEGIN OF ts_key,
travelid TYPE /dmo/travel_id,
bookingid TYPE /dmo/booking_id,
END OF ts_key.
CLASS-METHODS :
class_teardown,
create_local_client_proxy
IMPORTING
service_key TYPE /iwbep/
if_cp_client_proxy=>ty_s_service_key_v2
RETURNING
VALUE(client_proxy) TYPE REF TO /iwbep/if_cp_client_proxy .
METHODS:
setup,
teardown,
virtual_element FOR TESTING RAISING cx_static_check,
rba_with_filter FOR TESTING RAISING cx_static_check.
ENDCLASS.
CLASS /DMO/TC_BOOKING_ODATA IMPLEMENTATION.
METHOD class_setup.
go_client_proxy = create_local_client_proxy( VALUE #(
service_id =
'/DMO/UI_BOOKING_O2'
service_version =
'0001' ) ).
CDS_TEST_ENVIRONMENT =
cl_cds_test_environment=>create_for_multiple_cds( i_for_entities = VALUE #(
( i_for_entity = '/DMO/C_Booking_VE' i_select_base_dependencies =
abap_true )
( i_for_entity = '/DMO/C_BOOKINGSUPPLEMENT_U'
i_select_base_dependencies = abap_true )
) ) .
date = cl_abap_context_info=>get_system_date( ) + 10.
booking_mock_data = VALUE #( ( travel_id = '1' booking_id ='1'
) .
booksupplement_mock_data = VALUE #( ( travel_id = '1' booking_id = '1'
).
ENDMETHOD.
METHOD setup.
ENDMETHOD.
METHOD teardown.
ROLLBACK ENTITIES.
ENDMETHOD.

Test PUBLIC 1081
ENDMETHOD.
METHOD create_local_client_proxy.
TRY.
" the Cloud version
DATA(class1) = 'CL_WEB_ODATA_CLIENT_FACTORY'.
EXPORTING
RECEIVING
CATCH cx_root.
ENDTRY.
IF client_proxy IS NOT BOUND.
TRY.
" the onPrem version
DATA(class2) = '/IWBEP/CL_CP_CLIENT_PROXY_FACT'.
EXPORTING
RECEIVING
CATCH cx_root.
ENDTRY.
ENDIF.
cl_abap_unit_assert=>assert_bound( msg = 'cannot get client proxy factory
or service binding not active' act = client_proxy ).
ENDMETHOD.
METHOD virtual_element.
ENDMETHOD.
METHOD rba_with_filter.
ENDMETHOD.

ENDCLASS.
The test methods you develop in this chapter execute OData read requests on the OData service.
Test Methods
The test method virtual_element reads instance data of the entity Booking and checks whether the
implementation of the virtual element DaysToFlight works as expected. Virtual elements cannot be tested
via EML and are therefore a significant test case for OData integration tests.
The test method rba_with_filter reads the data of all BookingSupplement instances of a given Booking
instance and uses filter conditions to check for specific datasets. The filter conditions used in this test cannot
be formulated with EML, as EML read calls can only identify entity instances by their keys.

1082 PUBLIC Test
6.5.2.3.1 Testing a Virtual Element
This test method performs an OData read request and checks whether the value for the virtual element
DaysToFlight is calculated as expected.
In the first step, the booking instance data is inserted into the test double.
Next, a read request for the entity Booking is created using the Local Client Proxy interface.
Now the OData read request is executed. A reference to its response is assigned to the reference variable
lo_response.
Before the business data are received from the response, the method checks whether there actually is a
response to the OData request.
Now, the booking instance data are read from the response and saved to an internal table typed with the
projection view /DMO/C_Booking_VE.
Finally, the method checks the number of returned instances and the virtual element value of one of the
booking instances.
 Expand the following code sample to view the source code of the method virtual_element.
 Sample Code
METHOD virtual_element.

cds_test_environment->insert_test_data( booking_mock_data ).
DATA(lo_request) = go_client_proxy-
>create_resource_for_entity_set( 'Booking' )->create_request_for_read( ).
DATA ls_response_data TYPE STANDARD TABLE OF /DMO/C_Booking_VE.
ls_response_data ).
cl_abap_unit_assert=>assert_equals( exp = '5' act =
lines( ls_response_data ) ).
ls_response_data[ 1 ]-DaysToFlight ).

ENDMETHOD.
6.5.2.3.2 Testing an OData Read Request with Filter

Options
This test method performs an OData read request from the entity Booking on the child entity Booking
Supplement using the compositional relationship between these entities. The read request is formulated with
filter conditions that limit the amount of resulting entries. The test checks whether the expected number of
result entries and whether the correct values are returned respectively.
In the first step, the test data is inserted into the booking and booking supplement test doubles.
Next, the entity set resource on which the request will be executed is prepared. At first, a resource object
for the entity Booking is created. Then, the booking instance whose child instances will be read is identified.
Finally, the association to be used for the read-by-association request is specified.

Test PUBLIC 1083
Now the read request for the prepared entity set resource is created.
In the next step, a filter condition is applied that makes the OData request read only the booking supplement
instances with the currency code EUR. In order to achieve this, the ranges table lt_range_currencycode
is specified. It is used by the method create_by_range to create a filter tree. The created filter tree is then
applied on the OData request.
To limit the number of resulting entries further, the request is set to only include the first two result entries.
The OData read request is executed. A reference to its response is assigned to the reference variable
lo_response. Before the business data are received from the response, the method checks whether there
actually is a response to the OData request.
Next, the booking supplement instance data are read from the response and saved to an internal table
typed with the projection view /DMO/C_BookingSupplement_U. This internal table is sorted by the
BookingSupplementID.
Finally, the method checks the number of returned instances as well as their price values.
 Expand the following code sample to view the source code of the method rba_with_filter.
 Sample Code
METHOD rba_with_filter.

cds_test_environment->insert_test_data( booking_mock_data ).
cds_test_environment->insert_test_data( booksupplement_mock_data ).
DATA(lo_booking) = go_client_proxy-
>create_resource_for_entity_set( 'Booking' )->navigate_with_key( VALUE
ts_key( travelid = '1' bookingid = '1' )
)->navigate_to_many( 'TO_BOOKSUPPLEMENT' ).
DATA(lo_request) = lo_booking->create_request_for_read( ).
lo_filter_factory = lo_request->create_filter_factory( ).
lt_range_currencycode = VALUE #( ( sign = 'I' option = 'EQ' low =
'EUR' ) ).
lo_filter_node = lo_filter_factory-
>create_by_range( iv_property_path = 'CURRENCYCODE'
it_range = lt_range_currencycode ).
lo_request->set_filter( lo_filter_node ).
lo_request->set_top( iv_top = 2 ).
DATA ls_response_data TYPE STANDARD TABLE OF /DMO/C_BookingSupplement_U.
ls_response_data ).
SORT ls_response_data BY BookingSupplementID.
lines( ls_response_data ) ).
ls_response_data[ 1 ]-Price ).
ls_response_data[ 2 ]-Price ).
ENDMETHOD.


1084 PUBLIC Test
7 Consume
This topic gives an overview about how you can consume RAP BOs in different consumption scenarios.
Generally, RAP BOs can be consumed in an OData service consumption scenario or with EML.
• OData Service Consumption: You can consume OData services that expose RAP business objects with a
UI client or with the OData Client Proxy. The OData Client Proxy can consume RAP business objects that
are exposed as Web APIs.
For more information about a draft business service consumption scenario or developing Web APIs, see
Exposing the Draft Business Object for a UI Business Service [page 681] and Develop Web APIs [page 765].
• Business Object Consumption: You can consume released RAP business objects with EML, for example
in a BADI implementation or in a behavior implementation of another business object. This is also possible
for custom BOs.
For an EML overview, see Entity Manipulation Language (EML) [page 235].
7.1 Business Object Interface Consumption
You can consume RAP business objects which have been released by SAP to profit from already implemented
functionality. For this purpose, RAP business objects provide RAP BO interfaces. This section describes how to
consume RAP BO interfaces. This is applicable both for released and custom RAP business objects.
About Released RAP BO Interfaces
A RAP BO interface is a stable API intended to provide access to a RAP BO. To achieve lifecycle stability,
RAP BO interfaces are classified with a release contract that enables the interface consumption from a
different software component and only allows compatible changes to the interface that don't result in errors for
consumers. The underlying RAP BO can't be accessed or consumed directly, but must always be accessed via
the released interface of the RAP BO. For more information about the respective release contract, see .
For more information about RAP BO interfaces, see Business Object Interface [page 194].
Consuming RAP BO interfaces
EML Consumption
RAP BO interfaces can be consumed with EML.

Consume PUBLIC 1085
To consume a RAP BO interface with EML, specify the name of the interface in the EML statement instead of
the base/projection layer:
MODIFY ENTITIES OF My_Interface

ENTITY BO_Entity
CREATE …

For more information about EML consumption, see Entity Manipulation Language (EML) [page 235].
Business Service Consumption

You can consume a custom or released RAP BO interface with an OData service. You can create a projection
layer on top of the BO interface and create your own business service for OData or Web API consumption.
For more information about UI Service and Web API consumption, see OData Service Consumption [page
1086].
7.2 OData Service Consumption
An OData service can be exposed as a UI service, that can be consumed by an SAP Fiori UI, or as a Web API
that can be consumed by any OData client.
• https://help.sap.com/viewer/468a97775123488ab3345a0c48cadd8f/LATEST/en-US/
03265b0408e2432c9571d6b3feb6b1fd.html [https://help.sap.com/viewer/
468a97775123488ab3345a0c48cadd8f/LATEST/en-US/03265b0408e2432c9571d6b3feb6b1fd.html]

1086 PUBLIC Consume
• Creating an OData Service [page 323]
• Develop Web APIs [page 765]
UI service
An OData service that is exposed as a UI service is consumable by an SAP Fiori Elements app. Every front-
end configuration, which is manifested in the back-end development object (for example, UI annotations), is
exposed within the metadata of the service. That means, a Fiori UI reads the information in the metadata and
creates the matching UI for the service. These UI settings can be enhanced and overwritten in the SAP Web
IDE.
A UI service can be previewed with the Fiori Elements preview in the service binding tool. The preview mocks a
real UI app and has the same look and feel as a Fiori Elements app. It is therefore a powerful tool to test the UI
of your OData service already in the backend. However, it does not substitute the development in the SAP Web
IDE.
For further information about the Fiori Elements preview in the service binding, see Previewing the Resulting UI
Service [page 330].
For more information about SAPUI5 to get more information about creating a deployable SAP Fiori app, see
Developing Apps with SAP Fiori Elements.
Web API
An OData service that is exposed as a Web API comes without any UI specific information in the metadata. It is
the public interface for any OData client to access the OData service. For example, you can consume a Web API
from another OData service.
Web APIs require a life cycle management. It must be possible to define the release, the version, and the
possible deprecation of the Web API. This functionality is enabled in the service binding tool.
For more information about Web APIs, see Develop Web APIs [page 765].
Differences at a glance
The following table outlines the functional differences between the respective versions of a UI service and a
web API:
UI services and Web APIs

Feature WebAPI V2 WebAPI V4 UI Service V2 UI Service V4
UI annotations (includ- No UI specific informa- No UI specific informa- UI specific information UI specific information
ing value help) tion contained in meta- tion contained in meta- contained in metadata contained in metadata
data data

Consume PUBLIC 1087
Feature WebAPI V2 WebAPI V4 UI Service V2 UI Service V4
Feature control Not exposed as part of service Exposed as part of service
Denormalized texts Not exposed as part of service Exposed as part of service
Release for contracts Possible in ADT tab API state Not possible
Fiori Elements preview Not available Available in service binding
Code lists for units of Not available Contained in service Contained in entity Contained in service
measure / currencies group sets group
SAP__Currency
and
SAP__UnitOfMeas
ure
ISO conversion of cur- Available Not available
rency code format

1088 PUBLIC Consume
8 Reuse
Technical reuse services allow you to significantly increase developer efficiency by using released APIs to
integrating standard processes or standard functionality in your application.
About Technical Reuse Services
Reuse services offer standard functionality and allow you to significantly increase the developer efficiency.
These services aren't application or business object-specific, but offer general capabilities that are required by
multiple applications and business areas.
In some cases it is even required to have a single service being used across all applications and business
objects being part of a business process. For RAP, a variety of reuse services is available and ready-to-run,
ranging from applications jobs of logging, forms and emails up to change documents or the workflow. For
details about the offered reuse services, see Released Components and Objects.
Using Technical Reuse Services in RAP
How reuse services can be integrated in RAP, depends on the respective reuse service:
• Using a RAP BO Interface: A BO interface can be called to trigger the respective reuse, like for example the
workflow service.
• Using class-based APIs: By calling the class-based APIs, you can use the respective reuse service like for
example number ranges or factory calendar.
Integrating BTP Workflow Services [page 1089]

The workflow capability offers modern process automation capabilities.
8.1 Integrating BTP Workflow Services

The workflow capability offers modern process automation capabilities.
About BTP Workflow Services
 Note
Workflow services always require an integration scenario. For details, see Implementing a Workflow [page
1094].

Reuse PUBLIC 1089
With workflow services, you design workflows based on Business Process Model and Notation
(BPMN). The workflow definition defines the individual consecutive process steps that are processed
when a workflow instance is called by a RAP instance.
For more information about the workflow service, see Workflow Introduction and Workflow Definition versus
Workflow Instance.
Workflows and Numbering
When a workflow instance at runtime must be triggered depends on the numbering defined for a RAP BO. The
actions required to trigger a workflow instance are defined as save actions and can thus only be called during
the early or late save phase of a RAP BO:
• Early Numbering: It's recommended to call trigger the workflow instance in a determination on save
with the required methods.
• Late Numbering: It's recommended to trigger the workflow in a determination on save. If required,
you can set the payload with the setPayload method even later in the adjust_numbers method.
To see at which point in time the respective implementation is called at runtime, see Save Sequence Runtime
[page 225] and for details about the specifics for implementing workflows in a late numbering scenario, see
API for the Workflow Capability.
For more information about numbering, see Numbering [page 23]
Mass-Enablement
To ensure that triggering the workflow is mass-enabled, the key CpWfHandle of interface I_CPWF_INST
needs to be specified externally. A UUID with 32 characters is expected as input parameter. If the action
registerWorkflow is called repeteadly with the same CpWfHandle and an identical payload, this results in a
short dump.
It's recommended to use the class cl_system_uuid=>create_uuid_c32_static( ) to create the

required UUIDs.
Callback Class
The service callback class implements the process that is executed after the workflow has been finished.
This class must implement the interface if_swf_cpwf_callback. This class is required when a workflow is
registered.

1090 PUBLIC Reuse
Workflow Example
In this simplified example, the workflow consists four consectutive process steps and implements a simple
approval workflow for travels based on a predefined condition:
The Workflow ID is required to trigger a workflow instance from your implementation in the RAP behavior
pool.
The following code snippet shows how the user input from the second step contained in the variable
lastUserTask1.decision is set in the third step:
 Sample Code

var lastUserTask1 = $.usertask1.last;
$.context.Wfdecision = "undefined";
if (lastUserTask1.decision === "myaccept") {
$context.Wfdecision = "WF-accepted";
}
if (lastUserTask1.decision === "myreject") {
$context.Wfdecision = "WF-rejected";
}

Process Overview
BO Interface I_CPWF_INST
In the RAP behavior pool, workflows can be integrated via the released BO interface I_CPWF_INST. The intial
call consists of the following steps:
• registerWorkflow: Checks the required configuration set up and if successful registers a new workflow
instance.
• setPayload: provides the input data for the workflow instance in json format.
Both process steps must be called either in the early save phase or late save phase of your RAP BO runtime
depending on the numbering pattern defined for the respective RAP BO.
For more information about the BO Interface I_CPWF_INST, see API for the Workflow Capability or see the
respective KTD documentation in ADT.

Reuse PUBLIC 1091
Implemented Example Process
This example uses a simplified workflow to show how to trigger a workflow and how to receive the service
callback. The BO is implemented with early numbering, so both determinations are implemented as
determination on save as part of the FINALIZE in the save sequence. The workflow is triggered by
the action TriggerDecisionWorkflow which sets the fields required for the workflow. This triggers the
determination on save and starts the actual workflow.
1. Creating the Data Model for Workflow Example [page 1093]

This section outlines the data model used for the workflow example.
2. Implementing a Workflow [page 1094]
When a workflow is triggered in a RAP BO, the predefined decision workflow is triggered via the
Workflow Service. The example is triggered with an action and executed with a determination
on save.
3. Implementing the Service Callback Class [page 1100]
The service callback class implements the process that is executed after the decision workflow has
been finished.

1092 PUBLIC Reuse
8.1.1 Creating the Data Model for Workflow Example
This section outlines the data model used for the workflow example.
Root View:/DMO/R_Travel_W:
The root view uses numbering via a UUID in combination with a semantic key. The field WFRecipient contains
the email address of the employee receiving the email once the decision workflow has been triggered. For more
information about the contained standard fields, see ABAP Flight Reference Scenario [page 309].
 Sample Code

@EndUserText.label: 'Travel View Entity for Workflow'
define root view entity /DMO/R_Travel_W
as select from /DMO/A_TRAVEL_W
...
{
...
//Field triggers the Workflow
@Semantics.eMail.type: 'HOME'
workflow_recipient as WFRecipient,
...

}
Structures ty_wf_travel and ty_wf_json
Both structures are used in the implementation in the determination on save that triggers the workflow.
For more information, see Implementing a Workflow [page 1094].
Structure ty_wf_travel
This structure contains fields of the travel instance and fields relevant for the workflow response. The field
wfrecipient contains the email address and the field wfdecision records the workflow decision.

...
BEGIN OF ty_wf_travel,
TravelUUID TYPE sysuuid_x16,
TravelID TYPE /dmo/tra0vl_d_w,
AgencyID TYPE /dmo/age0ncy_d_w,
CustomerID TYPE /dmo/cstmr_d_w,
BeginDate TYPE /dmo/bgn_dt_w,
TotalPrice TYPE /dmo/ttl_prc_w,
CurrencyCode TYPE /dmo/crrncy_cd_w,
EndDate TYPE /dmo/end_dt_w,
Description TYPE /dmo/dscrptn_w,
OverallStatus TYPE /dmo/ovrll_stts_w,
wfrecipient TYPE c LENGTH 128,
wfdecision TYPE c LENGTH 128,
END OF ty_wf_travel,
...


Reuse PUBLIC 1093
Structure ty_wf_json
This structure consists of the unique UUID required for each travel instance and the travel %data in json fomat.
This structure is used as payload for triggering the workflow.

...
BEGIN OF ty_wf_json,
wfhandle TYPE sysuuid_x16,
json TYPE string,
END OF ty_wf_json.
...

Parent topic: Integrating BTP Workflow Services [page 1089]
Next: Implementing a Workflow [page 1094]
8.1.2 Implementing a Workflow
When a workflow is triggered in a RAP BO, the predefined decision workflow is triggered via the Workflow
Service. The example is triggered with an action and executed with a determination on save.
Prerequisites
• You have modeled a workflow as described in Modelling a Workflow

• You have created an integration scenario for the workflow service as described in Workflow Integration
Defining the Behavior Definition for /DMO/R_Travel_W
1. Create a behavior definition based on /DMO/R_Travel_W as described in .

The behavior definition requires the following behavior elements to trigger a workflow:
• field ( readonly ) WFRecipient: : Changes to this field trigger the determination on save. This
field is defined as readonly, because the value is filled in via the action triggerDecisionWorkflow.
• action triggerDecisionWorkflow: Sets the field WFRecipient and triggers the determination on save.
• determination triggerWorkflow: Executes the workflow registration and defines the payload for the
workflow service.
The numbering scenario is the decisive factor to decide how the workflow needs to be integrated in your
RAP BO. For more information, see Worflows and Numbering [page 1090]. In this case, implementing it in a
determination on save is the only option.
 Sample Code

managed implementation in class /dmo/bp_trvl_w unique;

1094 PUBLIC Reuse
strict(2);
with draft;
define behavior for /DMO/R_TRVL_W alias Travel

implementation in class /dmo/bp_trvl_w unique
persistent table /dmo/a_travel_w
draft table /dmo/d_travel_w
...
{
...
field ( readonly ) WFRecipient;
...
action ( features : instance ) triggerDecisionWorkflow parameter /dmo/
a_trvl_triggerwf_w result [1] $self;
determination triggerWorkflow on save { field WFRecipient; }

...
mapping for /dmo/a_travel_w corresponding

{...
}

}
Implementing Action triggerDecisionWorkflow
1. Implement the triggerDecisionWorkflow action
This action updates the workflow relevant fields in the EML MODIFY statement. The update to WFRecipient
triggers the workflow registration in the determination on save. The result returns all travel instances with all
fields.
 Sample Code
METHOD TriggerDecisionWorkflow.

MODIFY ENTITIES OF /dmo/r_trvl_d_w IN LOCAL MODE
ENTITY Travel
UPDATE FIELDS ( WFRecipient WFDecision WFTimestamp WFHandle )
WFRecipient = key-%param-WFRecipient
WFDecision = ''
WFTimestamp = 0
WFHandle = '' ) ).
READ ENTITIES OF /dmo/r_trvl_d_w IN LOCAL MODE

ENTITY Travel
ALL FIELDS WITH


ENDMETHOD.

Reuse PUBLIC 1095
Implementing Determination triggerWorkflow
When the determination is triggered, it registers the workflow and defines its payload. The following steps the
determination is implemented.
Here you can find the complete code snippet:
 Sample Code

METHOD triggerWorkflow.

ENTITY Travel
ALL FIELDS WITH VALUE #( FOR key IN keys ( %tky = key-%tky ) )
" Skip all Travels that have no recipient or for which a workflow has
already been triggered
DELETE travels WHERE WFRecipient IS INITIAL OR WFHandle IS NOT INITIAL.
CHECK travels[] IS NOT INITIAL.
" We need to specify our own WFHandle, as otherwise the mass-registration

via the RAP facade would not work
TRY.
<travel>-WFHandle = cl_system_uuid=>create_uuid_c32_static( ).
ASSERT 1 = 2.
ENDTRY.
ENDLOOP.
MODIFY ENTITIES OF i_cpwf_inst

ENTITY CPWFInstance
EXECUTE registerWorkflow
FROM VALUE #( FOR travel IN travels
( %key-CpWfHandle = travel-WFHandle
%param-RetentionTime = '2'
%param-CpWfDefId = 'z123.myworkflow'
%param-CallbackClass = '/DMO/CL_WF_CALLBACK'
%param-Consumer = 'DEFAULT' ) )
MAPPED DATA(mapped)
" Check that n Travels have resulted in n workflow instances (both are not
yet linked)
ASSERT lines( travels ) = lines( mapped-cpwfinstance ).
ASSERT failed-cpwfinstance IS INITIAL.
" Persist the Workflow Handle in the Travel - to indicate that a workitem
has been triggered
ENTITY Travel
UPDATE FIELDS ( WFHandle )
WFHandle = travel-WFHandle ) ).
" Set the workflow context for the new workflow instances
DATA: wf_travel TYPE /dmo/bp_trvl_d_w=>ty_wf_travel,
wf_json TYPE STANDARD TABLE OF /dmo/bp_trvl_d_w=>ty_wf_json.

1096 PUBLIC Reuse
TRY.
DATA(cpwf_api) = cl_swf_cpwf_api_factory_a4c=>get_api_instance( ).
DATA(cpwf_json) = cpwf_api->get_json_converter( ).
CATCH cx_swf_cpwf_api INTO DATA(lx_cpwf).
ASSERT 1 = 2.
ENDTRY.
LOOP AT travels ASSIGNING <travel>.
wf_travel = CORRESPONDING #( <travel>-%data ).
cpwf_json->serialize(
EXPORTING
data = wf_travel
RECEIVING
result = DATA(json) ).
APPEND VALUE #( wfhandle = <travel>-WFHandle

json = json ) TO wf_json.
ENDLOOP.

ENTITY CPWFInstance
EXECUTE setPayload
FROM VALUE #( FOR wf_item IN wf_json
( %key-CpWfHandle = wf_item-wfhandle
%param-context = wf_item-json
) )
MAPPED DATA(mapped2)
FAILED DATA(failed2).
ASSERT lines( travels ) = lines( mapped2-cpwfinstance ).

ASSERT failed2-cpwfinstance IS INITIAL.
ENDMETHOD.

1. Read Required Travels

The READ statement reads all fields for a travel instance. Then all instances without recipient in the
WFRecipient field are deleted from travels, as well as all instances for which the workflow had already
been triggered previously.

ENTITY Travel
ALL FIELDS WITH VALUE #( FOR key IN keys ( %tky = key-%tky ) )
" Skip all travels that have no recipient or for which a workflow has already
been triggered
DELETE travels WHERE WFRecipient IS INITIAL OR WFHandle IS NOT INITIAL.
CHECK travels[] IS NOT INITIAL.
...

2. Define WFHandle for Primary Key in BO Interface

The class cl_system_uuid with method create_uuid_c32_static( ) is called to define a unique UUID
for WFHandle for each travel instance as primary key for interface i_cpwf_inst.

...
" Specify WFHandle, as otherwise the mass-registration via the RAP BO
interface would not work
TRY.
<travel>-WFHandle = cl_system_uuid=>create_uuid_c32_static( ).

Reuse PUBLIC 1097
ASSERT 1 = 2.
ENDTRY.
ENDLOOP.
...

3. Register Workflow
The action registerWorkflow of BO interface CPWFInstance is executed to register the workflow with the
following input parameters:
• %key-CpWfHandle: UUID to uniquely identify each travel instance. UUID was generated in the previous
step.
• %param-CpWfDefId: Workflow ID of the designed workflow.
• %param-CallbackClass: Specifies the callback class which implements interface
if_swf_cpwf_callback.
Other input parameters are available depending on your use case. For more information, see API for the
Workflow Capability or refer to the respective KTD documentation.
The asserts check that all travel instances have been transfered to the workflow instances during the
operation.

...
ENTITY CPWFInstance
EXECUTE registerWorkflow
FROM VALUE #( FOR travel IN travels
( %key-CpWfHandle = travel-WFHandle
%param-RetentionTime = '2'
%param-CpWfDefId = 'myworkflow'
%param-CallbackClass = '/DMO/CL_WF_CALLBACK'
%param-Consumer = 'DEFAULT' ) )
MAPPED DATA(mapped)
" Check that n Travels have resulted in n workflow instances (both are not yet
linked)
ASSERT lines( travels ) = lines( mapped-cpwfinstance ).
ASSERT failed-cpwfinstance IS INITIAL.
...

4. Call Helper class for JSON Conversion

Create two variables based on the structures ty_wf_travel and ty_wf_json. For details
about the structures, see Structures ty_wf_travel and ty_wf_json [page 1093]. The class
cl_swf_cpwf_api_factory_a4c is is used as a helper class to get access to the json converter required
in the next step.
 Code Syntax

...
" Set the workflow context for the new workflow instances
wf_json TYPE STANDARD TABLE OF /dmo/bp_trvl_d_w=>ty_wf_json.
TRY.
DATA(cpwf_json) = cpwf_api->get_json_converter( ).
ASSERT 1 = 2.

1098 PUBLIC Reuse
ENDTRY.
...

5. Update Status for Started Workflow

The field WFHandle is updated to indicate that the workflow has been triggered for a specific travel instance.
 Code Syntax

...
" Persist the Workflow Handle in the Travel - to indicate that a workitem
has been triggered
ENTITY Travel
UPDATE FIELDS ( WFHandle )
WFHandle = travel-WFHandle ) ).
...

6. Set Payload
wf_travel contains a subset of the travel structure. The structure is converted to json format. Together
with the UUID WFHandle it's appended to the wf_json table of type TYPE STANDARD TABLE OF /dmo/
bp_trvl_d_w=>ty_wf_json.
Then the setPayload action transmits the payload in JSON format with the corresponding UUID.

...
LOOP AT travels ASSIGNING <travel>.
wf_travel = CORRESPONDING #( <travel>-%data ).
cpwf_json->serialize(
EXPORTING
data = wf_travel
RECEIVING
result = DATA(json) ).
APPEND VALUE #( wfhandle = <travel>-WFHandle

json = json ) TO wf_json.
ENDLOOP.

ENTITY CPWFInstance
EXECUTE setPayload
FROM VALUE #( FOR wf_item IN wf_json
( %key-CpWfHandle = wf_item-wfhandle
%param-context = wf_item-json
) )
MAPPED DATA(mapped2)
FAILED DATA(failed2).
ASSERT lines( travels ) = lines( mapped2-cpwfinstance ).

ASSERT failed2-cpwfinstance IS INITIAL.

Previous: Creating the Data Model for Workflow Example [page 1093]

Reuse PUBLIC 1099
Next: Implementing the Service Callback Class [page 1100]
8.1.3 Implementing the Service Callback Class
The service callback class implements the process that is executed after the decision workflow has been
finished.
In this example the callback applies the accept / reject decision of the workfllow to the acceptTravel /
rejectTravel actions of the related travel instance.
1. Create the class /dmo/cl_wf_callback as described in .

2. Implement the interface if_swf_cpwf_callback:

CLASS /dmo/cl_wf_callback DEFINITION
PUBLIC
...
PUBLIC SECTION.
INTERFACES if_swf_cpwf_callback .
PROTECTED SECTION.
PRIVATE SECTION.
ENDCLASS.
CLASS /dmo/cl_wf_callback IMPLEMENTATION.
METHOD if_swf_cpwf_callback~workflow_instance_completed.
...
ENDMETHOD.
ENDCLASS.

3. Implement the workflow_instance_completed method.
1. Define the parameters wf_travel and wf_timestampl. Wf_travel contains all fields required to
receive the callback from the workflow and wf_timestampl contains the timestamp of the point in
time that the callback was received.


wf_timestampl TYPE timestampl.
...
ENDMETHOD.

4. To receive the callback data, a helper classes is required:
• cl_swf_cpwf_api_factory_a4c: With this class, you can retrieve an instance of the Workflow API which
allows access to workflows For further details, refer to the system documentation.
With the method get_context_data_from_json, you receive the data from the workflow response:

...
TRY.
DATA(json) = cpwf_api->get_workflow_context( iv_cpwf_handle =
iv_cpwf_handle ).
cpwf_api->get_context_data_from_json(
EXPORTING
iv_context = json
IMPORTING
ev_data = wf_travel

1100 PUBLIC Reuse
).

RAISE EXCEPTION TYPE /dmo/cx_wf_callback
EXPORTING
previous = lx_cpwf.
ENDTRY.
...

5. Fill the timestamp to save the point in time the reponse was received with the GET TIME STAMP method:

...
GET TIME STAMP FIELD wf_timestampl.
...

6. Update the travel fields relevant for the workflow for the active travel instance. This includes the
WFDecision to save the user decision, WFTimestamp to save the time information.

...
MODIFY ENTITIES OF /dmo/r_trvl_d_w
ENTITY Travel
UPDATE FIELDS ( WFDecision WFTimestamp WFHandle )
WITH VALUE #( ( TravelUUID = wf_travel-TravelUUID
WFDecision = wf_travel-WFDecision
WFTimestamp = wf_timestampl
WFHandle = '' ) )
FAILED DATA(failed)

7. If the modify fails, handle the exception handling based on the fail-cause.
For more information about fail-causes, see Reponse Parameter [page 161].

...
IF failed-travel IS NOT INITIAL.
CASE failed-travel[ 1 ]-%fail-cause.

WHEN if_abap_behv=>cause-not_found.
EXPORTING
textid = /dmo/cx_wf_callback=>travel_not_found
travel_id = wf_travel-travelid.
WHEN if_abap_behv=>cause-locked.
EXPORTING
textid = /dmo/cx_wf_callback=>travel_locked
WHEN OTHERS.
RAISE EXCEPTION TYPE /dmo/cx_wf_callback.
ENDCASE.
ENDIF.
...

8. Call either acceptTravel or rejectTravel actions based on the user decision saved in parameter
WFDecision. If WFDecision contains WF-accepted, acceptTravel is called to update the status. If it
contains WF-rejected, the action rejectTravel is called. If the rejectTravel fails an exception is
raised. Commit the final decision to the database with COMMIT ENTITIES.

...

Reuse PUBLIC 1101
" Call accept/reject Action based on WF outcome
IF wf_travel-WFDecision EQ 'WF-accepted'.
ENTITY Travel
EXECUTE acceptTravel
FROM VALUE #( ( TravelUUID = wf_travel-TravelUUID
FAILED DATA(failed_accept)
REPORTED DATA(reported_accept).
IF failed_accept-travel IS NOT INITIAL.

EXPORTING
textid = /dmo/cx_wf_callback=>travel_set_status_failed
ENDIF.
ELSEIF wf_travel-WFDecision EQ 'WF-rejected'.

ENTITY Travel
EXECUTE rejectTravel
FAILED DATA(failed_reject)
REPORTED DATA(reported_reject).
IF failed_reject-travel IS NOT INITIAL.

EXPORTING
ENDIF.
ENDIF.
COMMIT ENTITIES.
...

9. Raise an exception, if the callback fails.

...
IF sy-subrc NE 0.
ENDIF.
...

Result
You have implement the callback class to persist the accept or reject travel information received via the
workflow.
 Sample Code

CLASS /dmo/cl_wf_callback DEFINITION
PUBLIC
FINAL
CREATE PUBLIC .
PUBLIC SECTION.

1102 PUBLIC Reuse
INTERFACES if_swf_cpwf_callback .
PROTECTED SECTION.
PRIVATE SECTION.
ENDCLASS.
CLASS /dmo/cl_wf_callback IMPLEMENTATION.

wf_timestampl TYPE timestampl.
TRY.
DATA(json) = cpwf_api->get_workflow_context( iv_cpwf_handle =
iv_cpwf_handle ).
cpwf_api->get_context_data_from_json(
EXPORTING
iv_context = json
IMPORTING
ev_data = wf_travel
).

EXPORTING
previous = lx_cpwf.
ENDTRY.
GET TIME STAMP FIELD wf_timestampl.

ENTITY Travel
UPDATE FIELDS ( WFDecision WFTimestamp WFHandle )
WITH VALUE #( ( TravelUUID = wf_travel-TravelUUID
WFDecision = wf_travel-WFDecision
WFTimestamp = wf_timestampl
WFHandle = '' ) )
FAILED DATA(failed)
IF failed-travel IS NOT INITIAL.
CASE failed-travel[ 1 ]-%fail-cause.

WHEN if_abap_behv=>cause-not_found.
EXPORTING
textid = /dmo/cx_wf_callback=>travel_not_found
WHEN if_abap_behv=>cause-locked.
EXPORTING
textid = /dmo/cx_wf_callback=>travel_locked
WHEN OTHERS.
ENDCASE.

Reuse PUBLIC 1103
ENDIF.
" Call accept/reject Action based on WF outcome

IF wf_travel-WFDecision EQ 'WF-accepted'.
ENTITY Travel
EXECUTE acceptTravel
FAILED DATA(failed_accept)
REPORTED DATA(reported_accept).
IF failed_accept-travel IS NOT INITIAL.

EXPORTING
ENDIF.
ELSEIF wf_travel-WFDecision EQ 'WF-rejected'.

ENTITY Travel
EXECUTE rejectTravel
FAILED DATA(failed_reject)
REPORTED DATA(reported_reject).
IF failed_reject-travel IS NOT INITIAL.

EXPORTING
ENDIF.
ENDIF.
COMMIT ENTITIES.
IF sy-subrc NE 0.
ENDIF.
ENDMETHOD.
ENDCLASS.

Previous: Implementing a Workflow [page 1094]

1104 PUBLIC Reuse
9 CDS Annotations
The following list summarizes SAP annotations of the Data Definition Language (DDL) of ABAP CDS that are
relevant in the context of ABAP RESTful programming model and released for ABAP Cloud Platform.
SAP CDS annotations are evaluated by SAP frameworks and can be either ABAP annotations or framework-
specific annotations.
ABAP CDS - ABAP Annotations
CDS annotations that are evaluated by ABAP runtime:
• AbapCatalog Annotations
• AccessControl Annotations
• ClientHandling Annotations
• EndUserText Annotations
• Environment Annotations
• MappingRole Annotations
• Metadata Annotations
• Semantics Annotations
See also: ABAP CDS - View Annotations (ABAP Keyword Documentation)
 Tip
To access help for an ABAP annotation, position the cursor on the relevant annotation in the DDL editor and
press F1 .
Framework-Specific Annotations
Framework-specific CDS annotations (as a rule) are exposed for OData and evaluated during runtime.
• Aggregation Annotations [page 1107]

• AccessControl Annotations [page 1106]
• Consumption Annotations [page 1195]
• ObjectModel Annotations [page 1207]
• OData Annotations [page 1211]
• Search Annotations [page 1243]
• Semantics Annotations [page 1247]
• UI Annotations [page 1260]

CDS Annotations PUBLIC 1105
Related Information
CDS Annotation Syntax
9.1 AccessControl Annotations
Enable application developers to define how the authorization check for a CDS entity is executed
Scope and Definition
@Scope:[#VIEW, #TABLE_FUNCTION]

AccessControl.authorizationCheck : String(20) enum { NOT_REQUIRED; NOT_ALLOWED;
CHECK; PRIVILEGED_ONLY; } default #CHECK;

Usage
Annotation Meaning
AccessControl.autho This element defines the behavior of the authorization check.
rizationCheck Scope: [#VIEW]
Engine Behavior: The runtime and design-time engines handle the authorization check
based on the value of the element.
Values:
Value Description
#NOT_REQUIRED During the authorization runtime, an authorization check is

executed if a DCL role exists for the entity. If no role exists
there is no check and no protection. This behavior is the
same behavior at runtime as for value #CHECK. However in
this case it is intended by the developer that no role exists.
During development, no warning occurs when activating the

entity.
#NOT_ALLOWED During the authorization runtime, no authorization check is

executed.
During development, a warning occurs if a developer acti-

vates a role for an entity, which has this annotation value.

1106 PUBLIC CDS Annotations
Annotation Meaning
#CHECK During the authorization runtime, an authorization check is

executed if a DCL role exists for the entity. If no role exists
there is no check and no protection.
During development, a warning occurs if a developer acti-

vates the entity and no DCL role exists for the entity. This
value is the default value.
NOTE
The value #NOT_REQUIRED is recommended for entities for which no authorization checks are planned yet,
but might be needed by the developer or customer laster. To prohibit roles for the entity, use the value
#NOT_ALLOWED.
Example
When the developer activates the following DDL document, since an authorization check is not required, ABAP
development tools do not produce a warning. It does not matter whether a role exists for the entity or not.
At runtime, if there is a role for the entity, then ABAP performs an authorization check with the role. If there is
no role, there is no check and no protection for the entity.
 Sample Code
@AbapCatalog.sqlViewName: 'DEMO_CDS_PRJCTN'

define view demo_cds_spfli
as select from spfli
{ key spfli.carrid,
key spfli.connid,
spfli.cityfrom,
spfli.cityto }

9.2 Aggregation Annotations
  Specifies aggregation behavior on element level.
@Scope:[#ELEMENT]

annotation Aggregation
{

default: String(30) enum
{
NONE;
SUM;
MIN;
MAX;
AVG;
COUNT_DISTINCT;
NOP;
FORMULA;
};
exception : String( 30) enum
{
SUM;
MIN;
MAX;
AVG;
COUNT;
COUNT_DISTINCT;
FIRST;
LAST;
STANDARD_DEVIATION;
VARIANCE;
MEDIAN;
NHA;
};
referenceElement : array of ElementRef;
allowPrecisionLoss : Boolean default true;
};

Usage
With this annotation, you can specify the aggregation behaviour of elements in generic usage like analytic
manager or ODATA. Elements without default aggregation or with Aggregation.default: #NONE will not be
aggregated and will be used in GROUP BY for aggregating access. Elements that can be aggregated are known
as measures.
Annotation Meaning
Aggregation.allowPr The annotation can be used in the views of dataCategory: #CUBE or #FACT. They
must contain a currency or unit conversion.
ecisionLoss
 Note
If an analytical query (Analytics.query: true) is built with a #CUBE view, the

database aggregates the units or currency and then performs the conversion. This is
faster than converting on row level. The results maybe slightly different due to rounding.
Scope: #VIEW
Type: Boolean
Evaluation Runtime (Engine):This annotation will be interpreted by the analytic manager.

Annotation Meaning
Aggregation.default Scope: #ELEMENT
Type: String of ENUM
Evaluation Runtime (Engine): This annotation is integrated by both SADL and analytic
manager. Use all values for this annotation only for fields of numeric and date type. This is
only allowed in views with dataCategory: #CUBE, #FACT, #DIMENSION. Aggre-
gation should not be used for all character like fields.
ENUM Description
SUM The total (sum) of all values in this column is shown in the
result line.
MAX The highest value of all values in this column is shown in the
result line.
MIN The lowest value of all values in this column is shown in the
result line.
AVG The average of all values is calculated. In this annotation,

analytic manager requires a referenceElement while SADL
does not.
 Note
The analytic manager allows AVG only together

with Aggregation.referenceElement and ex-
actly one element in this list. Aggregation:
{ default: #AVG , referenceElement:
<element> } behaves like Aggregation:
{ default: #SUM, exception: #AVG ,
referenceElement: <element> }.
COUNT_DISTINCT The number of rows is calculated. SADL and analytic man-

ager both need a referenceElement in this annotation.
 Note
The analytic manager allows COUNT_DISTINCT only

together with Aggregation.referenceElement
and exactly one element in this list. be-
haves like Aggregation: { default:
#SUM, exception: #COUNT_DISTINCT ,
referenceElement: <element> }.
NOP NOP returns a value if all values are equal. Otherwise, it re-
turns a special error value. It is the default in views with and
dataCategory: #CUBE, #FACT,#DIMENSION if the
data type of the element is numeric. This can only be used
by analytic manager.

Annotation Meaning
FORMULA The value #FORMULA indicates that the element is a for-

mula. This has to be calculated after the operands have been
determined by aggregation or calculation. It should never be
aggregated. This only applies to analytic manager and not
to SADL.
 Note
This can only be used in views with

Analytics.query: true.
 Example
Margin : = Revenue / Cost. If Margin should be< shown

per OrgUnit in a report, the aggregates of Revenue and
Cost have to be determined per OrgUnit first, and then
the Margin has to be calculated per OrgUnit.> }
NONE This value indicates that the element is not a measure. Usu-
ally these elements are used in filters and GROUP BY state-
ments.
Aggregation.excepti Aggregation: {Exception aggregation is always performed in addition to default aggregation,
on which must not be equal to the #NONE. This is not an alternative to default aggregation.
This means that data is first aggregated through the default aggregation grouped by the
reference element and then aggregated with the exception aggregation. The list of reference
elements has to contain one field. If this field has a foreign key association or a text associa-
tion, then all fields in the ON condition of that association have to be part of the list.
 Note
If you want to use Aggregation.exception, you have

to define Aggregation.default (not equal to NONE) and
Aggregation.referenceElement in order to define the granularity with which
the aggregation rule is applied.
Scope: #ELEMENT
Evaluation Runtime (Engine): Analytic manager
ENUM Description
SUM, MAX, MIN, All these values determine the aggregation of the measure
AVG, COUNT, in the same way as SUM, MAX, MIN, AVG, COUNT,
COUNT_DISTINCT COUNT_DISTINCT in Aggregation.default.
FIRST, LAST These values indicate that the first or last value in relation to
the reference characteristic is shown in the result line.

Annotation Meaning
STANDARD_DEVIATION This value indicates that, after aggregating with the refer-
ence characteristic, the standard deviation of the calculated
values is shown in the results row.
VARIANCE This value indicates that, after aggregating with the refer-
ence characteristic, the variance of the calculated values is
shown in the results row.
MEDIAN This value indicates that the middle value (central value) of a
set sorted in ascending order is calculated:
• For a set with an uneven number of elements, the result

is the middle value.
 Example
For a set of five elements, the result is the value of

the third element. Suppose you have the following
values: 1, 12, 2, 4, 24. When the values are sorted in
ascending order (1, 2, 4, 12, 24), the median is the
third middle value, which is 4.
• For a set with an even number of elements, the result is

the average of the two middle values.
 Example
For a set of six elements, the result is the average

of the third and fourth elements. Suppose you have
the following values: 1, 12, 2, 4, 24, 6. When the
values are sorted in ascending order (1, 2, 4, 6, 12,
24), the median is the average of the values 4 and 6,
which is 5.
NHA No aggregation along the hierarchy. This value ensures that

nodes without a postable value part, and which only aggre-
gate the values of their children, are calculated as NULL.
This means they have no value if they are not postable no-
des. Postable nodes get the value of the postable child.
Aggregation.referen This annotation can be used in views of dataCategory: #CUBE or #FACT which
contain a currency or unit conversion. If an analytical query (Analytics.query:true),
ceElement
which is built on top of such a cube-view with with this annotation, the database first aggre-
gates grouped by the currency or unit and them performs the currency or unit conversion
This is much faster than the conversion row by row, but due to rounding effects, the result is
slightly different.
Scope: #ELEMENT
Type: Array of elementRef. You can specify a reference characteristic.
Evaluation Runtime (Engine): Analytic manager.

Examples
Example 1: default Aggregation
 Sample Code
@Semantics.currencyCode:true

GlobalCurrency,
@Semantics: { amount : {currencyCode: 'GlobalCurrency'} }
FixedAmountInGlobalCrcy,

When selecting FixedAmountInGlobalCrcy the SUM of this element is calculated.
Example 2: exception aggregation
 Sample Code
calendarDay,

@Semantics.unitOfMeasure: true
unit,
@Aggregation.exception: #LAST
@Aggrgation.referenceElement: ‘calenderDay’
@Semantics.quantity : ‘unit'
Quantity

This view describes the quantity of certain goods in a stock per calendar day. The measure quantity can be
aggregated with SUM for all dimensions except the calendar day.
Non-aggregated Data
calendarDay Plant Material Quantity
01/01/2018 Plant1 Material1 10 PC
02/01/2018 Plant2 Material2 70PC
Aggregate Quantity and Group by Material and Aggregate Quantity and Group by Material and CalendarDay
Material calendarDay Quantity
Material1 01/01/2018 40 PC
Material1 02/01/2018 30 PC
Material1 Result 30 PC
Material2 01/01/2018 90 PC

Material calendarDay Quantity
Material2 02/01/2018 110 PC
Material2 Result 110 PC
Result Result 140PC
Example 3: Counter-optimized
For CDS views representing master data reports (the FROM clause refers to a CDS view categorized as
#DIMENSION), a counter of the different dimension values can be defined by combining the annotation
Aggregation: #SUM with a select list entry containing constant value 1:
 Sample Code

@EndUserText.label: 'CostCenters per ControlingArea'
@Analytics.query: true
define view ControllingAreaView
as SELECT from CostCenterDimension {
controllingArea,
1 as costCenterCount
}

With costCenter in the key of the dimension, no exception aggregation is involved, thus improving the
performance of the report.
 Note
This pattern can be combined with CAST statements (for reusing texts of DDIC data types) and/or CASE
statements (for defining restricted measures). You must not use other constants than 1 however, or add
annotation AnalytcisDetails.query.formula.
9.3 Analytics Annotations
 Home Enable the analytic manager for multidimensional data consumption, performing data
aggregation, and slicing and dicing data. It is mandatory for each ENUM value that on field in the storage
view exists. BI front ends like SAP Analytics Cloud can consume the data via the analytic manager.
annotation Analytics

{
dataCategory : String(20) enum { DIMENSION; FACT; CUBE; AGGREGATIONLEVEL; };
query : Boolean default true;
hidden : Boolean default true;

planning
{
enabled : Boolean default true;
};
dataExtraction
{
delta
{
byElement
{
name : ElementRef;
maxDelayInSeconds : Integer default 1800;
detectDeletedRecords : Boolean default true;
ignoreDeletionAfterDays : Integer;
};
changeDataCapture
{
automatic : Boolean default true;
mapping: array of
{
role : String(30) enum {MAIN; LEFT_OUTER_TO_ONE_JOIN;};
table : String(30);
// only used if association is not specified
viewElement : array of ElementRef;
// only used if association is not specified
tableElement : array of String(30);
filter : array of
{
tableElement : String(30);
operator : String(11) enum
{EQ;NOT_EQ;GT;GE;LT;LE;BETWEEN;NOT_BETWEEN;} default #EQ;
value : String(45);
highValue : String(45);
};
};
};
};
filter : array of
{
viewElement : ElementRef;
operator : String(11) enum {EQ;NOT_EQ;GT;GE;LT;LE;BETWEEN;NOT_BETWEEN;}
default #EQ;
value : String(45);
highValue : String(45);
};
alternativeKey : array of ElementRef;

partitionBy : array of ElementRef;
// replication in cloud not allowed as long as communication scenario is
unclear
};
viewModelReplication
{
};
hints : String(1298);
writeBack
{
className : String(30);
// Implements IF_ROOPS_ODP_WRITEBACK

};
settings
{
maxProcessingEffort : String(20) enum { LOW; MEDIUM; HIGH; UNLIMITED; }
default #HIGH;
olapPushdown : String( 30 ) enum { OFF; MAX; };
zeroValues: {
handling: String(20) enum { SHOW; HIDE; HIDE_IF_ALL; } default #SHOW;
hideOnAxis: String(20) enum { ROWS; COLUMNS; ROWS_COLUMNS; } default
#ROWS_COLUMNS;
};
rows: {
hierarchicalDisplay : {
active : Boolean;
expandTo: ElementRef;
};
totalsLocation: String(10) enum { BOTTOM; TOP; };
};
columns {
active : Boolean;
};
totalsLocation: String(10) enum { RIGHT; LEFT; };
};
displayOriginalInitialValue: Boolean default true;
initialValueForMissingText : Boolean default true;
valueHelp : {
supressInitialValue : Boolean default true;
}
runtimeExtensibility : {
allowed : Boolean default true;
}
};
internalName : String(30) enum { DEFAULT; LOCAL; GLOBAL; };
technicalName : String( 16 ) ;
variableCheck: {
implementedBy : String(255); // String = 'ABAP:<Classname>' , class
implements IF_RSRTS_CDS_VARIABLE_CHECK
}
constraints: {
filter : String(20) enum { UNIQUE_PER_CELL; UNIQUE_PER_QUERY; };
}
processingEngine : String(5) enum { AE; MDS; };

onlyRestrictedAttributeTextAccess : Boolean default true;
readClassName : String(30);
excludeFromRuntimeExtensibilty : Boolean default true;
document
{
@Scope:[#VIEW]
storageForEntity: array of EntityRef;
@Scope:[#VIEW]
storagePersistence: array of EntityRef;
@Scope:[#VIEW]
serviceClassName: String(30); // implements IF_RSDOC_SERVICE_VIRT

@Scope:[#ELEMENT]
type: String(4) enum { DOC; TRA; SVA; SVH; HNM; HNO; HIO; };
@Scope:[#ELEMENT]
reference: String(30);
@Scope:[#ELEMENT]
semantics: String(30) enum { ID; VERSION; TAG; QPROV; TYPE; OWNER;
INFOPROV;
SVA_INFOPROV; KYFNM; STATUS; SESSION_ID;
TIMESTAMP;
DOCUMENT; SELECTIONS; PROPERTY; };
};
};

Usage
The analytic manager needs a star schema (multidimensional) and a query to consume the data. Most
annotations to define the star schema in different CDS views are specified in ObjectModel annotations.
SomeSemantics annotations are also available. The Analytics annotations also specify the facts (center
of the star schema), extraction capabilities for replicating data into further systems, and analytic query
properties. A semantic distinction can be made in the Analytics annotations between annotations that are
relevant for the InfoProvider (CUBE or DIMENSION) level and annotations that are only relevant for analytic
queries.
Analytics.constrain This annotation should be used for elements (dimensions) in cube views. It ensures that all
ts.filter analytic queries on top of the cube view provide a filter for that element.
Scope: #ELEMENT
Evaluation Runtime (Engine):Analytic manager should be used in cube views.
ENUM Description
UNIQUE_PER_CELL The filter has to be unique for each structure element but
different structure elements might have different filter values
- for example, plan-actual-sign or planVersion.
UNIQUE_PER_QUERY The filter has to be unique in the query.
Analytics.dataCateg Analytic queries can be defined on top of CDS views using the
ory Analytics.dataCategory annotation.
Scope: #VIEW
Evaluation Runtime (Engine): Analytic manager. By specifying the data category, the
developer can provide directives and hints, telling the analytic manager how to interpret
individual entities for example.
ENUM Description

DIMENSION This value indicates that the entity represents master data.
This kind of view can be used for replication and for queries.
 Example
Typical dimensions are material view and customer view.
FACT This value indicates that the entity represents master data.
 Example
CUBE The #CUBE value (like #FACT) also represents factual data,
but #CUBE doesn't have to be without redundancy. This
means joins with master data are possible. Queries are usu-
ally built on top of #CUBE, where data is replicated from
facts.
AGGREGATION_LEVEL This value indicates a projection. For this kind of view, the
analytic manager offers write-back functionality (planning
functionality). Views in this category have to select from
a view with dataCategory = #CUBE, which supports
the annotation Analytics.writeBack.className.
No associations are allowed, and elements can't be renamed.
 Note
This value should not be used for this annotation. This is

used for planning scenarios and such planning scenarios
are not currently available in cloud platforms but only on
premise.
Analytics.dataExtra In this annotation, if a CDS view is based on a table with a technical key and an alternative
ction.alternativeKe key, the CDS view typically uses the semantics key as a key.
y
 Note
It is important that the key of the main view and the key of the underlying main table are
identical.
Scope: #VIEW
Type: Array of ElementRef
Analytics.dataExtra The application developer can enable the generic delta extraction with this annotation.
ction.delta.byEleme
nt

Analytics.dataExtra By using this annotation, the system will remember all key combinations of the view that
ction.delta.byEleme were extracted in delta mode. If a key combination does not occur in the view anymore, this
will automatically generate a delete image in the extracted data.
nt.detectDeletedRec
ords Scope: #VIEW
Type: Boolean
Evaluation Runtime (Engine): Analytic manager. Detects deleted records.
Analytics.dataExtra This annotation only makes sense together with

ction.delta.byEleme Analytics.dataExtraction.delta.byElement.detectDeletedRecords.
nt.ignoreDeletionAf The extraction will ignore deleted records if they are older than the specified number of
terDays days. The main purpose is archiving.
 Example
If records are archived after 2 years, this value should be less than 700. In this case, the
deletion in the database tables will be ignored if the record is only older than 700 days.
Scope: #VIEW
Type: Integer - specified number of days.
Analytics.dataExtra There is always a time delay between taking a UTC time stamp and the database commit.
ction.delta.byEleme This annotation specifies the maximum possible delay in seconds.
nt.maxDelayInSecond Scope: #VIEW

s
Type: Integer - Maximum number of seconds between taking the time stamp and the
successful database commit. The default is 1800 seconds.
Analytics.dataExtra Application developers can enable the generic delta extraction with this annotation. This is
ction.delta.byEleme the element that should be used for filtering during generic delta extraction. This element
can be either a date (ABAP type DATS) or a UTC time stamp.
nt.name
Scope: #VIEW
Type: ElementRef - the name of an element that should be used for filtering during generic
delta extraction.
 Note
If the field is a time stamp, the system also checks the annotation
Semantics.systemDate.lastChangedAt: true. .

Analytics.dataExtra Use the CDC (change data capture) delta mechanism based on database triggers.
ction.delta.changeD Scope: #VIEW

ataCapture
Analytics.dataExtra In case of simple CDS views like projections no mapping information needs to be provided,
ction.delta.changeD but the relevant information about key fields etc. in inferred by the system.
ataCapture.automati Scope: #VIEW

c
Type: Boolean
Analytics.dataExtra In case of more complex CDS views, e.g. using joins, mapping information needs to be
ction.delta.changeD provided. With this annotation, you define the mapping of exposed elements in the CDS
view and the underlying table key fields; see also example 3.
ataCapture.mapping
Scope: #VIEW
Type: array of:
 Code Syntax
array of

{
role : String(30) enum {MAIN;
LEFT_OUTER_TO_ONE_JOIN;};
table : String(30);
// only used if association is not
specified
viewElement : array of ElementRef;
// only used if association is not
specified
tableElement : array of String(30);

filter : array of
See individual annotation descriptions for details.
Evaluation Runtime (Engine):Analytic manager

Analytics.dataExtra This annotation allows the definition of filters on the table to be logged for a CDS view. If
ction.delta.changeD the filter is one single value (no operator or operator #EQ), it can replace a missing mapping
between viewElement and table Element.
ataCapture.mapping.
filter Filter on logging table:
.tableElement: Name of the element in the logging table or view that is to be restricted.
.operator: Restriction operator, possible values are: #EQ, #NOT_EQ, #GT, #GE, #LT,
#LE, #BETWEEN, and #NOT_BETWEEN; default is #EQ.
.value: The filter value.
.highValue: That specifies the upper value for ranges defined in combination with opera-
tors #BETWEEN or #NOT_BETWEEN.
Scope: #VIEW
Type: array of:
 Code Syntax
array of {

tableElement : ElementRef;
operator :
String(11) enum;
value :
String(45);

highValue :
String(45);}
Analytics.dataExtra This annotation defines the role of the database table.

ataCapture.mapping.
role
ENUM Description
MAIN The key of the extraction view corresponds exactly to the key
of the underlying main table to be logged.
LEFT_OUTER_TO_ONE_J There is a left outer join but not all requirements of role
OIN #COMPOSITION are met.
Analytics.dataExtra Name of the table to be logged.

ataCapture.mapping.
Type: String
table

Analytics.dataExtra List of table key fields that map to CDS view elements.
ction.delta.changeD
 Note
ataCapture.mapping.
tableElement Both arrays, viewElement and tableElement, must contain the same number
of elements and must list them in the same order so that corresponding fields match.
Additionally, the array tableElement must contain exactly all key elements of the
logging table without the client element.
Scope: #VIEW
Type: ElementRef
Analytics.dataExtra List of CDS view elements that map to key fields of the underlying tables.
ction.delta.changeD If mapping.role LEFT_OUTER_TO_ONE_JOIN, the list enumerates all exposed CDS view
ataCapture.mapping. element names that correspond to key fields in this underlying outer table; in other words
viewElement that correspond to the foreign key fields used in the on-conditions of the joins.
Scope: #VIEW
Type: ElementRef
Analytics.dataExtra Application developers can use this annotation to mark views that are suitable for data
ction.enabled replication.
Scope: #VIEW
Type: Boolean
The default setting is true. In this case, the view is suitable for data replication. If set to false,
the view is not suitable for data replication.
 Note
This view must be annotated with Analytics.dataCategory (except the value

AGGREGATIONLEVEL) or with ObjectModel.dataCategory with the value
#TEXT or #HIERARACHY .
 Tip
Delta capabilities must be provided for mass data.
Analytics.dataExtra Filters to be applied after the extraction of data.
ction.filter Scope: #VIEW
Type Description

Filter on logging table:
 Code Syntax
.viewElement: Name of the element in the current view.
array of {

.operator: Possible values are #EQ, #NOT_EQ, #GT, #GE,
#LT, #LE, #BETWEEN, and #NOT_BETWEEN; default is #EQ.
viewElement : .value: The filter value.

ElementRef;
.highValue: Only used in combination with operators
#BETWEEN or #NOT_BETWEEN.
operator :
String(11)
enum;
value :
String(45);

highValue :
String(45);}
Analytics.dataExtra This annotation gives a list of view elements that can be used to partition the data.
ction.partitionBy If a CDS view might return more than 1 million records, you need to split a full extraction
request into several disjoint data packages.
Scope: #VIEW
Analytics.document The analytic manager offers features to add, modify, or delete comments in the Result
set of a Query in analytic manager. The comments should be visible in all queries of one
cube view which share the same filters. With the annotations,Analytics.document it is
possible to define a storage for documents, assign cube views to a storage, and enable an
analytical query for comments.
 Note
The view that provides the documents (storage) needs the annotation
Analytics.dataCategory: #DOCSTORE. The document storage needs spe-
cial elements. Its elements have to be classified with the annotation Ananltics.docu-
ment.reference, -.semantics, and -.type.

Analytics.document. This annotation should be used in the document storage. This means the view with
reference @Analytics.dataCategory: #DOCSTORE. "The cube view" refers to the view refer-
enced by Analytics.document.storageForEntity.
For each dimension field in the cube view, two fields with
Analytics.document.reference must exist in the field. One of the annotations
has to have the additional annotation Analytics.document.type: #TRA. This field
has to have the same type as the field in the cube view. The other field needs the anno-
tation Analytics.document.type: #SVA. and has to be type # CHAR 1. If the
dimension supports hierarchies, then four additional fields with the following types: #SVH
(CHAR1), #HNM (CHAR 30), #HNO (CHAR 32), and #HIO (CHAR 30) are
also needed.
The annotation should be used in the document storage- the view with
Analyitcs.dataCategory: #DOCSTORE. "The cube view" means the view that is
referenced by Analytics.document.storageForEntity.
 Note
The annotation Analytics.document.reference is used for describing the

meaning of the fields in the Document CDS View. The storage view needs specific fields:
• Administrative fields need to have the an-

notations Analytics.document.type. #DOC and
Analytics.document.semantics.
• For each dimension field of the referenced cube view
(Analytics.document.storageForEntity), fields with special
Analytics.document.type annotations are needed.
Scope: #ELEMENT
Type: String

Analytics.document. Each enumeration (Enum) value listed below, a field has to exist with both the
semantics Analytics.document.semantics and Analytics.document.type: #DOC
annotations.
 Note
The annotation Analytics.document.semantics is used for describing the


Scope: #ELEMENT
ENUM Description
ID Field of type NUMC 16
TAG Field of type CHAR 60
QPROV Field of type CHAR 30
TYPE Field of type CHAR 1
OWNER Field of type CHAR 12
INFOPROV Field of the type CHAR 30
SVA-INFOPROV Field of the type CHAR 1
KYFNM Field of type CHAR 30
STATUS Field of type CHAR 1
SESSION_ID Field of type CHAR 30
TIMESTAMP Field of type DEC 15. In CDS:ABAP data element with refer-
ence to domain TZNTSTMPS.
DOCUMENT Field of type RAWSTRING
SELECTIONS Field of type RAWSTRING
PROPERTY Field of type RAWSTRING

Analytics.document. A CDS-based DocumentStore handles DocumentIDs and the assignment to cells in a
serviceClassName query result. The real documents are handled by the application. In order to achieve
this, the application has to implement a class with implements a special interface
IF_RSDOC_SERVICE_VIRT and the name of the class has to be assigned to the Docu-
ment CDS view.
Scope: #VIEW
Type: String
Analytics.document. This annotation provides a list of cube views that the comments are provided for. At first,
storageForEntity only one view is allowed. This annotation has to be used in a document storage view and
needs the header annotation Analytics.dataCategory. #DOCSTORE.
Scope: #VIEW
Type: Array of EntityRef
Analytics.document. This annotation can be used in CDS-cube views(Analytics.dataCategory:

storagePersistence
#CUBE) or in analytical query views. In a cube view, it describes the list of possible docu-
ment storages. At first, only one star age view is allowed. On the query level, it describes
which document storage should be used. Here only one entry is allowed and it must be in
the list of possible storages of the underlaying cube view.
Scope: #VIEW
Analytics.document. The annotation Analytics.document.semantics is used for describing the mean-

type ing of the fields in the Document CDS View. The storage view needs specific fields:
• Administrative fields need to have the annotations Analytics.document.type.

#DOC and Analytics.document.semantics.
Scope: #ELEMENT
ENUM Description
DOC
TRA
SVA

SVH
HNM
HNO
HIO
Analytics.excludeFr Some BI clients allow to extend the runtime view with further dimensions or measures
omRuntimeExtensibil from the cube view that are not predefined tin the CDS query view. Some dimensions or
measures should be excluded from this feature either because they are DPP relevant and
ity
arbitrary users would be excluded from this feature either because they are DPP relevant
and arbitrary users shouldn't use these or because they re of a technical nature. Fields in
the CDS cube view with this annotation are excluded from the runtime extensibility.
Scope: #ELEMENT
Type: Boolean
The analytic manager ensures that an analytics query on top of that cube view supports a
filter for this element.
Analytics.hidden Usage on the element level: You can use this flag to decide whether the entity should be
visible to analytic clients.Usage on the view level: Views with Analytics.query are not
exposed in value help. Views with Analytics.dataCategory are not exposed in value
help for the CDS query designer.
Scope: #ELEMENT, #VIEW
Type: Boolean
True-
• The element will not be added to the InfoProvider model of Analytics. You can use this
flag if there are elements in the view, which shouldn't be part of the InfoProvider model
of Analytics for technical reasons, but the flag can't be deleted because the view is not
consumed by Analytics. Using this flag, you can avoid error messages from Analytics
for these elements.
• The view cannot be consumed by analytic clients. The default is true if this annotation
is used.
False- The view can be consumed by analytic clients.

Analytics.hints This annotation is reserved for special hints for the Analytics engine in ABAP.
Usage on the view level: Views with Analytics.query are not exposed in value help.
Views with Analytics.dataCategory are not exposed in value help for the CDS query
designer.
Scope: #VIEW
Type: String
Analytics.internalN The CDS model is transformed to an InfoProvider or InfoObject model. The ana-
ame lytic protocols like INA or BICS are based on InfoProvider and InfoObject names.
The elements of an analytic CDS view (CUBE, FACT, DIMENSION) are mapped to
InfoObject names. If there is an @ObjectModel.foreignKey.assocation or
@ObjectModel.text.assocation, and the target of the association is only used
once, the InfoObject name is derived by default from the SQL view name of the target view.
These names are called #GLOBAL. The InfoObject name for the representative key element
of a dimension is always derived from the dimension view. In all other cases, the InfoObject
name is derived from the view and the element name. These names are called #LOCAL.
With this annotation, the identifier that is used between BI Tools and the analytic manger
can be influenced, meaning that adding @ObjectModel.foreignKey.association
or @ObjectModel.text.association will not change the identifier.
 Note
If multiple elements are used in the ON condition of the foreign key association of
an element, and the InfoObject name should be global, all other elements of the ON
condition need to be global InfoObject names. This default behavior can be overruled
with this annotation.
ENUM Description

LOCAL • At Element level: The element is assigned to
a local InfoObject name. If not possible, an er-
ror is raised. This is useful if the annotation
@Object.Model.foreignKey.assocation
should be added to an element of an existing view. The
InfoObject name will then not change.
• At View level: All elements for which it is possible will
be assigned to a local InfoObject name. If it is used,
@ObjectModel.foreignKey.assocation /
@ObjectModel.text.assocation can be added,
changed, or removed without changing the InfoObject
names.
GLOBAL • At Element level: The element is assigned to an InfoOb-

ject with a global name. If not possible, an error is
raised. It can be used if there are multiple elements
referencing to the same dimension (same target of the
foreign key association). In this case, one element can
be specified. This is then given the global name, while all
others are given local names. If not specified, the first el-
ement is given the global name. It is especially useful for
an existing element if a new element should be added,
which should reference to the same dimension.
• At View level: The default is GLOBAL. All elements for

which it is possible will be assigned to a global InfoOb-
ject name.
Analytics.onlyRestr Only for views with Analytics.dataCategory #DIMENSION or

ictedAttributeTextA
ObjectModel.dataCategory #TEXT. Cube data is always read restricted (DCL) via
ccess
the analytical engine. The display attributes and text for the keys in the query result are read
privileged. If the annotation is set in the dimension, the display attributes are read restricted
(DCL of the dimension view) and if it is set in the text view, the text is read restricted (DCL of
the text view).
Scope: #VIEW
Type: Boolean

Analytics.planning. An input-enabled query provides writeback capabilities and can be used in planning scenar-
enabled ios.
Scope: #VIEW
Type: Boolean
True: The view is enabled for planning. The default is true if this annotation is used.
False: The view is not enabled for planning.
 Note
The view has to select data from a view, which is annotated with
Analytics.dataCategory: #AGGREGATIONLEVEL.
 Note
This view must be annotated with Analytics.query: true.
Evaluation Runtime (Engine): Specifies which view will be interpreted as input-enabled

analytic query by the analytic manager.
Analytics.processin Specifies the Analytic engine with which the analytical query should be processed. The
gEngine engines might offer different features.
Scope: #ELEMENT
ENUM Description
AE The query will be processed by the Analytic Engine that is

implemented in ABAP but number crunching is pushed down
to HANA. This is the default setting.
MDS The query will be processed by the MDS Analytical Engine

inside SAP HANA.

Analytics.query Query view classification.
Scope: #VIEW
Type: Boolean
True- The query view will be exposed to the analytic manager. The default is true if
this annotation is used.
 Note
Data will be selected from the view specified in the from clause. The view of the from
clause has to be annotated with the Analytics.dataCategory as #DIMENSION,
#CUBE or #AGGREGATIONLEVEL, and the DCL has to be assigned to the view of the
from clause.
False: The query view will not be exposed to the analytic manager.
Evaluation Runtime (Engine): By tagging the CDS view, the developer can specify which
views will be exposed to the analytic manager. This type of view will be interpreted as an
analytic query by the analytic manager.
 Note
This view must not be annotated with Analytics.dataCategory = #NONE.
Analytics.readClass Only for views with Analytics.dataCategory #CUBE. This annotation specifies an
Name ABAP-class which has to implement the interface IF_RSRTS_CDS_READ. At runtime the
Analytical Engine (and only this) calls the methods of the class instead selecting data
from the CDS view. This means the Analytical Engine can't use any optimization like HANA-
pushdown for complex queries. Furthermore, the developer of the class is responsible for
data authorization (DCL). Therefore, the annotation should only be used in exceptional
cases.
Scope: #VIEW
Type: String . Name of an ABAP class, which implements the interface

IF_RODPS_ODP_WRITEBACK. className as String
Evaluation Runtime (Engine): Specifies which class enables the analytic manager to write
data to the view.
 Note
The read class is not called if the view is called view SQL or if it is the source of another
CDS view, which is not an analytical query.
Anayltics.settings. This annotation switches on the universal hierarchy for the dimensions on the columns.
columns.hierarchica Scope: #VIEW

lDisplay.active
Type: Boolean

Analytics.settings. If universal hierarchy display is switched on columns, the hierarchy will be expanded to the
columns.hierarchica level specified by this annotation.
ldisplay.expandTo Scope: #VIEW
Type: ElementRef
Analytics.settings. This annotation specifies are shown to the right or the left of the details. If nothing is
columns.totalsLocat specified the default is RIGHT without display hierarchy and LEFT with display hierarchy.
ions Scope: #VIEW
ENUM Description
RIGHT Show results on columns right of the details
LEFT Show results on columns left of the details
Analytics.settings. The Analytical Manager usually displays the initial value of a dimension as #. If the annota-
displayOriginalValu tion is set to true, the external value of the initial value will be shown. Showing # is the
default if the annotation is not set.
e
It can be set in the header of a dimension or text view, or it can be set for analytic manager
in a cube view without foreign key or text association.
It can only be set for dimensions where the initial value is not a space.
Scope: #VIEW
Type: Boolean
Analytics.settings. If text should be displayed but a text is missing for a single key, then the display key is
initialValueForMiss displayed for this single key.
ingText
If the text should remain empty, this annotation has to be set as a header annotation:
• In the text view with ObjectModel.dataCategory: #TEXT.
• With Analytics.dataCategory: #DIMENSION if the dimension provides the

text.
Scope: #VIEW
Type: Boolean

Analytics.settings. If InfoProviders store large amounts of data, certain queries can retrieve large result sets.
maxProcessingEffort The maxProcessingEffort is the maximum effort expected by analytic manager for process-
ing the data it retrieves.
When the limit is reached, the analytic manager returns an error message and the user can
set filters or remove dimensions from the axis in order to get smaller result sets.
Scope: #VIEW
Evaluation Runtime (Engine): This annotation will be interpreted by the analytic manager
for query views (Analytics.query: true).
ENUM Description
LOW
MEDIUM
HIGH The default is #HIGH.
UNLIMITED There is no limit when reading data but processing might

crash memory overflow error or other similar issues may
occur.
Analytics.settings. The Analytic manager is able to map som OLAP features as an SAP HANA calcula-
olapPushdown tion scenario. This means some calculations are not calculated in the ABAP server
but rather in HANA, which is faster in most cases. This is what we call "pushdown".
Unfortunately, the performance is not improved by the pushdown in all cases. By
default, all queries using certain features will be processed with pushdown. With
Analytics.settings.olapPushdown: Off set for a cube view, you can switch
off the pushdown for all queries of that cube. If the annotation is set on query level, then the
setting of the cube is overruled. This means with OFF you can switch off the pushdown for
a single query. With MAX, pushdown is performed off if pushdown has been switched off in
the cube.
Scope: #VIEW
Type:String of ENUM
ENUM Description
OFF The analytic manager doesn't use the pushdown mecha-

nism and accesses cube data via SQL (corresponds to
TREXOPS = 0).
MAX The analytic manager performs the pushdow if relevant fea-

tures are used in the query. (corresponds to TREXOPS =
9).

Analytics.settings. This annotation shows all dimensions that are on the rows in a universal display hierarchy.
rows.hierarchicalDi Scope: #VIEW

splays.active
Type: Boolean
Analytics.settings. With the annotation, the hierarchy will be expanded to the level specified if the universal
rows.hierarchicalDi display hierarchy is switched to rows.
spaly.expandTo Scope: #VIEW
Type: ElementRef
Analytics.settings. This annotation specifies if the totals appear on the rows above the details or below the
rows.totalsLocation details.
s If nothing is specified the default setting is as follows:
• If there is no hierarchy, the totals are displayed below the details.

• If there is a display hierarchy, the totals are on top and the parents are above the
children.
Scope: #VIEW
ENUM Description
BOTTOM The results are at the bottom below the details.
TOP The results are at the top.
Analytics.settings. If this annotation is set in the header of the CDS query view, some BI tools offer
runtimeExtenbsibili the possibility to extend the runtime view with further dimensions or measures at run-
time. This is not possible if this annotation is not set. If not all dimensions or meas-
ty.allowed
ures of the cube view should be used, these can be excluded with the annotation
Analytics.excludeFromRuntimeExtensibility.
Scope: #VIEW
Type: Boolean

Analytics.settings. This annotation can be used in views of the type Analytics.dataCategory: #DIMEN-
valueHelp.suppressI SION and in views of type ObjectModel.dataCategory: #TEXT.
nitialValue If a text association for the representative key field exists, the annotation of the dimension is
relevant and the annotation of the text view will be ignored. If this annotation is set, an extra
line for the initial value will not be added when value help is processed. If a record exists
with initial key, it wall always be shown independent of the annotation.
Scope #VIEW
Type: Boolean
Analytics.settings. You can specify whether rows or columns with cells that contain zeros as values are to be
zeroValues.handling displayed.
Scope: #VIEW
ENUM Description
SHOW You can specify that zeros are to be displayed (No zero sup-
pression takes place). The default is #SHOW.
HIDE If you want to suppress zeros, there are two options availa-
ble: #HIDE and #HIDE_IF_ALL . For queries that have
characteristics in the rows and key figures in the columns
(or the other way around, with key figures in the rows and
characteristics in the columns), the effect of the settings
is identical. The two settings only differ in how they affect
queries that have characteristics in the rows and columns
(cross-classified table). If you use zero suppression with the
#HIDE value, the system checks whether there are zero val-
ues in the results area. If there are zero values in the results
area, the corresponding row or column is hidden.

HIDE_IF_ALL For queries that have characteristics in the rows and key
figures in the columns (or the other way around, with key
figures in the rows and characteristics in the columns),
the effect of the value is identical to #HIDE. If your query
has characteristics in the rows and columns however (cross-
classified table), and you use zero suppression with the
#HIDE_IF_ALL value, the system hides all rows or col-
umns that contain zero values. Examples are plan-actual-
sign or planVersion.
 Note
If a detail row is not equal to zero (in a hierarchy for

example), all superordinate rows are displayed, even if
they contain zeros. As a result, the system ensures that
the business context of the query is retained for the end
user, even if the value #HIDE_IF_ALL is set.
Analytics.settings. You can specify whether rows or columns that contain zeros as values are to be hidden.
zeroValues.hideOnAx Scope: #VIEW

is
ENUM Description
ROWS Only rows that contain zeros as values are to be hidden.
COLUMNS Only columns that contain zeros as values are to be hidden.
ROWS_COLUMNS The default is ROWS_COLUMNS. Rows and columns that

contain zeros as values are to be hidden.
Analytics.technical Names in the analytical model are derived from the annotation
Name AbapCatalog.sqlViewName for CDS views or from the CDS name for view entities.
If a view entity provides the annotation Analytics.technicalName, the name in the
analytical model is derived from this. It should only be used when migrating a CDS view to a
CDS view entity.
Scope: #VIEW, #ELEMENT
Type: String

Analytics.variableC The consistency of the variable input can be checked.
heck.implementedBy Scope: #VIEW
Type: String - Name of an ABAP class that implements

IF_RSRTS_CDS_VARIABLE_CHECK. The interface method is called when a variable
screen is confirmed at runtime of the analytics query.
 Note
This is only interpreted in the context of an analytical query.
Analytics.viewModel In the UI of the CDS view replication, a customer can choose the CDS views that shall be
Replication.enabled replicated. Here, the customer can only select from those CDS views that are enabled for
view model replication. The annotation is used to enable a view for view model replication.
Scope: #VIEW
Type: Boolean
Analytics.viewModel The annotation is used to enable a view for view replication.View replication is mainly used
Replication.enabled for analytical use cases.
Scope: #VIEW
Type: Boolean
Analytics.writeBack Views with Analytics.dataCategory: #AGGREGATIONLEVEL on top of this type

.className of view can be used for planning scenarios. The ABAP class is used for saving the data,
authorization checks, and enqueuing.
Scope: #VIEW
Type: String. Name of the ABAP class that integrates the interface
IF_RODPS_ODP_WRITEBACK
Evaluation Runtime (Engine): Specifies which class enables the analytic manager to write
data to the view.
 Note
Only relevant if Analytics.dataCategory: #CUBE or

Analytics.dataCategory: #FACT.
Examples
Example 1
Example for replication-enabled master data.

 Sample Code
@EndUserText.label: 'EPM Demo: Employee'

@Analytics:{ dataCategory: #DIMENSION , dataExtraction.enabled: true }
@AccessControl.authorizationCheck: #CHECK
@ObjectModel.representativeKey: 'EmployeeUUID'
@AbapCatalog.sqlViewName: 'SEPM_IEMPLOYEE'
define view SEPM_I_Employee as
select from snwd_employees
association [0..1] to SEPM_I_Company as _Company
on $projection.CompanyUUID = _Company.CompanyUUID
...
{
key snwd_employees.node_key as EmployeeUUID,
@ObjectModel.foreignKey.association: '_Company'
snwd_employees.parent_key as CompanyUUID,

...}
Example 2
Example for transactional data (fact).
 Sample Code
@EndUserText.label: 'EPM Demo: Sales Order Item with Addtl. Data (private
view)'

@Analytics.dataCategory: #CUBE
@AbapCatalog.sqlViewName: 'SEPM_PSOIC'
define view SEPM_P_SalesOrderItemCube
as select from SEPM_I_SalesOrderItem
association [0..1] to SEPM_I_SalesOrder_E as _SalesOrder_E
on $projection.salesorder = _SalesOrder_E.SalesOrder
...
{
@ObjectModel.foreignKey.association: '_SalesOrder_E'
key _SalesOrder.SalesOrder,
_SalesOrder_E,

...}
Example 3
Example for defining a list of tables that should be logged for delta data extraction.
 Sample Code
@Analytics: {

dataCategory: #FACT,
dataExtraction: {
enabled: true,
delta.changeDataCapture.mapping:
[ { table: 'rsodpcdcunittab2', role: #MAIN, viewElement:
['view_key1', 'view_key2'], tableElement: ['tab_key1', 'tab_key2'] },
{ table: 'rsodpcdcunittab1', role: #LEFT_OUTER_TO_ONE_JOIN,
viewElement: ['view_key3'], tableElement: ['tab_key1'] } ]

} }

9.4 Analytics Annotations
 Cloud Enable the analytic manager for multidimensional data consumption, performing data
aggregation, and slicing and dicing data. It is mandatory for each ENUM value that on field in the storage
view exists. BI front ends like SAP Analytics Cloud can consume the data via the analytic manager.
annotation Analytics

{
dataCategory : String(20) enum { DIMENSION; FACT; CUBE; AGGREGATIONLEVEL; };
query : Boolean default true;
hints : String(1298);
};
settings
{
maxProcessingEffort : String(20) enum { LOW; MEDIUM; HIGH; UNLIMITED; }
default #HIGH;
zeroValues: {
handling: String(20) enum { SHOW; HIDE; HIDE_IF_ALL; } default #SHOW;
hideOnAxis: String(20) enum { ROWS; COLUMNS; ROWS_COLUMNS; } default
#ROWS_COLUMNS;
};
rows: {
active : Boolean;
};
totalsLocation: String(10) enum { BOTTOM; TOP; };
};
columns {
active : Boolean;
};
totalsLocation: String(10) enum { RIGHT; LEFT; };
};
displayOriginalInitialValue: Boolean default true;
initialValueForMissingText : Boolean default true;
valueHelp : {
supressInitialValue : Boolean default true;
}
runtimeExtensibility : {
allowed : Boolean default true;
}
};
internalName : String(30) enum { DEFAULT; LOCAL; GLOBAL; };
technicalName : String( 16 ) ;
variableCheck: {
implementedBy : String(255); // String = 'ABAP:<Classname>' , class
implements IF_RSRTS_CDS_VARIABLE_CHECK

}
constraints: {
filter : String(20) enum { UNIQUE_PER_CELL; UNIQUE_PER_QUERY; };
}
excludeFromRuntimeExtensibilty : Boolean default true;
document
{
@Scope:[#VIEW]
storageForEntity: array of EntityRef;
@Scope:[#VIEW]
storagePersistence: array of EntityRef;
@Scope:[#ELEMENT]
type: String(4) enum { DOC; TRA; SVA; SVH; HNM; HNO; HIO; };
@Scope:[#ELEMENT]
reference: String(30);
@Scope:[#ELEMENT]
semantics: String(30) enum { ID; VERSION; TAG; QPROV; TYPE; OWNER;
INFOPROV;
SVA_INFOPROV; KYFNM; STATUS; SESSION_ID;
TIMESTAMP;
DOCUMENT; SELECTIONS; PROPERTY; };
};
};

Usage
The Analytic Manager needs a star schema (multidimensional) and a query to consume the data. Most
annotations to define the star schema in different CDS views are specified in ObjectModel annotations. Some
Semantics annotations are also relevant. The Analytics annotations also specify the facts (center of the
star schema), extraction capabilities for replicating data into further systems, and analytic query properties. A
semantic distinction can be made in the Analytics annotations between annotations that are relevant for the
InfoProvider (CUBE or DIMENSION) level and annotations that are only relevant for analytic queries.
Annotation Meaning
Analytics.constrain This annotation should be used for elements (dimensions) in cube views. It ensures that all
ts.filter analytic queries on top of the cube view provide a filter for that element.
Scope: #ELEMENT
Evaluation Runtime (Engine): Analytic manager should be used in cube views.
ENUM Description
UNIQUE_PER_CELL The filter has to be unique for each structure element but dif-
ferent structure elements might have different filter values-
for example plan-actual-sign or planVersion.

Annotation Meaning
UNIQUE_PER_QUERY The filter has to be unique in the query.
Analytics.dataCateg Analytic queries can be defined on top of CDS views using the
ory Analytics.dataCategory annotation.
Scope: #VIEW
Evaluation Runtime (Engine): By specifying the data category, the developer can provide
directives and hints, telling the analytic manager how to interpret individual entities for
example.
ENUM Description
DIMENSION This value indicates that the entity represents master data.
 Example
FACT This value indicates that the entity represents master data.
 Example
CUBE The #CUBE value (like #FACT) also represents factual data,
but #CUBE doesn't have to be without redundancy. This
means joins with master data are possible. Queries are usu-
ally built on top of #CUBE, where data is replicated from
facts.
AGGREGATION_LEVEL This value indicates a projection. For this kind of view, the
analytic manager offers write-back functionality (planning
functionality). Views in this category have to select from
a view with dataCategory = #CUBE, which supports
the annotation Analytics.writeBack.className.
No associations are allowed, and elements can't be renamed.
 Note
This value should not be used for this annotation. This is

used for planning scenarios. These planning scenarios
aren't currently available in cloud platforms but only
on premise.

Annotation Meaning
Analytics.document. Each enumeration (Enum) value listed below, a field has to exist with both the
semantics Analytics.document.semantics and Analytics.document.type: #DOC
annotations.
 Note
The annotation Analytics.document.semantics is used for describing the


Scope: #ELEMENT
ENUM Description
ID Field of type NUMC 16
TAG Field of type CHAR 60
QPROV Field of type CHAR 30
TYPE Field of type CHAR 1
OWNER Field of type CHAR 12
INFOPROV Field of the type CHAR 30
SVA-INFOPROV Field of the type CHAR 1
KYFNM Field of type CHAR 30
STATUS Field of type CHAR 1
SESSION_ID Field of type CHAR 30
TIMESTAMP Field of type DEC 15. In CDS:ABAP data element with refer-
ence to domain TZNTSTMPS.
DOCUMENT Field of type RAWSTRING
SELECTIONS Field of type RAWSTRING

Annotation Meaning
PROPERTY Field of type RAWSTRING
Analytics.document. A CDS-based DocumentStore handles DocumentIDs and the assignment to cells in a

serviceClassName query result. The real documents are handled by the application. In order to achieve
this, the application has to implement a class with implements a special interface
IF_RSDOC_SERVICE_VIRT and the name of the class has to be assigned to the Docu-
ment CDS view.
Scope: #VIEW
Type: String
Analytics.document. This annotation provides a list of cube views that the comments are provided for. At first,
storageForEntity only one view is allowed. This annotation has to be used in a document storage view and
needs the header annotation Analytics.dataCategory. #DOCSTORE.
Scope: #VIEW
Analytics.document. This annotation can be used in CDS-cube views(Analytics.dataCategory:

storagePersistence
#CUBE) or in analytical query views. In a cube view, it describes the list of possible docu-
ment storages. At first, only one star age view is allowed. On the query level, it describes
which document storage should be used. Here only one entry is allowed and it must be in
the list of possible storages of the underlaying cube view.
Scope: #VIEW
Analytics.document. The annotation Analytics.document.semantics is used for describing the mean-

type ing of the fields in the Document CDS View. The storage view needs specific fields:
• Administrative fields need to have the annotations Analytics.document.type.

#DOC and Analytics.document.semantics.
Scope: #ELEMENT
ENUM Description
DOC

Annotation Meaning
TRA
SVA
SVH
HNM
HNO
HIO
Analytics.excludeFr Some BI clients allow to extend the runtime view with further dimensions or measures
omRuntimeExtensibil from the cube view that are not predefined in the CDS query view. Some dimensions or
ity measures should be excluded from this feature either because they are DPP relevant and
arbitrary users would be excluded from this feature and shouldn't be used by arbitrary users
or because they are of a technical nature. Fields in the CDS cube view with this annotation
are excluded from the runtime extensibility.
Scope: #ELEMENT
Type: Boolean
The analytic manager ensures that an analytics query on top of that cube view supports a
filter for this element.
Analytics.hidden Usage on the element level: You can use this flag to decide whether the entity should be
visible to analytic clients. Usage on the view level: Views with Analytics.query are not
exposed in value help. Views with Analytics.dataCategory are not exposed in value
help for the CDS query designer.
Type: Boolean
• TRUE-
• The element will not be added to the InfoProvider model of Analytics. You can
use this flag if there are elements in the view, which shouldn't be part of the
InfoProvider model of Analytics for technical reasons, but the flag can't be deleted
because the view is not consumed by Analytics. Using this flag, you can avoid error
messages from Analytics for these elements.
• The view cannot be consumed by analytic clients. The default is true if this annota-
tion is used.
• FALSE- The view can be consumed by analytic clients.

Annotation Meaning
Analytics.hints This annotation is reserved for special hints for the Analytics engine in ABAP.
Scope: #VIEW
Type: String
Analytics.internalN The CDS model is transformed to an InfoProvider or InfoObject model. The ana-
ame lytic protocols like INA or BICS are based on InfoProvider and InfoObject names.
The elements of an analytic CDS view (CUBE, FACT, DIMENSION) are mapped to
InfoObject names. If there is an ObjectModel.foreignKey.assocation or
ObjectModel.text.assocation, and the target of the association is only used once,
the InfoObject name is derived by default from the SQL view name of the target view. These
names are called #GLOBAL. The InfoObject name for the representative key element of
a dimension is always derived from the dimension view. In all other cases, the InfoObject
name is derived from the view and the element name. These names are called #LOCAL.
With this annotation, the identifier that is used between BI Tools and the analytic manger
can be influenced, meaning that adding ObjectModel.foreignKey.association
or ObjectModel.text.association will not change the identifier.
Evaluation Runtime (Engine): Analytic manager.
 Note
If multiple elements are used in the ON condition of the foreign key association of
an element, and the InfoObject name should be global, all other elements of the ON
condition need to be global InfoObject names. This default behavior can be overruled
with this annotation.
ENUM Description
LOCAL • At Element level: The element is assigned to

a local InfoObject name. If not possible, an
error is raised. This is useful if the annota-
tion Object.Model.foreignKey.assocation
should be added to an element of an existing view. The
InfoObject name will then not change.
• At View level: All elements for which it is possible will
be assigned to a local InfoObject name. If it is used,
@ObjectModel.foreignKey.assocation /
ObjectModel.text.assocation can be added,
changed, or removed without changing the InfoObject
names.

Annotation Meaning
GLOBAL • At Element level: The element is assigned to an InfoOb-

ject with a global name. If not possible, an error is
raised. It can be used if there are multiple elements
referencing to the same dimension (same target of the
foreign key association). In this case, one element can
be specified. This is then given the global name, while all
others are given local names. If not specified, the first el-
ement is given the global name. It is especially useful for
an existing element if a new element should be added,
which should reference to the same dimension.
• At View level: The default is global. All elements for

which it is possible will be assigned to a global InfoOb-
ject name.
Analytics.query Query view classification.
Scope: #VIEW
Type: Boolean
• TRUE - The query view will be exposed to the analytic manager. The default is
true if this annotation is used.
 Note
Data will be selected from the view specified in the from clause. The view of
the from clause has to be annotated with the Analytics.dataCategory
as #DIMENSION, #CUBE or #AGGREGATIONLEVEL, and the DCL has to be
assigned to the view of the from clause.
• FALSE - The query will not be exposed to the analytic manager.
Evaluation Runtime (Engine): This type of view will be interpreted as an analytic query by
the analytic manager. By tagging the CDS view, the developer can specify which views will
be exposed to the analytic manager.
 Note
This view must not be annotated with @Analytics.dataCategory = #NONE.
Anayltics.settings. This annotation switches on the universal hierarchy for the dimensions on the columns.
columns.hierarchica Scope: #VIEW

lDisplay.active
Type: Boolean

Annotation Meaning
Analytics.settings. If universal hierarchy display is switched on columns, the hierarchy will be expanded to the
columns.hierarchica level specified by this annotation.
ldisplay.expandTo Scope: #VIEW
Type: ElementRef
Analytics.settings. This annotation specifies are shown to the right or the left of the details. If nothing is
columns.totalsLocat specified the default is RIGHT without display hierarchy and LEFT with display hierarchy.
ions Scope: #VIEW
ENUM Description
RIGHT Show results on columns right of the details
LEFT Show results on columns left of the details
Analytics.settings. The analytical manager usually displays the initial value of a dimension as a #. If the
displayOriginalInit annotation is set to true, the external value of the initial value will be shown. Showing the #
is the default if the annotation is not set.
ialValue
It can be set in the header of a dimension or text view, or it can be set for an element in a
cube view without foreign key or text association.
It can only be set for dimensions where the initial value is not a space.
Scope: #VIEW
Type: Boolean
Analytics.settings. If text should be displayed but a text is missing for a single key, then the display key is
initialValueForMiss displayed for this single key.
ingText
If the text should remain empty, this annotation has to be set as a header annotation:
•
• With Analytics.dataCategory: #DIMENSION if the dimension provides the
text.
Scope: #VIEW
Type: Boolean

Annotation Meaning
Analytics.settings. If InfoProviders store large amounts of data, certain queries can retrieve large result sets.
maxProcessingEffort The maxProcessingEffort is the maximum effort expected by analytic manager for process-
ing the data it retrieves.
When the limit is reached, the analytic manager returns an error message and the user can
set filters or remove dimensions from the axis in order to get smaller result sets.
Scope: #VIEW
ENUM Description
LOW
MEDIUM
HIGH The default is #HIGH.
UNLIMITED There is no limit when reading data but processing might

crash memory overflow error or other similar issues may
occur.
Analytics.settings. The Analytic manager is able to map som OLAP features as an SAP HANA calcula-
olapPushdown tion scenario. This means some calculations are calculated not calculated in the ABAP
server but rather in HANA, this is faster in most cases. This is what we call "push-
down". Unfortunately, the performance is not improved by the pushdown in all cases.
By default, all queries using certain features will be processed with pushdown. With
Analytics.settings.olapPushdown: Off set for a cube view, you can switch
off the pushdown for all queries of that cube. If the annotation is set on query level, then the
setting of the cube is overruled. This means with OFF you can switch off the pushdown for
a single query. With MAX, pushdown is performed off if pushdown has been switched off in
the cube.
Scope: #VIEW
Type:String of ENUM
ENUM Description
OFF The analytic manager doesn't use the pushdown mecha-

nism and accesses cube data via SQL (corresponds to
TREXOPS = 0).
MAX The analytic manager performs the pushdown if relevant

features are used in the query. (corresponds to TREXOPS =
9).

Annotation Meaning
Analytics.settings. This annotation shows all dimensions that are on the rows in a universal display hierarchy.
rows.hierarchicalDi Scope: #VIEW

splay.active
Type: Boolean
Analytics.settings. With the annotation, the hierarchy will be expanded to the level specified if the universal
rows.hierarchicalDi display hierarchy is switched to rows.
spaly.expandTo Scope: #VIEW
Type: ElementRef
Analytics.settings. This annotation specifies if the totals appear on the rows above the details or below the
rows.totalsLocation details.
s If nothing is specified the default setting is as follows:
• If there is no hierarchy, the totals are displayed below the details.

• If there is a display hierarchy, the totals are on top and the parents are above the
children.
Scope: #VIEW
ENUM Description
BOTTOM The results are at the bottom below the details.
TOP The results are at the top.
Analytics.settings. If this annotation is set in the header of the CDS query view, some BI tools offer
runtimeExtenbsibili the possibility to extend the runtime view with further dimensions or measures at run-
time. This is not possible if this annotation is not set. If not all dimensions or meas-
ty.allowed
ures of the cube view should be used, these can be excluded with the annotation
Analytics.excludeFromRuntimeExtensibility.
Scope: #VIEW
Type: Boolean

Annotation Meaning
Analytics.settings. This annotation can be used in views of the type Analytics.dataCategory:

valueHelp.suppressI #DIMENSION and in views of type ObjectModel.dataCategory: #TEXT.
nitialValue If a text association for the representative key field exists, the annotation of the dimension is
relevant and the annotation of the text view will be ignored. If this annotation is set, an extra
line for the initial value will not be added when value help is processed. If a record exists
with initial key, it wall always be shown independent of the annotation.
Scope #VIEW
Type: Boolean
Analytics.settings. You can specify whether rows or columns with cells that contain zeros as values are to be
zeroValues.handling displayed.
Scope: #VIEW
ENUM Description
SHOW You can specify that zeros are to be displayed (no zero sup-
pression takes place). The default is #SHOW.
HIDE If you want to suppress zeros, there are two options avail-
able: #HIDE and #HIDE_IF_ALL. For queries that have
characteristics in the rows and key figures in the columns
(or the other way around, with key figures in the rows and
characteristics in the columns), the effect of the settings
is identical. The two settings only differ in how they affect
queries that have characteristics in the rows and columns
(cross-classified table). If you use zero suppression with the
#HIDE value, the system checks whether there are zero val-
ues in the results area. If there are zero values in the results
area, the corresponding row or column is hidden.

Annotation Meaning
HIDE_IF_ALL For queries that have characteristics in the rows and key
figures in the columns (or the other way around, with key
figures in the rows and characteristics in the columns),
the effect of the value is identical to #HIDE. If your query
has characteristics in the rows and columns however (cross-
classified table), and you use zero suppression with the
HIDE_IF_ALL value, the system hides all rows or columns
that contain zero values.
 Note
If a detail row is not equal to zero (in a hierarchy for

example), all superordinate rows are displayed, even if
they contain zeros. As a result, the system ensures that
the business context of the query is retained for the end
user, even if the value HIDE_IF_ALL is set. Examples
are plan-actual-sign or planVersion.
Analytics.settings. You can specify whether rows or columns that contain zeros as values are to be hidden.
zeroValues.hideOnAx Scope: #VIEW

is
ENUM Description
ROWS Only rows that contain zeros as values are to be hidden.
COLUMNS Only columns that contain zeros as values are to be hidden.
ROWS_COLUMNS The default is ROWS_COLUMNS. Rows and columns that

contain zeros as values are to be hidden.
Analytics.technical Names in the analytical model are derived from the annotation
Name AbapCatalog.sqlViewName for CDS views or from the CDS name for view entities.
If a view entity provides the annotation Analytics.technicalName, the name in the
analytical model is derived from this. It should only be used when migrating a CDS view to a
CDS view entity.
Scope: #VIEW, #ELEMENT
Type: String

Annotation Meaning
Analytics.variableC The consistency of the variable input can be checked.
heck.implementedBy Scope: #VIEW
Type: String - Name of an ABAP class that implements

IF_RSRTS_CDS_VARIABLE_CHECK. The interface method is called when a variable
screen is confirmed at runtime of the analytics query.
 Note
This is only interpreted in the context of an analytical query.
Examples
Example 1
Example for replication-enabled master data.
 Sample Code
@EndUserText.label: 'EPM Demo: Employee'

@Analytics:{ dataCategory: #DIMENSION , dataExtraction.enabled: true }
@ObjectModel.representativeKey: 'EmployeeUUID'
@AbapCatalog.sqlViewName: 'SEPM_IEMPLOYEE'
define view SEPM_I_Employee as
select from snwd_employees
association [0..1] to SEPM_I_Company as _Company
on $projection.CompanyUUID = _Company.CompanyUUID
...
{
key snwd_employees.node_key as EmployeeUUID,
@ObjectModel.foreignKey.association: '_Company'
snwd_employees.parent_key as CompanyUUID,

...}
Example 2
Example for transactional data (fact).
 Sample Code
@EndUserText.label: 'EPM Demo: Sales Order Item with Addtl. Data (private
view)'

@Analytics.dataCategory: #CUBE
@AbapCatalog.sqlViewName: 'SEPM_PSOIC'
define view SEPM_P_SalesOrderItemCube
as select from SEPM_I_SalesOrderItem
association [0..1] to SEPM_I_SalesOrder_E as _SalesOrder_E
on $projection.salesorder = _SalesOrder_E.SalesOrder
...

{
@ObjectModel.foreignKey.association: '_SalesOrder_E'
key _SalesOrder.SalesOrder,
_SalesOrder_E,

...}
Example 3
Example for defining a list of tables that should be logged for delta data extraction.
 Sample Code
@Analytics: {

dataCategory: #FACT,
dataExtraction: {
enabled: true,
delta.changeDataCapture.mapping:
[ { table: 'rsodpcdcunittab2', role: #MAIN, viewElement:
['view_key1', 'view_key2'], tableElement: ['tab_key1', 'tab_key2'] },
{ table: 'rsodpcdcunittab1', role: #LEFT_OUTER_TO_ONE_JOIN,
viewElement: ['view_key3'], tableElement: ['tab_key1'] } ]

} }
9.5 AnalyticsDetails Annotations
 Home Enable application developers to specify the default multidimensional layout of the query, the
sequence of variables in UI consumption, and the specific aggregation and planning behavior of the data.
All these annotations can only be used in views with @Analytics.query : true.
@Scope:[#ELEMENT]

annotation AnalyticsDetails
{
query
{
formula : String(1298);
axis : String(20) enum { FREE; ROWS; COLUMNS; };
totals: String(20) enum { HIDE; SHOW; };
scaling : Integer;
decimals : Integer;
display : String(20) enum { KEY; TEXT; TEXT_KEY; KEY_TEXT; };
sortDirection : String(20) enum { ASC; DESC; };
displayHierarchy : String(20) enum { OFF; ON; FILTER; FILTER_ONLY; };
hierarchyInitialLevel : Integer;
hierarchyBinding : array of
{
type : String(12) enum { ELEMENT; PARAMETER; CONSTANT; USER_INPUT;
SYSTEM_FIELD; };
value : String(512);
variableSequence : Integer;

};
hierarchySettings
{
hidePostedNodesValues : Boolean default true;
hideNodeWithOneChild : Boolean default true;
childNodePosition : String(10) enum { BELOW ; ABOVE; };
};
elementHierarchy
{
parent : ElementRef;
initiallyCollapsed : Boolean default true;
};
@Scope:[#ELEMENT, #PARAMETER]
resultValuesSource : String(10) enum { CUBE; DIMENSION; };
resultValueHelpSource : String(10) enum { QUERY; DIMENSION; };
reverseSign: Boolean default true;
onCharacteristicStructure: Boolean default true;

collisionHandling:
{ formula : String( 20) enum { DEFAULT; THIS; CONCURRENT; };
decimals : String( 20) enum { DEFAULT; THIS; CONCURRENT; };
scaling : String( 20) enum { DEFAULT; THIS; CONCURRENT; };
semanticObject : String( 20) enum { DEFAULT; THIS; CONCURRENT; };
};
ignoreFurtherFilter:
{ forElement : array of ElementRef;
forAllElements : Boolean; }
};
exceptionAggregationSteps : array of
{
exceptionAggregationBehavior : String(14) enum
{
SUM;
MIN;
MAX;
COUNT;
COUNT_DISTINCT;
AVG;
STD;
FIRST;
LAST;
NHA;
};
exceptionAggregationElements : array of String(30);
};
planning
{
disaggregation : String enum { NONE; TOTAL; DIFFERENCE; };
distribution : String enum { EQUAL; PROPORTIONAL; PROPORTIONAL_REF; };
distributionReference : elementRef;
};
};
@Scope: [#PARAMETER]
variable {
usageType : String(20) enum { PARAMETER; FILTER; FORMULA; };
referenceElement : ElementRef;
mandatory : Boolean default true;
defaultValue : String(1024);
defaultValueHigh : String(1024);
defaultHierarchyNode : {
nodeType : String( 30 );
node : array of {
element : String( 30 );

};
};
defaultRanges : array of {
sign : String(1) enum { I; E; };
option : String(2) enum { EQ; BT; CP; LE; GE; NE; NB; NP; GT; LT; };
low : String(1024);
high : String(1024);
};
selectionType : String(20) enum { SINGLE; INTERVAL; RANGE;
HIERARCHY_NODE; };
multipleSelections : Boolean default true;
hierarchyBinding : array of {
type : String(20) enum { PARAMETER; CONSTANT; SYSTEM_FIELD;};
value : String(512) ;
};
};

};

Usage
Annotation Meaning
AnalyticsDetails.ex Usually, the default aggregation determines how measures are aggregated in analytics.
ceptionAggregationS
 Caution
teps.exceptionAggre
gationBehavior
In some cases different aggregation behavior is needed for a special element of the entity
(dimension of a cube). The default aggregation behavior can't be defined in the query. It
needs to be defined on the cube layer.
 Note
Example: A measure "Inventory" can be summed up for the different plants and other
dimensions, but not for time – according to time the last or average value might be
relevant.
Exception aggregation is optional and is used to define different (to the de-
fault aggregation) aggregation behavior for specified elements. In general, there
can be multiple elements in which a measure has to be aggregated differ-
ently. Therefore, a list of ExceptionAggregationSteps can be assigned.
ExceptionAggregationBehavior defines the aggregation behavior.
 Note
Example: In the query there's a measure that should show the number of
customers with positive sales - where sales is a measure of the underlying
CUBE view with default aggregation SUM. When the sales measure is now
used in a query with exceptionAggregationBehavior: COUNT and
exceptionAggregationElements : Customer, the sales must first be ag-
gregated (SUM) at customer level, and then COUNT has to be performed. If there is a
value for sales, this means that the sales is replaced by 1 (otherwise it is set to 0). This
number can be summed up again.
Scope: #ELEMENT
Evaluation Runtime (Engine): The (logical) order in which the Analytic manager performs
the aggregation is as follows: Firstly, the DefaultAggregation is performed. This intermediate
result is still grouped by all elements in the list of ExceptionAggregationSteps. The
result is then aggregated by the exception aggregation in the order of StepNumber.
The first remark holds even if the default aggregation is FORMULA. This means that the
calculation is performed when the result is still grouped by the exception aggregation ele-
ments. After the formula has been calculated, the result is aggregated according to the list
of ExceptionAggregationSteps. This means that the aggregation level to be used
for calculation can be defined precisely.
ENUM Description

Annotation Meaning
SUM Sum
MIN Minimum
MAX Maximum
NHA "No Hierarchy Aggregation" - the value of a hierarchy's no-

des isn't the aggregate of its children
COUNT Counter
AVG Average
STD Standard deviation
FIRST First
LAST Last
AnalyticsDetails.ex The elements that should be aggregated in this step. These elements must represent di-
ceptionAggregationS mensions. For more information, see
teps.exceptionAggre AnalyticsDetails.exceptionAggregationSteps.exceptionAggregati
gationElements onBehavior.
Scope: #ELEMENT
Type: String - list of elements representing dimension
AnalyticsDetails.pl This annotation allows you to define the disaggregation behavior. This annotation is only
anning.disaggregati available for elements with AnalyticsDetails.planning.enabled.
on If a measure is specified with this annotation, it is input-ready in the analytic query. It

enables the user to make manual entries for aggregated values. These values must be
disaggregated on all the data records that contribute to the aggregated value of the cell.
Scope: #ELEMENT
ENUM Description
NONE No Disaggregation (default)
TOTAL Disaggregates the value entered.
DIFFERENCE Disaggregates the difference to value entered.

Annotation Meaning
AnalyticsDetails.pl If disaggregation is chosen, you can choose how the value is distributed during disaggrega-
anning.distribution tion with this annotation. This annotation will be ignored if CDS view or the corresponding
element isn't enabled for planning.
Scope: #ELEMENT
ENUM Description
EQUAL Equal distribution (default)
PROPORTIONAL Proportional to the current value
PROPORTIONAL_REF Proportional to the current value of a sibling member in the

selection list, which needs to be specified via the
AnalyticsDetails.planning.distributionRe
ference annotation.
AnalyticsDetails.pl You can specify a sibling member in the selection list for reference with this anno-
anning.distribution tation if disaggregation and AnalyticsDetails.planning.distribution :
Reference #PROPORTIONAL_REF are chosen.
This annotation will be ignored if CDS view or the corresponding element isn't enabled for
planning.
Scope: #ELEMENT
Type: ElementRef - Name of sibling member for reference
AnalyticsDetails.pl Individual members in the selection list (no calculated elements) need to be annotated
anning.enabled for enabling planning. The list can only be used in input-enabled analytic queries. This
means that the views have to be annotated with Analytics.query: true and
Analytics.planning.enabled: true. If a measure is specified with this annota-
tion, it is input-ready in the analytic query.
Scope: #ELEMENT
Type: Boolean - The member in the selection list is enabled for planning. This is the default
setting (true).

Annotation Meaning
AnalyticsDetails.qu For a tabular display of the query result, the elements can be positioned on multiple axes
ery.axis for the default layout. The elements can be directly annotated with their axis. Measures
(elements that can be aggregated (@Aggregation.default)) all need to be on the same axis.
The annotation of the first measure will therefore be used for all measures of the query. If no
AnalyticsDetails.query.axis is found, the system positions the measures on the
columns.
The default value for elements that are not measures is the free axis. Note that elements in
the projection list, which belong to the same field in the query, for example, text field, will be
grouped together.
Scope: #ELEMENT
Evaluation Runtime (Engine): Analytic manager: If the BI client doesn't specify which
elements are on which axis, the layout is derived by this annotation.
ENUM Description
FREE Default value for elements other than measures. Dimension

isn't displayed in the initial grid, but can be added to rows or
columns by a user at runtime.
ROWS
COLUMNS Default value for measures.
AnalyticsDetails.qu If a query has a measure and a characteristic structure, conflicts can occur. For instance,
ery.collisionHandli both structures might contain a member with a formula. Then it has to be specified which
ng property should be the taken for the resulting cell: the property from the measure structure
member or the property from the characteristic structure member. For instance, if both
members are a formula it has to be specified which formula should be calculated for the
resulting cell. If nothing is specified, the property of the measure structure will be taken.
 Note
The query.collisionHandling annotation must be used with special elements. query.colli-

sionHandling.decimals, -.formula, -.scaling, or -.semanticObject.
AnalyticsDetails.qu Determines which setting for decimals (query.decimals) should be set for the resulting cell.
ery.collisionHandli This annotation is only relevant for measures. For other elements it will be ignored.
ng.decimals
Scope: #ELEMENT
ENUM Description
DEFAULT Use the default.

Annotation Meaning
THIS Use this property for all members of the orthogonal struc-
ture when combined with the member.
CONCURRENT Use this property for all members of the orthogonal struc-
AnalyticsDetails.qu Determines which formula should be calculated in the resulting cell.

ery.collisionHandli
Scope: #ELEMENT
ng.formula
ENUM Description
AnalyticsDetails.qu Determines which setting for scaling (query.scaling) should be set for the resulting cell.
ery.collisionHandli Scope: #ELEMENT
ng.scaling
ENUM Description
ture when combining with the member.
Determines which semantic object (Consumption.semanticObject) should be assigned to

AnalyticsDetails.qu
the resulting cell.
ery.collisionHandli
Scope: #ELEMENT
ng.semanticObject
ENUM Description

Annotation Meaning
AnalyticsDetails.qu For fields that represent measures, restricted measures, and calculated elements, you can
ery.decimals set the number of decimals to be used. This element is only relevant for measures. For other
elements it will be ignored.
Scope: #ELEMENT
Type: Integer from 0 to 9.
AnalyticsDetails.qu This annotation defines if a dimension should be displayed as (external) key or text in the
ery.display default layout. If nothing is specified, the default is taken from the Analytical Provider. If it is
not specified in the Analytical Provider, the default is #TEXT if the dimension supports text.
Otherwise, the default is #KEY.
Scope: #ELEMENT
Evaluation Runtime (Engine): Analytic manager: This annotation is relevant for dimen-
sions in analytic queries and in cube views.
ENUM Description
KEY The key will be displayed.
TEXT The text will be displayed.
TEXT_KEY Text and key will be displayed.
KEY_TEXT Key and text will be displayed.
AnalyticsDetails.qu This annotation allows you to specify the display hierarchy attribute for the element. It isn't
ery.displayHierarch possible for measures. The query result is shown in a hierarch for the specified element.
y Scope: #ELEMENT
ENUM Description
OFF No display hierarchy.
ON With display hierarchy. The hierar-

chy used must be specified by
AnalyticsDetails.query.hierarchyBinding.
Only if there doesn't exist a hierarchy directory, the binding
isn't necessary.
FILTER The display hierarchy is the same one defined on the filter
for this element. In this case, a hierarchy filter needs to be
defined on the same element. The hierarchy binding is taken
from the filter.

Annotation Meaning
FILTER_ONLY This is similar to FILTER but display hierarchy can't be

changed at runtime.
AnalyticsDetails.qu A hierarchical display of structure members can be displayed with this annotation. The
ery.elementHierarch hierarchy can be defined within the measure structure and the characteristic structure.
y This annotation must be used with an element, -.elementHierarchy.inilliallyCollapsed or
-.elementHierarchy.parent.
AnalyticsDetails.qu If true, the hierarchy node represented by the annotated entry will be initially col-
ery.elementHierarch lapsed (only applicable if the annotated entry has children. The elements of the meas-
ure structure and characteristic structure can be displayed in a hierarchical way. With
y.initiallyCollapse
AnalyticsDeltails.query.elementHierarch.parent an element becomes
d
the child of another element.
Scope:#ELEMENT
Type: Boolean
AnalyticsDetails.qu Elements of a structure (measure or characteristic) will be shown as a flat list in the key fig-
ery.elementHierarch ure structure of the Analytic Query. To achieve a hierarchical display, select list entries can
y.parent be annotated with @AnalyticsDetails.query.elementHierarchy.parent

and will appear hierarchically below the specified parent entry.
If the element belongs to the measure structure, the parent must also belong to the meas-
ure structure. If it belongs to the characteristic structure, the parent element must belong to
the characteristic structure.
Scope:#ELEMENT
Type: ElementRef. This is the alias of the select list entry serving as parent for the annotated
entry.

Annotation Meaning
AnalyticsDetails.qu This annotation allows you to specify the formula expression, which can't be expressed as
ery.formula an SQL formula (operands required from the element list of the view). Only numerical values
(measures) can be used as operands. This annotation will be interpreted as a formula.
Scope: #ELEMENT
Type: String
This expression can contain the following:
• Cube measures
• Arithmetic expressions
• Functions NDIV0 and NODIM
• CASE expressions with a maximum of one THEN clause (will be translated into BW IF
operator)
• WHEN clause can contain conditional or Boolean expressions of measures
• ELSE clause is optional (default to ELSE 0)
AnalyticsDetails.qu With this annotation, an element of a structure can be hidden but the end user can display
ery.hidden it at runtime. If Consumption.hidden is used the element is hidden at all times and
cannot be seen at runtime.
Scope: #ELEMENT
Type: Boolean
AnalyticsDetails.qu General example for AnalyticsDetails.hierarchyBinding type annotations.
ery.hierarchyBindin  Example
g
AnalyticsDetails.query.hierarchBinding: {type : #PARAMETER,
value 'parameter_name'}. In this case, parameter_name specifies the name of
a parameter.

Annotation Meaning
AnalyticsDetails.qu The AnalyticsDetails.query.hierarchyBinding annotations allow you to

ery.hierarchyBindin specify a special hierarchy for an element with a display hierarchy. One tuple has to be
g.type specified for each key field of the hierarchy directory view. The first entry is supplied to the
first key field of the hierarchy directory, the second entry to the second key field, and so on.
If there is no hierarchy directory, the hierarchy binding can be omitted.
AnalyticsDetails.query.hierarchyBinding.type determines how the

key element is filled (by a constant, a parameter, a filtered ele-
ment or by a user input field). The type specifies the type of
AnalyticsDetails.query.hierarchyBinding.value.
Scope: #ELEMENT
ENUM 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 run-

time 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
AnalyticsDetails.query.variableSequence.
AnalyticsDetails.qu This annotation contains, depending on the type, a literal value, the parameter name
ery.hierarchyBindin (without : $parameter), the element name and an identifier for the user input field,
g.value respectively. In case of type #SYSTEM_FIELD, the allowed values are those of @Environ-
ment.systemField for system field.
Scope: #ELEMENT
Type: String

Annotation Meaning
AnalyticsDetails.qu This annotation allows you to specify the order of parameters and variables on the variable
ery.hierarchyBindin input UIs.
g.variableSequence In case filters or parameters are not annotated they are displayed after the annotated ones
in the order they appear in the CDS document.
Scope: #ELEMENT
Type: Integer - This number defines the position of the variable generated for the user input
field.
AnalyticsDetails.qu This annotation defines which hierarchy level will be displayed initially.
ery.hierarchyInitia Scope: #ELEMENT

lLevel
Type: Integer - Hierarchy level with that number will be displayed initially.
AnalyticsDetails.qu Defines whether the nodes should expand to the bottom or the top.
ery.hierarchySettin Scope: #ELEMENT

gs.childNodePositio
n
field.
ENUM Description
BELOW (Default) The children are shown below the parent if the
dimension is on the rows. If the dimension is on the columns,
the children will be shown on the left.
ABOVE The children are shown above the parent (on rows) or to the
left (on columns).
AnalyticsDetails.qu For some hierarchies, the hierarchy nodes can have posted values on their own (and not just
ery.hierarchySettin represent the aggregation over all its child nodes) which are displayed as separate rows in
the report. Using this annotation the display of the posted values can be suppressed.
gs.hidePostedNodesV
alues Scope: #ELEMENT
Type: Boolean
AnalyticsDetails.qu Node 1 has children Node 11 and Node 12. Node 11 has only one child, Node 111. Node 111 has
ery.hierarchySettin children Node A and Node B. Then Node 111 will be presented as child of Node 1 and Node 11
is not visible.
gs.hideNodeWithOneC
hild

Annotation Meaning
AnalyticsDetails.qu The feature "constant selection" of the analytic engine can be modeled by using the
ery.ignoreFurtherFi annotations AnalyticsDetails.query.ignoreFurtherFilter.forElement,
lter which expects a list of elements, names, and the annotation, and
AnalyticsDetails.query.ignoreFurtherFilter.forAllElements. With
variant .forAllElements, filters for all dimensions are ignored. With var-
iant,forElement, only the filters for the dimension in that list are ignored.
lter.forElementp which expects a list of elements, names, and the annotation, and
variant,forElement, only the filters for the dimension in that list are ignored.
Scope: #ELEMENT
Type: Boolean
lter.forAllElements which expects a list of elements, names, and the annotation, and
variant .forAllElements, filters for all dimensions are ignored.
Scope: #ELEMENT
AnalyticsDetails.qu All measures, restricted measures, and calculated elements will be shown in the measure
ery.onCharacteristi structure. Further restricted elements can be assigned to a second structure (characteristic
cStructure structure). If a formula is used with all operands belonging to the characteristic structure,
the formula must be integrated into the characteristic structure. Pattern for a restricted
element : CASE WHEN...THEN 1 END AS.…
Scope: #ELEMENT
Type: Boolean

Annotation Meaning
AnalyticsDetails.qu This annotation specifies which values of a dimension should be shown in a value help at
ery.resultValueHelp query runtime for selecting a dynamic filter. This is only supported for elements.
Source
Scope: #ELEMENT, #PARAMETER
Evaluation Runtime (Engine): Specifies if the dimension should only show the values
selected from the Analytical Provider or if it should be filled up by master data of the
dimension view.
ENUM Description
QUERY Before data is selected from the dimension view the query
is performed with the dimension in drill down and all other
filters in place. The result is used as an additional filter when
selecting data from the master data view.
This is the default if the annotation is not set.
DIMENSION The value help is showing all data from the master data view.
AnalyticsDetails.qu This annotation influences the list of values, which should be taken into account for a
ery.resultValuesSou specific dimension. This is only supported for elements.
rce Scope: #ELEMENT, #PARAMETER
ENUM Description
CUBE All values available in the view of the from clause.
DIMENSION All values available in dimension.
AnalyticsDetails.qu The sign of a measure will be flipped (positive will become negative and negative numbers
ery.reverseSign will become positive). It is only a display feature. Calculations with the measure will be
performed with the "real" sign. This is only supported for elements.
Type: Boolean
Evaluation Runtime (Engine):

Annotation Meaning
AnalyticsDetails.qu For measures, restricted measures, and calculated elements, you can set the scaling factor
ery.scaling to be used. This annotation is only relevant for measures. For other elements it will be
ignored. Numbers will be scaled by a factor of 10*n.
Scope: #ELEMENT
Type: Integer - number from 0 to 9.
Evaluation Runtime (Engine): This annotation is only relevant for measures. For other
elements it will be ignored.
AnalyticsDetails.qu If nothing is specified, the rows are sorted ascending by first dimension, second dimension,
ery.sortDirection and so on. The same is true for dimension on columns. With this annotation, the sort
direction can be set #ASC (ascending) and #DESC (descending).
Scope: #ELEMENT
ENUM Description
ASC Sort ascending (default)
DESC Sort descending
AnalyticsDetails.qu For dimensions, you can set the behavior for totals. Theses annotations will be ignored for
ery.totals measures.
Scope: #ELEMENT
ENUM Description
HIDE Totals or subtotals are not added to the result set for this
element.
SHOW In addition to the details, the subtotals are added to the

result set for this element.
AnalyticDetails.var In general, a CDS parameter represents a single value, which has to be determined at
iable runtime either by user input or derivation. But in Analytics, this concept is too strict. There
is the need for multiple values, for intervals, for hierarchy-nodes. In some cases the input
should be optional. This can be achieved with the AnalyticsDetails.variable
annotations. If these annotations are used, the ODATA.publish: true is not supported.

Annotation Meaning
AnalyticsDetails.qu If user input is necessary for the parameter, the sequence of all fields for user input at
ery.variableSequenc runtime can be specified with this annotation. UIs will create user prompts for parameters
that require a user input or elements with filters (consumption.filter). This annotation can
e
be used to specify the sequence of user prompts at runtime. If filters or parameters are not
annotated, they are displayed after the annotated ones - in the order they appear in the CDS
document. The sequence is calculated according to the order of all variables.
Type: Integer - The order of parameters and variables. Integer values may contain gaps.
AnalyticsDetails.va These annotations allow one to specify a default value for a hierarchy node filter. It has to be
riable.defaultHiera used in combination with selectionType #HIERARCHY_NODE. A hierarchy node is seen as

a list of elements (structured type), which are the semantic elements in the corresponding
rchyNode
view with ObjectMOdel.dataCategory : #Hierarchy.
AnalyticsDetails.va The .variable.defaultHierarchyNode annotations allow one to specify a

riable.defaultHiera default value for a hierarch node filter. It must be used in combination with
rchyNode.node.eleme AnalytictsDetails.variable.selectionType #HIERARCHY_NODE. A hier-

nt arch node is seen as a list of elements (structure type) which are the semantic elements
in the corresponding view with ObjectModel.dataCategory: #HIERARCHY. With
sub annotation node, each part can be set to a constant separately. Element is reference ing
the element in the hierarchy view. If the value of the field NodeType, is initial, then the value
represents a leaf.
With the node sub annotations, each part can be set to a constant separately.
The annotation
AnalyticsDetails.variable.defaultHierarch.node.element is referring
to the element in the hierarch view.
Scope: #PARAMETER
Type: String
AnalyticsDetails.va The AnalyticsDetails.variable.defaultHierarchyNode annotations allow

riable.defaultHiera one to specify a default value for a hierarch node filter. It must be used in combination
rchyNode.node.value with AnalytictsDetails.variable.selectionType #HIERARCHY_NODE. A

hierarch node is seen as a list of elements (structure type) which are the semantic elements
in the corresponding view with ObjectModel.dataCategory: #HIERARCHY.
Scope: #PARAMETER
Type: String

Annotation Meaning

rchyNode.nodeType AnalytictsDetails.variable.selectionType #HIERARCHY_NODE. A hier-

arch node is seen as a list of elements (structure type) which are the semantic elements in
the corresponding view with ObjectModel.dataCategory: #HIERARCHY.
If the value of the field NodeType is initial, the value represents a leaf.
Scope: #PARAMETER
Type: String
AnalyticsDetails.va This annotation specifies the default for a variable with selection type #RANGE. The logic
riable.defaultRange follows the ABAP-range logic with the subfield high.
s.high Scope: #PARAMETER
Type: String
riable.defaultRange follows the ABAP-range logic with the subfield low.
s.low Scope: #PARAMETER
Type: String
riable.defutaltRang follows the ABAP-range logic with the subfield option.
hes.option Scope: #PARAMETER
ENUM Description
EQ
BT
CP
LE
GE

Annotation Meaning
NE
NB
NP
GT
LT
riable.defaultRange follows the ABAP-range logic with the subfield sign.
s.sign This annotation specifies the default for a variable with selection type #RANGE. The logic
follows the ABAP-range logic with the subfield sign.
Scope: #PARAMETER
ENUM Description
AnalyticsDetails.va This annotation specifies a default value. If the variable is input enabled, the variable is
riable.defaultValue prefilled with the default value. If the variable is hidden, the variable is processed with the
default value. The resulting type of the "default expression" must comply with the data type
of the associated element.
Scope: #PARAMETER
Type: String
AnalyticsDetails.va This annotation is used in combination with AnalyticsDetails.defaultValue

riable.defaultValue to specify a default for the upper bound of an interval.
High AnalyticsDetails.devaultValue specifies the lower boundary. It is only useful

for variables of the selection type #INTERVAL or #RANGE.
Scope: #PARAMETER
Type: String

Annotation Meaning
AnalyticsDetails.va This annotation determines how the key element is filled by either a constant, a parameter,
riable.hierarchyBin a (filtered) element, a user input field, or a system field. Allowed values: #CONSTANT,
#PARAMETER, #SYSTEM_FIELD.
ding.type
Scope: #PARAMETER
ENUM Description
PARAMETER
CONSTANT
SYSTEM_FIELD Allowed values are for those of @Environment.systemField

for system field.
AnalyticsDetails.va This annotation contains, depending on the type, a literal value, the parameter name (with-
riable.hierarchyBin out : or $parameter), the element name, the identifier for the user input field, and system
field. Allowed values are those of @Environment.systemField for system field. In the case of
ding.value
type '
Scope: # PARAMETER
Type: String
AnalyticsDetails.va This annotation shows the position of the variable generated for the user input field. The
riable.hierarchyBin sequence is calculated according to the order of all variables.
ding.variableSequen
 Note
ce
This annotation is only relevant for type: #USER_INPUT.
Scope: # PARAMETER
Type: Integer

Annotation Meaning
AnalyticsDetails.va If this is set to true, the system enforces that the variable contains a value at runtime. If it is
riable.mandatory set to false, the variable is optional and the query might be executed without a value set.
 Note
If the annotation is not set, the variable is mandatory. This behavior is different from
other boolean annotations.
Scope: # PARAMETER
Type: Boolean
AnalyticsDetails.va This annotation is used to indicate that several lines (rows) can be entered on the filter input
riable.multipleSele (selection UIs combined with the selectionType you get.
ctions
Scope: # PARAMETER
Type: Boolean
AnalyticsDetails.va This annotation refers to an element in the result structure or in the underlying data source
riable.referenceEle to which the variable refers. In the case of a filter variable, this annotation is mandatory and
ment must contain the element that represents the dimension. In general, it restricts the usage in
expressions, serves as a reference for default values, and may result in a default value help.
Scope: #PARAMETER
Type: String
Evaluation Runtime: Analytic manager
AnalyticsDetails.va This annotation determines how values can be entered.

riable.selectionTyp
Scope: #PARAMETER
e
ENUM Description
SINGLE Single Value
INTERVAL Interval is a special case of a Range with "sign = including"

and "option = BT".
RANGE A Range is a complete (ABAP like) SELECT option including

sign (including/excluding) and an operator such as EQ, CP,
or BT.
HIERARCHY_NODE Hierarchy node means everything under the node.

Annotation Meaning
AnaylticsDetails.va This annotation is a classification corresponding to the terminology Parameter Variable,
riable.usageType Filter Variable, and Formula Variable. The usage of the parameter in the view definition has
to match the intended usage expressed with this annotation. Whether the parameter is used
according to the usageType is not verified by the analytical engine.
Scope: #PARAMETER
ENUM Description
PARAMETER The variable is used for a parameter of the underlaying data

source. For example, the value is pushed down at runtime via
SQL to the corresponding data source.
FILTER The variable is used in filters for the dimension represented

by the element annotated as referenceElement. Filters are
typically global filters in the case of CDS: where clause or
element restrictions in Restricted Measures in the case of
CDS: sub expression when expressions.
FORMULA The variable is used as a placeholder in expressions defining

calculated measures, for example virtual elements with for-
mula aggregation referring to other elements with measure
semantics.
Examples
Example 1
Calculated Elements
 Sample Code

@Analytics.query : true
define view fincancial as select from sales
{
@AnalyticsDetails.query.axis : #ROWS
product,
@AnalyticsDetails.query.axis : #COLUMNS
@AnalyticsDetails.query.formula : 'revenue - cost'
1 as absolute_margin,
@AnalyticsDetails.query.formula : 'NDIV0($projection.absolute_margin /
revenue ) * 100'
1 as relative_margin,
@AnalyticsDetails.query.formula : 'CASE WHEN $projection.relative_margin >

20 THEN revenue ELSE 0 END'
1 as revenue_for_margin_gt_20
}


Example 2
Display hierarchy selection: Specify the hierarchy directly.
 Sample Code

define view costcenter_reporting
with parameters
cost_center_hier_param : String
as select from costcenters
{
...
@AnalyticsDetails.query : {
displayHierarchy: #ON,
hierarchyInitialLevel: 3, // three levels of the hierarchy will be

opened at start
hierarchySettings{hidePostedNodesValues: true }, // don't show posted
node values
hierarchyBinding :
[ { type : #CONSTANT, value : 'CONTR_AREA_10' },
{ type : #PARAMETER, value : 'cost_center_hier_param' }
]
}
costcenter, // hierarchy node filter
costs,
...
}

Example 3
Use of $session variables, especially $session.system_date.
The system supports variables like $session.system_date for different use cases:
• In cube parameters
 Sample Code

define view …
as select from zCostCenter_Flt( P_KeyDate: $session.system_date )

• In queries on time-dependent master data in where clauses
 Sample Code

} where
DateTo >= $session.system_date and
DateFrom <= $session.system_date

• In paths to time-dependent attributes or texts
 Sample Code

_CostCenter[1: DateTo >= $session.system_date and DateFrom <=
$session.system_date]._Text[1: Language = $parameters.P_Language].Text as
CostCenterText,


• In restricted key figures
 Sample Code

case when PostingDate = $session.system_date then ammount as currentAmmount
9.6 AnalyticsDetails Annotations
 Cloud Enable application developers to specify the default multidimensional layout of the query, the
sequence of variables in UI consumption, and the specific aggregation and planning behavior of the data.
All these annotations can only be used in views with @Analytics.query : true.
@Scope:[#ELEMENT]

Annotation AnalyticsDetails
{
query
{
formula : String(1298);
axis : String(20) enum { FREE; ROWS; COLUMNS; };
totals: String(20) enum { HIDE; SHOW; };
scaling : Integer;
decimals : Integer;
display : String(20) enum { KEY; TEXT; TEXT_KEY; KEY_TEXT; };
sortDirection : String(20) enum { ASC; DESC; };
displayHierarchy : String(20) enum { OFF; ON; FILTER; FILTER_ONLY; };
hierarchyInitialLevel : Integer;
hierarchyBinding : array of
{
type : String(12) enum { ELEMENT; PARAMETER; CONSTANT; USER_INPUT;
SYSTEM_FIELD; };
};
hierarchySettings
{
hidePostedNodesValues : Boolean default true;
hideNodeWithOneChild : Boolean default true;
childNodePosition : String(10) enum { BELOW ; ABOVE; };
};
elementHierarchy
{
parent : ElementRef;
initiallyCollapsed : Boolean default true;
};
resultValuesSource : String(10) enum { CUBE; DIMENSION; };
resultValueHelpSource : String(10) enum { QUERY; DIMENSION; };
reverseSign: Boolean default true;
onCharacteristicStructure: Boolean default true;

collisionHandling:
{ formula : String( 20) enum { DEFAULT; THIS; CONCURRENT; };
decimals : String( 20) enum { DEFAULT; THIS; CONCURRENT; };
scaling : String( 20) enum { DEFAULT; THIS; CONCURRENT; };
semanticObject : String( 20) enum { DEFAULT; THIS; CONCURRENT; };
};
ignoreFurtherFilter:
{ forElement : array of ElementRef;
forAllElements : Boolean; }
};
exceptionAggregationSteps : array of
{
exceptionAggregationBehavior : String(14) enum
{
SUM;
MIN;
MAX;
COUNT;
COUNT_DISTINCT;
AVG;
STD;
FIRST;
LAST;
NHA;
};
exceptionAggregationElements : array of String(30);
};
variable {
usageType : String(20) enum { PARAMETER; FILTER; FORMULA; };
referenceElement : ElementRef;
mandatory : Boolean default true;
defaultValue : String(1024);
defaultValueHigh : String(1024);
defaultHierarchyNode : {
nodeType : String( 30 );
node : array of {
element : String( 30 );
};
};
defaultRanges : array of {
sign : String(1) enum { I; E; };
option : String(2) enum { EQ; BT; CP; LE; GE; NE; NB; NP; GT;
LT; };
low : String(1024);
high : String(1024);
};
selectionType : String(20) enum { SINGLE; INTERVAL; RANGE;
HIERARCHY_NODE; };
multipleSelections : Boolean default true;
hierarchyBinding : array of {
type : String(20) enum { PARAMETER; CONSTANT; SYSTEM_FIELD;};
value : String(512) ;
};
};
};


Usage
Annotation Meaning
AnalyticsDetails.ex Usually, the default aggregation determines how measures are aggregated in analytics.
ceptionAggregationS
 Caution
teps.exceptionAggre
gationBehavior The default aggregation behavior can't be defined in the query. It must be defined on
the cube layer.
In some cases, different aggregation behavior is needed for a special element of the entity
(dimension of a cube).
 Note
Example: A measure "Inventory" can be summed up for the different plants and other
dimensions, but not for time – according to time the last or average value might be
relevant.
Exception aggregation is optional and is used to define different (to the de-
fault aggregation) aggregation behavior for specified elements. In general, there
can be multiple elements in which a measure has to be aggregated differ-
ently. Therefore, a list of ExceptionAggregationSteps can be assigned.
ExceptionAggregationBehavior defines the aggregation behavior.
 Note
Example: In the query there's a measure that should show the number of
customers with positive sales - where sales is a measure of the underlying
CUBE view with default aggregation SUM. When the sales measure is now
used in a query with exceptionAggregationBehavior: COUNT and
exceptionAggregationElements : Customer, the sales must first be ag-
gregated (SUM) at customer level, and then COUNT has to be performed. If there’s a
value for sales, this means that the sales is replaced by 1 (otherwise it is set to 0). This
number can be summed up again.
Scope: #ELEMENT
Evaluation Runtime (Engine): The (logical) order in which the Analytic manager performs
the aggregation is as follows: Firstly the DefaultAggregation is performed. This intermediate
result is still grouped by all elements in the list of ExceptionAggregationSteps. The
result is then aggregated by the exception aggregation in the order of StepNumber.
The first remark holds even if the default aggregation is FORMULA. This means the calcula-
tion is performed when the result is still grouped by the exception aggregation elements.
After the formula has been calculated, the result is aggregated according to the list of
ExceptionAggregationSteps. This means that the aggregation level to be used for
calculation can be defined precisely.

Annotation Meaning
ENUM Description
SUM Sum
MIN Minimum
MAX Maximum
NHA "No Hierarchy Aggregation" - the value of a hierarchy's no-

des isn't the aggregate of its children.
COUNT Counter
AVG Average
STD Standard deviation
FIRST First
LAST Last
AnalyticsDetails.ex The elements that should be aggregated in this step. These elements must represent di-
ceptionAggregationS mensions. For more information, see
teps.exceptionAggre AnalyticsDetails.exceptionAggregationSteps.exceptionAggregati
gationElements onBehavior.
Scope: #ELEMENT
Type: String - list of elements representing dimension
AnalyticsDetails.qu For a tabular display of the query result, the elements can be positioned on multiple axes
ery.axis for the default layout. The elements can be directly annotated with their axis. Measures
(elements that can be aggregated (@Aggregation.default)) all need to be on the same axis.
The annotation of the first measure will therefore be used for all measures of the query. If no
AnalyticsDetails.query.axis is found, the system positions the measures on the
columns.
The default value for elements that are not measures is the free axis. Note that elements in
the projection list, which belong to the same field in the query, for example, text field, will be
grouped together.
Scope: #ELEMENT
Evaluation Runtime (Engine): Analytic manager: If the BI client doesn't specify which
elements are on which axis, the layout is derived by this annotation.
ENUM Description
FREE Default value for elements other than measures. Dimension

isn't displayed in the initial grid, but can be added to rows or
columns by a user at runtime.
ROWS

Annotation Meaning
COLUMNS Default value for measures.
AnalyticsDetails.qu If a query has a measure and a characteristic structure, conflicts can occur. For instance,
ery.collisionHandli both structures might contain a member with a formula. Then it has to be specified which
property should be the taken for the resulting cell: the property from the measure structure
ng
member or the property from the characteristic structure member. For instance, if both
members are a formula it has to be specified, which formula should be calculated for the
resulting cell. If nothing is specified, the property of the measure structure will be taken.
 Note
The query.collisionHandling annotation must be used with special elements. query.colli-

sionHandling.decimals, -.formula, -.scaling, or -.semanticObject.
AnalyticsDetails.qu Determines which setting for decimals (query.decimals) should be set for the resulting cell.
ery.collisionHandli This annotation is only relevant for measures. For other elements it will be ignored.
ng.decimals
Scope: #ELEMENT
ENUM Description
AnalyticsDetails.qu Determines which formula should be calculated in the resulting cell.

ery.collisionHandli
Scope: #ELEMENT
ng.formula
ENUM Description

Annotation Meaning
AnalyticsDetails.qu Determines which setting for scaling (query.scaling) should be set for the resulting cell.
ery.collisionHandli
Scope: #ELEMENT
ng.scaling
ENUM Description
Determines which semantic object (Consumption.semanticObject) should be assigned to

AnalyticsDetails.qu
the resulting cell.
ery.collisionHandli
Scope: #ELEMENT
ng.semanticObject
ENUM Description
AnalyticsDetails.qu For fields that represent measures, restricted measures, and calculated elements, you can
ery.decimals set the number of decimals to be used. This annotation is only relevant for measures. For
other elements it will be ignored.
Scope: #ELEMENT
Type: Integer number from 0 to 9.

Annotation Meaning
AnalyticsDetails.qu This annotation defines if a dimension should be displayed as (external) key or text in the
ery.display default layout. If nothing is specified, the default is taken from the Analytical Provider. If it is
not specified in the Analytical Provider, the default is #TEXT if the dimension supports text.
Otherwise, the default is #KEY.
Scope: #ELEMENT
Evaluation Runtime (Engine): Analytic manager: This annotation is relevant for dimen-
sions in analytic queries and in cube views.
ENUM Description
KEY The key will be displayed.
TEXT The text will be displayed.
TEXT_KEY Text and key will both be displayed - text first.
KEY_TEXT Key and text will both be displayed - key first.
AnalyticsDetails.qu This annotation allows you to specify the display hierarchy attribute for the element. It isn't
ery.displayHierarch possible for measures.
y The query result is shown in a hierarchy for the specified element.
Scope: #ELEMENT
ENUM Description
OFF No display hierarchy
ON With display hierarchy. The hierar-

chy used must be specified by
AnalyticsDetails.query.hierarchyBinding.
Only if there doesn't exist a hierarchy directory, the binding
isn't necessary.
FILTER The display hierarchy is the same one defined on the filter
for this element. In this case, a hierarchy filter needs to be
defined on the same element. The hierarchy binding is taken
from the filter.
FILTER_ONLY This is similar to FILTER but display hierarchy can't be

changed at runtime.
AnalyticsDetails.qu A hierarchical display of structure members can be displayed with this annotation. The
ery.elementHierarch hierarchy can be defined within the measure structure and the characteristic structure.
y This annotation must be used with an element, -.elementHierarchy.inilliallyCollapsed or
-.elementHierarchy.parent.

Annotation Meaning
AnalyticsDetails.qu If true, the hierarchy node represented by the annotated entry will be initially col-
ery.elementHierarch lapsed (only applicable if the annotated entry has children. The elements of the meas-
ure structure and characteristic structure can be displayed in a hierarchical way. With
y.initiallyCollapse
AnalyticsDeltails.query.elementHierarch.parent, an element becomes
d
the child of another element.
Scope:#ELEMENT
Type: Boolean
AnalyticsDetails.qu Elements of a structure (measure or characteristic) will be shown as a flat list in the key fig-
ery.elementHierarch ure structure of the Analytic Query. To achieve a hierarchical display, select list entries can
y.parent be annotated with @AnalyticsDetails.query.elementHierarchy.parent

and will appear hierarchically below the specified parent entry.
If the element belongs to the measure structure, the parent must also belong to the meas-
ure structure. If it belongs to the characteristic structure, the parent element must belong to
the characteristic structure.
Scope:#ELEMENT
Type: ElementRef. This is the alias of the select list entry serving as parent for the annotated
entry.
AnalyticsDetails.qu This annotation allows you to specify the formula expression, which can't be expressed as
ery.formula an SQL formula (operands required from the element list of the view). Only numerical values
(measures) can be used as operands.
Scope: #ELEMENT
Type: String
This expression can contain the following:
• Cube measures
• Arithmetic expressions
• Functions NDIV0 and NODIM
• CASE expressions with a maximum of one THEN clause (will be translated into BW IF
operator)
• WHEN clause can contain conditional or Boolean expressions of measures
• ELSE clause is optional (default to ELSE 0)
Evaluation Runtime (Engine): Analytic manager: This annotation will be interpreted as a

formula.

Annotation Meaning
AnalyticsDetails.qu With this annotation, an element of a structure can be hidden but the end user can display
ery.hidden it at runtime. If Consumption.hidden is used the element is hidden at all times and
cannot be seen at runtime.
Scope: #ELEMENT
Type: Boolean
AnalyticsDetails.qu General example for AnalyticsDetails.hierarchyBinding type annotations.
ery.hierarchyBindin  Example
g
AnalyticsDetails.query.hierarchBinding: {type : #PARAMETER,
value 'parameter_name'}. In this case, parameter_name specifies the name
of a parameter. This annotation is an array of the sub-annotations -type, -value, and
variablesequence. See details below.
AnalyticsDetails.qu The AnalyticsDetails.query.hierarchyBinding annotations allow you to

ery.hierarchyBindin specify a special hierarchy for an element with a display hierarchy. One tuple has to be
g.type specified for each key field of the hierarchy directory view. The first entry is supplied to the
first key field of the hierarchy directory, the second entry to the second key field, and so on.
If there is no hierarchy directory, the hierarchy binding can be omitted.
AnalyticsDetails.query.hierarchyBinding.type determines how the

key element is filled (by a constant, a parameter, a filtered ele-
ment or by a user input field). The type specifies the type of
AnalyticsDetails.query.hierarchyBinding.value.
Scope: #ELEMENT
ENUM 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 run-

time 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
AnalyticsDetails.query.variableSequence.

Annotation Meaning
AnalyticsDetails.qu This annotation contains, depending on the type, a literal value, the parameter name
ery.hierarchyBindin (without : $parameter), the element name and an identifier for the user input field,
g.value respectively. In case of type #SYSTEM_FIELD, the allowed values are those of @Environ-
ment.systemField for system field.
Scope: #ELEMENT
Type: String
AnalyticsDetails.qu This annotation allows you to specify the order of parameters and variables on the variable
ery.hierarchyBindin input UIs.
g.variableSequence In case filters or parameters are not annotated, they are displayed after the annotated ones
in the order they appear in the CDS document.
Scope: #ELEMENT
field.
AnalyticsDetails.qu This annotation defines which hierarchy level will be displayed initially.
ery.hierarchyInitia Scope: #ELEMENT

lLevel
Type: Integer - Hierarchy level with that number will be displayed initially.
AnalyticsDetails.qu Defines whether the nodes should expand to the bottom or the top.
ery.hierarchySettin Scope: #ELEMENT

gs.childNodePositio
n
ENUM Description
BELOW (Default) The children are shown below the parent if the
dimension is on the rows. If the dimension is on the columns,
the children will be shown on the left.
ABOVE The children are shown above the parent (on rows) or to the
left (on columns).
AnalyticsDetails.qu For some hierarchies, the hierarchy nodes can have posted values on their own (and not just
ery.hierarchySettin represent the aggregation over all its child nodes) which are displayed as separate rows in
the report. Using this annotation the display of the posted values can be suppressed.
gs.hidePostedNodesV
alues Scope: #ELEMENT
Type: Boolean

Annotation Meaning
AnalyticsDetails.qu Node 1 has children Node 11 and Node 12. Node 11 has only one child, Node 111. Node 111 has
ery.hierarchySettin children Node A and Node B. Then Node 111 will be presented as child of Node 1 and Node 11
is not visible.
gs.hideNodeWithOneC
hild Scope: #ELEMENT
Type: Boolean
lter which expects a list of elements, names, and the annotation, and
AnalyticsDetails.query.ignoreFurtherFilter.forAllElements, With
variant forAllElements, filters for all dimensions are ignored. With var-
iant,forElement, only the filters for the dimension in that list are ignored.
The feature "constant selection" of the analytical engine can be modeled by using the
AnalyticsDetails.qu
annotations AnalyticsDetails.query.ignoreFurtherFilter.forElement
ery.ignoreFurtherFi (expects a list of elements (expects a list of elements names) and the annotation
lter.forElement AnalyticsDetails.query.ignoreFurtherFilter.forAllElements. With
variant "forAllElements" all filters for all dimensions are ignored. With variant "forElement"
only the filters for the dimension in that list are ignored.
Scope: #ELEMENT
Type: Boolean
The feature "constant selection" of the analytical engine can be modeled by using the
AnalyticsDetails.qu
annotations AnalyticsDetails.query.ignoreFurtherFilter.forElement
ery.ignoreFurtherFi (expects a list of elements (expects a list of elements names) and the annotation
lter.forAllElements AnalyticsDetails.query.ignoreFurtherFilter.forAllElements. With
variant "forAllElements" all filters for all dimensions are ignored. With variant "forElement"
only the filters for the dimension in that list are ignored.
Scope: #ELEMENT
AnalyticsDetails.qu All measures, restricted measures, and calculated elements will be shown in the measure
ery.onCharacteristi structure. Further restricted elements can be assigned to a second structure (characteristic
structure). If a formula is used with all operands belonging to the character structure, the
cStructure
formula must be integrated into the character structure. Pattern for a resticeted element :
CASE WHEN...THEN 1 END AS....
Scope: #ELEMENT
Type: Boolean

Annotation Meaning
AnalyticsDetails.qu This annotation specifies which values of a dimension should be shown in a value help at
ery.resultValueHelp query runtime for selecting a dynamic filter. This is only supported for elements.
Source
ENUM Description
QUERY Before data is selected from the dimension view the query
is performed with the dimension in drill-down and all other
filters in place. The result is used as an additional filter when
selecting data from the master data view.
This is the default if the annotation is not set.
DIMENSION The value help is showing all data from the master data view.
AnalyticsDetails.qu This annotation influences the list of values, which should be taken into account for a
ery.resultValuesSou specific dimension. This is only supported for elements.
rce Scope: #ELEMENT, #PARAMETER
ENUM Description
CUBE All values available in the view of the from clause.
DIMENSION All values available in dimension.
AnalyticsDetails.qu The sign of a measure will be flipped (positive numbers will become negative and negative
ery.reverseSign numbers will become positive). It is only a display feature. Calculations with the measure will
be performed with the "real" sign. This is only supported for elements
.Scope: #ELEMENT, #PARAMETER
Type: Boolean
AnalyticsDetails.qu For measures, restricted measures, and calculated elements, you can set the scaling factor
ery.scaling to be used. This annotation is only relevant for measures. For other elements it will be
ignored. Numbers will be scaled by a factor of 10*n.
Scope: #ELEMENT
Type: Integer number from 0 to 9.

Annotation Meaning
AnalyticsDetails.qu If nothing is specified, the rows are sorted ascending by first dimension, second dimension,
ery.sortDirection and so on. The same is true for dimension on columns. With this annotation, the sort
direction can be set #ASC (ascending) and #DESC (descending).
Scope: #ELEMENT
ENUM Description
ASC Sort ascending (default)
DESC Sort descending
AnalyticsDetails.qu For dimensions, you can set the behavior for totals. These annotations will be ignored for
ery.totals measures.
Scope: #ELEMENT
ENUIM Description
HIDE Totals or subtotals are not added to the result set for this
element.
SHOW In addition to the details, the subtotals are added to the

result set for this element.
AnalyticDetails.var In general, a CDS parameter represents a single value which has to be determined at
iable runtime either by user input or derivation. But in Analytics, this concept is too strict. There
is the need for multiple values, for intervals, for hierarchy-nodes. In some cases the input
should be optional. This can be achieved with the AnalyticsDetails.variable
annotations. If these annotations are used, the ODATA.publish: true is not supported.
AnalyticsDetails.qu If user input is necessary for the parameter, the sequence of all fields for user input at
ery.variableSequenc runtime can be specified with this annotation. UIs will create user prompts for parameters
that require a user input or elements with filters (consumption.filter). This annotation can
e
be used to specify the sequence of user prompts at runtime. If filters or parameters are not
annotated, they are displayed after the annotated ones - in the order they appear in the CDS
document. The sequence is calculated according to the order of all variables.
Type: Integer - The order of parameters and variables. Integer values may contain gaps.

Annotation Meaning
AnalyticsDetails.va These annotations allow one to specify a default value for a hierarchy node filter. It has to be
riable.defaultHiera used in combination with selectionType #HIERARCHY_NODE. A hierarchy node is seen as

a list of elements (structured type), which are the semantic elements in the corresponding
rchyNode
view with ObjectMOdel.dataCategory : #Hierarchy.

rchyNode.node.eleme AnalytictsDetails.variable.selectionType #HIERARCHY_NODE. A hier-

nt arch node is seen as a list of elements (structure type) which are the semantic elements
in the corresponding view with ObjectModel.dataCategory: #HIERARCHY. With
sub annotation node, each part can be set to a constant separately. Element is reference ing
the element in the hierarchy view. If the value of the field NodeType, is initial, then the value
represents a leaf.
The annotation
AnalyticsDetails.variable.defaultHierarch.node.element is referring
to the element in the hierarch view.
Scope: #PARAMETER
Type: String
AnalyticsDetails.va The AnalyticsDetails.variable.defaultHierarchyNode annotations allow

riable.defaultHiera one to specify a default value for a hierarch node filter. It must be used in combination
rchyNode.node.value with AnalytictsDetails.variable.selectionType #HIERARCHY_NODE. A

hierarch node is seen as a list of elements (structure type) which are the semantic elements
in the corresponding view with ObjectModel.dataCategory: #HIERARCHY.
Scope: #PARAMETER
Type: String

Annotation Meaning

rchyNode.nodeType AnalytictsDetails.variable.selectionType #HIERARCHY_NODE. A hier-

arch node is seen as a list of elements (structure type) which are the semantic elements in
the corresponding view with ObjectModel.dataCategory: #HIERARCHY.
If the value of the field NodeType is initial, the value represents a leaf.
Scope: #PARAMETER
Type: String
riable.defaultRange follows the ABAP-range logic with the subfield high.
s.high Scope: #PARAMETER
Type: String
riable.defaultRange follows the ABAP-range logic with the subfield low.
s.low Scope: #PARAMETER
Type: String
riable.defutaltRang follows the ABAP-range logic with the subfield option.
hes.option Scope: #PARAMETER
ENUM Description
EQ
BT
CP
LE
GE

Annotation Meaning
NE
NB
NP
GT
LT
riable.defaultRange follows the ABAP-range logic with the subfield sign.
s.sign This annotation specifies the default for a variable with selection type #RANGE. The logic
follows the ABAP-range logic with the subfield sign.
Scope: #PARAMETER
ENUM Description
AnalyticsDetails.va This annotation specifies a default value. If the variable is input enabled, the variable is
riable.defaultValue prefilled with the default value. If the variable is hidden, the variable is processed with the
default value. The resulting type of the "default expression" must comply with the data type
of the associated element.
Scope: #PARAMETER
Type: String
AnalyticsDetails.va This annotation is used in combination with AnalyticsDetails.defaultValue

riable.defaultValue to specify a default for the upper bound of an interval.
High AnalyticsDetails.devaultValue specifies the lower boundary. It is only useful

for variables of the selection type #INTERVAL or #RANGE.
Scope: #PARAMETER
Type: String

Annotation Meaning
AnalyticsDetails.va This annotation determines how the key element is filled by either a constant, a parameter,
riable.hierarchyBin a (filtered) element, a user input field, or a system field. Allowed values: #CONSTANT,
#PARAMETER, #SYSTEM_FIELD.
ding.type
Scope: #PARAMETER
ENUM Description
PARAMETER
CONSTANT
SYSTEM_FIELD Allowed values are for those of @Environment.systemField

for system field.
AnalyticsDetails.va This annotation contains, depending on the type, a literal value, the parameter name (with-
riable.hierarchyBin out : or $parameter), the element name, the identifier for the user input field, and system
field. Allowed values are those of @Environment.systemField for system field. In the case of
ding.value
type '
Scope: # PARAMETER
Type: String
AnalyticsDetails.va This annotation shows the position of the variable generated for the user input field. The
riable.hierarchyBin sequence is calculated according to the order of all variables.
ding.variableSequen
 Note
ce
This annotation is only relevant for type: #USER_INPUT.
Scope: # PARAMETER
Type: Integer

Annotation Meaning
AnalyticsDetails.va If this is set to true, the system enforces that the variable contains a value at runtime. If it is
riable.mandatory set to false, the variable is optional and the query might be executed without a value set.
 Note
If the annotation is not set, the variable is mandatory. This behavior is different from
other boolean annotations.
Scope: # PARAMETER
Type: Boolean
AnalyticsDetails.va This annotation is used to indicate that several lines (rows) can be entered on the filter input
riable.multipleSele (selection UIs combined with the selectionType you get.
ctions
Scope: # PARAMETER
Type: Boolean
AnalyticsDetails.va This annotation refers to an element in the result structure or in the underlying data source
riable.referenceEle to which the variable refers. In the case of a filter variable, this annotation is mandatory and
ment must contain the element that represents the dimension. In general, it restricts the usage in
expressions, serves as a reference for default values, and may result in a default value help.
Scope: #PARAMETER
Type: String
AnalyticsDetails.va This annotation determines how values can be entered.

riable.selectionTyp
Scope: #PARAMETER
e
ENUM Description
SINGLE Single Value
INTERVAL Interval is a special case of a Range with "sign = including"

and "option = BT".
RANGE A Range is a complete (ABAP like) SELECT option including

sign (including/excluding) and an operator such as EQ, CP,
or BT.
HIERARCHY_NODE Hierarchy node means everything under the node.

Annotation Meaning
AnaylticsDetails.va This annotation is a classification corresponding to the terminology Parameter Variable,
riable.usageType Filter Variable, and Formula Variable. The usage of the parameter in the view definition has
to match the intended usage expressed with this annotation. Whether the parameter is used
according to the usageType is not verified by the analytical engine.
Scope: #PARAMETER
ENUM Description
PARAMETER The variable is used for a parameter of the underlaying data

source. For example, the value is pushed down at runtime via
SQL to the corresponding data source.
FILTER The variable is used in filters for the dimension represented

by the element annotated as referenceElement. Filters are
typically global filters in the case of CDS: where clause or
element restrictions in Restricted Measures in the case of
CDS: sub expression when expressions.
FORMULA The variable is used as a placeholder in expressions defining

calculated measures, for example virtual elements with for-
mula aggregation referring to other elements with measure
semantics.
Examples
Example 1
Calculated Elements
 Sample Code

define view fincancial as select from sales
{
@AnalyticsDetails.query.axis : #ROWS
product,
@AnalyticsDetails.query.axis : #COLUMNS
@AnalyticsDetails.query.formula : 'revenue - cost'
1 as absolute_margin,
@AnalyticsDetails.query.formula : 'NDIV0($projection.absolute_margin /
revenue ) * 100'
1 as relative_margin,
@AnalyticsDetails.query.formula : 'CASE WHEN $projection.relative_margin >

20 THEN revenue ELSE 0 END'
1 as revenue_for_margin_gt_20
}


Example 2
Display hierarchy selection: Specify the hierarchy directly.
 Sample Code

define view costcenter_reporting
with parameters
cost_center_hier_param : String
as select from costcenters
{
...
@AnalyticsDetails.query : {
displayHierarchy: #ON,
hierarchyInitialLevel: 3, // three levels of the hierarchy will be

opened at start
hierarchySettings{hidePostedNodesValues: true }, // don't show posted
node values
hierarchyBinding :
[ { type : #CONSTANT, value : 'CONTR_AREA_10' },
{ type : #PARAMETER, value : 'cost_center_hier_param' }
]
}
costcenter, // hierarchy node filter
costs,
...
}

Example 3
Use of $session variables, especially $session.system_date.
The system supports variables like $session.system_date for different use cases:
• in cube parameters
 Sample Code

define view …
as select from zCostCenter_Flt( P_KeyDate: $session.system_date )

• in queries on time-dependent master data in where clauses
 Sample Code

} where
DateTo >= $session.system_date and
DateFrom <= $session.system_date

• in paths to time-dependent attributes or texts
 Sample Code

_CostCenter[1: DateTo >= $session.system_date and DateFrom <=
$session.system_date]._Text[1: Language = $parameters.P_Language].Text as
CostCenterText,


• in restricted key figures
 Sample Code

case when PostingDate = $session.system_date
9.7 Consumption Annotations
Define a specific behavior that relates to the consumption of CDS content through domain-specific
frameworks.
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 Definition
Annotations belonging to Consumption.filter regulate filtered queries on UIs.
Usually filter values are entered manually by the user on a UI. By using filter annotations query filters can be influenced.
Scope: [ELEMENT]
Evaluation Runtime (Engine): Interpreted by ABAP Runtime Environment
Consumption.filter. Boolean (true, Scope: [ENTITY,ELEMENT]

businessDate.at false) As an association annotation, this annotation is relevant for
associations to temporal CDS views that do not bind the
temporal key of the target in ther on-condition. The annota-
tion indicated that in consumption scnearios with key-date
semantics, the association should be filtered with the key
date.
As a view annotation, this annotation indicated that the view

should be consumed at a key date.

Consumption.filter.defaultHierarchy This annotation allows to specify a default value for a hierar-

chy node filter of a view element
This annotation must be used in combination with

selectionType:#HIERARCHY_NODE
The default is either proposed to the end user or implicitly

set by the consumption framework of the view in case the
end user does not explicitly specify a different value.
A hierarchy node is seen as a list of elements, which

are the semantic elements in the corresponding view with
@ObjectModel.dataCategory:#HIERARCHY.
nodeType Value: Description
elementRef References the element in

the hierarchy node view.
node[] With node each part can be set to a constant separately
Value: Description
element References the element in

the hierarchy node view.
value Specifies the value for the

node.
Consumption.filter. String(1024) Specifies a default value for a filter of a view element. This
defaultValue value is either proposed to the end user or implicitly set by
the consumption framework in case the end user does not
explicitly specify a different value.
The result type of the string expression must comply with

the data type of the annotated element.
Consumption.filter. String(1024) This annotation is used in combination with

defaultValueHigh defaultValue to specify a default interval for a filter of
a view element.
In this case, the defaultValue contains the lower,

defaultValueHigh thge upper boundary of the interval.
Consumption.filter. String(12) This annotation determines how the key element is filled.
hierarchyBinding.ty
#ELEMENT Name of an element, which has a unique filter. At runtime,
pe the filter value is used for this hierarchy component.
#PARAMETER Parameter name.
#CONSANT 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 in-
put at runtime. The variable is placed in the list of all values
in accordance with
Consumption.filter.hierarchyBinding.vari
ableSequence.
#SYSTEM_FIELD System field.
Consumption.filter. String(512) This annotation contains, depending on the type, a literal

hierarchyBinding.va value, the parameter name (without : or $parameter), the
element name and an identifier for the user input field, re-
lue
spectively.
Consumption.filter. Boolean (true, Specifies that the filter is hidden for the UI client.
hidden false) In combination with a derivation, this leads to a dynamic
filter at runtime without user interaction.
Consumption.filter. Boolean (true, This annotation enforces a user to enter a value for the an-
mandatory false) notated element even if a default value exists.
Consumption.filter. Boolean (true, This annotation is used to indicate that several lines can be
multipleSelections false) entered on the filter input (selection) UIs combined with the
selectionType. The following combinations are available:
• selectionType SINGLE and multipleSelections = true:

IN list
• selectionType INTERVAL and multipleSelec-
tions=false: single interval
• selectionType INTERVAL and multipleSelections =
true: several intervals
• selectionType RANGE and multipleSelections = true:
several ranges ( complete (ABAP like) SELECT-options).
Consumption.filter. String(20) This annotation defines how values can be entered.

selectionType
SINGLE Specifies that a single value must be entered.
INTERVAL Specifies that an interval must be entered.
An Interval is a special case of range with

sign=including and operator=BT.
RANGE Specifies that a range must be entered.
A range is a complete SELECT-option including sign and op-

erator.
HIERARCHY_NODE Specifies that a hierarchy node must be entered.
Refers to the complete hierarchy under the node.

Consumption.filter. Integer This annotation allows you to specify the order of parame-
variableSequence ters and variables on the variable input UIs.
The number defines the position of the variable generated

for the user input field.
Consumption.hidden Boolean (true, This annotation prevents fields from being exposed by
false) (default false) OData. Therefore, the field will not be exposed to UIs.
Consumption.default String(1024) This annotation can be used on action importing parameters

Value to define default values for the action consumption via UI
consumption. The specified value in the annotation is then
displayed as default value when executing the action on the
UI.
Consumption.semanti string This annotation leverages enhanced interoperability across

cObject applications. The semantic semantic object that is defined in
the Fiori Launchpad must be specified as the value.
 Example
SAP Fiori has introduced the concept of intent-

based navigation, whereby an intent is a combi-
nation of <semanticObject> <action>. A
semanticObject annotation is used in SAP Fiori UIs
to dynamically derive navigation targets for the anno-
tated view as a source.
Scope: #ELEMENT, #PARAMETER, #ENTITY
For more information, see Based on Intent [page 846].
Consumption.valueHe string This annotation defines whether the values of the value help
lpDefault.fetchValu provider view are automatically retrieved without setting a
es Possible Values:
filter when invoking the value help, or whether they must be
#AUTOMATICALLY_WHEN explicitly requested.
_DISPLAYED (default in The annotation must be used in the value help provider en-
OData V4) tity.
#ON_EXPLICIT_REQUES Scope: #ENTITY

T (default in OData V2)
Annotations belonging to Consumption.valueHelpDefinition directly establish a relationship to an entity that acts as a value
help provider.
The value help can be consumed without an association to the target value help provider.
Scope: [ELEMENT, PARAMETER]
Evaluation Runtime (Engine): Interpreted by ABAP Runtime Environment

Consumption.valueHelpDefinition.addition Defines an additional binding condition for the value help

alBinding[] on the same target value help provider entity for filtering
the value help result list and/or returning values from the
selected value help record.
element Specifies the element in the target value help provider entity
that is linked to the local element or parameter for the addi-
tional binding.
localElement Specifies the local element that is linked to the element or

parameter in the target value help provider entity for the
additional binding.
localParameter Specifies the local parameter that is linked to the element

or parameter in the target value help provider entity for the
additional binding.
parameter Specifies the parameter in the target value help provider

entity that is linked to the local element or parameter for the
additional binding.
usage The binding may either specify an additional filter-criterion

on the value help list (#FILTER), or an additional result
mapping for the selected value help record (#RESULT) or
a combination thereof (#FILTER_AND_RESULT). If not
specified explicitly the usage is #FILTER_AND_RESULT. If
distinctValues is set to true, additional bindings must specify
the usage as #FILTER.
Consumption.valueHelpDefinition.distinct Specifies whether the value help result list shall only contain
Values distinct values for the annotated field or parameter. If set to
true all mappings will be used for filtering, but only the value
for the field/parameter which the value help was requested
for will be returned by the value help.
Consumption.valueHelpDefinition.entity[] Defines the binding for the value help to the value help pro-
viding entity. It requires specification of the entity and the
element providing the value help for the annotated element.
element Value: Description
elementRef Specifies the element in the

entity referenced in name
that provides the value help
for the annotated element.
name Value: Description
entityRef Specifies the entity which

contains the element that
provides the value help.

Consumption.valueHelpDefinition.label This annotation contains a language-dependent text that is

used to label the value list, if more than one value help is
assigned to one element.
If not specified the label of the value help binding element is

used.
Consumption.valueHelpDefinition.presenta The presentation variant indicates how the value help result
tionVariantQualifier should be displayed.
Consumption.valueHelpDefinition.qualifie Uniquely identifies alternative values for an annotation.

r
Omission means the OData term is applied without explicit
qualifier.
If more than one value help is defined for one element, a

qualifier must be used.
Consumption.valueHelpDefinition.useForVa Value Description

lidation
Boolean (default: This annotation marks value
true) help that shall be used for
validation of user input.
Consumption.ranked Value Description
Boolean (default: This annotation enables

true) search results in value help
views to be automatically
sorted by search score. As
the implementation of the
search functionality requires
special considerations, this
kind of sorting cannot be
implemented by default, but
must be explicitly activated
on the views that fulfill the
necessary prerequisites.
Example 1
The annotation Consumption.valueHelpDefinition is used to define a value help for the annotated
element. The value help provider can be a different CDS entity without association. To consume the value
help, the value help provider entity must be added to the respective OData service.
You can filter the available value help options by defining an additional binding. In the following example case,
only the business partners are displayed that use the same currency code.
 Sample Code
DEFINE VIEW BuPaView AS SELECT FROM db_bp

{
key bp.bp_id as BusinessPartnerID,
...
bp.currency_code as CurrencyCode,
bp.company_name as CompanyName,
}

DEFINE VIEW SOView AS SELECT FROM db_so as so
{
so.sales_order_id as SalesOrderID,
…
so.CurrencyCode as CurrCode,
@Consumption.valueHelpDefinition: [{ entity : { name :
'I_AIVS_BusinessPartner',
element :
'BusinessPartnerID'},
additionalBinding :
[{ localElement : 'CurrCode',
element : 'CurrencyCode'
}]
}]

_BusinessPartner.BusinessPartnerID
Example 2
 Sample Code
define view sales_order_vh as select from SalesOrder as so

{
…
@Consumption.valueHelpDefinition: [{ qualifier: 'ValueHelp2',
entity : { name :
'I_BusinessPartner',
element :
'BusinessPartnerID'
},
label : 'Business Partner Value Help'
},
{ entity : { name :
'I_BuPa',
element :
'BusinessPartnerID'
},
label : 'Business Partner VH'
}]

_BusinessPartner.BusinessPartnerID
9.8 Hierarchy Annotations
 Home Enables an application developer to specify a parent-child hierarchy that they want to make explicitly
accessible in a data model, together with the structure that defines this hierarchy.
@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 can be defined in two ways. The first is a hierarchy based directly on the master
data/dimension entity, for example, employees and managers. In this case, the hierarchy is time dependent if
the master data entity is as well. The second is a specific hierarchy view. Here, the recursion can be defined
on abstract keys and several hierarchies may exist. With abstract keys, the nodes could be different business
entities and it is possible that leaves belong to multiple parent nodes. These features are not available when the
hierarchy is defined directly in the master data. In this scenario, the relation between the node and parent node
can depend on the time independent of the time dependency of the dimension.
The second is a specific hierarchy view. Here, the recursion can be defined on abstract keys and several
hierarchies may exist. With abstract keys, the nodes could be different business entities and it is possible that
leaves belong to multiple parent nodes. These features are not available when the hierarchy is defined directly
in the master data. In this scenario the relation between the node and parent node can depend on the time
independent of the time dependency of the dimension.
 Note
A simple example of a parent-child hierarchy is the “Employee” master data. A “Manager” is an “Employee”
and almost every “Employee” is assigned to a “Manager”.
On entity level the following metadata can be defined:

Annotation Meaning
Hierarchy.parentChild.director For external hierarchies, the view of hierarchy nodes often contains the
y nodes for multiple alternative hierarchies. A user is supposed to choose

a single hierarchy for display, and their selection is used as a filter when
selecting from the hierarchy node view. The directory annotation iden-
tifies an association, the hierarchy directory association, from the hierar-
chy node view to a view (the so-called hierarchy directory), providing all
available alternative hierarchies for this hierarchy node view. The hierarchy
view may be a standard dimension and could also provide text.
Scope: #VIEW
Type: AssociationRef . This denotes the name of the hierarchy directory

that is used to filter the nodes.
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.
Hierarchy.parentChild.label User-friendly name of the hierarchy. Only relevant if the view defines one
hierarchy only, and Hierarchy.parentChild.directory is not used.
Scope: #VIEW
Type: String - as a description of the hierarchy.
Evaluation Runtime (Engine): Analytic manager: This name can be

exposed in input help for Hierarchy.parentChild.name. The
hierarchy is exposed if there isn't a directory label defined. See
Hierarchy.parentChild.name.

Annotation Meaning
Hierarchy.parentChild.multiple Indicates that multiple parents might occur in the hierarchy.
Parents
 Note
In a geographic hierarchy, for example, you might want to assign the

country Turkey to the continents Europe and Asia.
 Caution
We need to distinguish the above use case from the following one: In
a time hierarchy YEAR, QUARTER, MONTH January under 2011 and
January under 2012 are not the same member with multiple parents.
They are different Januaries.
Scope: #VIEW
Type: Boolean. This defines whether multiple parents occur in the hierarchy
or not. Default setting is true.
Evaluation Runtime (Engine): The analytic manager can handle hierar-

chies with leaves with multiple parents, but it does't support nodes with
multiple parents. This annotation is only relevant for engines that cannot
handle multiple roots. The annotation is not interpreted by theAnalytic
manager:.
Hierarchy.parentChild.name Technical name of the hierarchy. Only relevant if the view defines one hier-
archy only, and Hierarchy.parentChild.directory is not used.
Scope: #VIEWThe hierarchy is accessed in queries or in program

logic later on via this name. The description can be set with the
Hierarchy.parentChild.label.
Type: String
Evaluation Runtime (Engine): Analytic manager:
Hierarchy.parentChild.orphaned Defines how nodes without a parent (more precisely with a parent that does
Node.handling not occur as a child) are processed.
Scope: #VIEW
Type:
Evaluation Runtime (Engine): Depending on the annotation value, the ana-

lytic manager will ignore orphaned nodes, treat them as root nodes, put
them under a step parent node or raise an error.
ENUM Description
ROOT_NODES Treat nodes as root nodes (default).
ERROR Stop processing and show an error.

Annotation Meaning
IGNORE Ignore nodes and remove them from the hierarchy.
STEPPARENT_N Put nodes under a step parent node.

ODE
Hierarchy.parentChild.orphaned Defines how nodes without a parent (more precisely with a parent that does
Node.stepParentNodeId not occur as a child) are processed.
• 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).
Scope: #VIEW
Type:
Evaluation Runtime (Engine):Analytic manager:
ENUM Description
stepParentNo node ID(s) of the step parent node(s)

deId
Hierarchy.parentChild.recurse. If the underlying view definition does not contain an association defining
child the parent-child relationship but only “normal” elements, this annotation
has to be used to define the children.
Scope: #VIEW
Type: Array of ElementRef. The element names define the key elements of
the "child".
Hierarchy.parentChild.recurse. If the underlying view definition does not contain an association defining
parent the parent-child relationship but only “normal” elements, this annotation
has to be used to define the parents.
Scope: #VIEW
Type: Array of ElementRef. The element names define the key elements of
the "parent".

Annotation Meaning
Hierarchy.parentChild.recurseB Defines the parent-child relationship in a hierarchy based on an existing
y association from hierarchy node to its parent node in the same view.
Scope: #VIEW
Type: ElementRef. The name of the parent-child association needs to be

specified here.
Hierarchy.parentChild.rootNode Using this annotation, you can define dedicated metadata for how to handle
.visibility root node(s) in the hierarchy.
Scope: #VIEW
Type:
Evaluation Runtime (Engine): Depending on the annotation value, the ana-

lytic manager might add an extra root node to the hierarchy. The label of
this node is the value of Hierarchy.parentChild.label.
ENUM Description
ADD_ROOT_NOD The system will add the root node of the hierarchy if
E_IF_DEFINED it is explicitly defined, but the system will not add an
extra artificial root node. This is the default.
ADD_ROOT_NOD The system will always add an artificial single root node
E to the hierarchy. All other nodes are descendants of
this node.
DO_NOT_ADD_R The system will not add an artificial single root node to
OOT_NODE the hierarchy.
Hierarchy.parentChild.siblings Hierarchy.parentChild.siblingsOrder defines the order of

Order.by values with the same parent.
Hierarchy.parentChild.siblingsOrder.by defines the ele-

ment name, which contains the values to be ordered.
Scope: #VIEW
Type: ElementRef
Evaluation Runtime (Engine): The analytic manager sorts all children of a

node in the given order.

Annotation Meaning
Hierarchy.parentChild.siblings Hierarchy.parentChild.siblingsOrder defines the order of

Order.direction values with the same parent.
Hierarchy.parentChild.siblingsOrder.direction defines
if the sort order of values with the same parent is “ascending” or “descend-
ing”.
Scope: #VIEW
Type:
Evaluation Runtime (Engine): The analytic manager sorts all children of a

node in the given order.
ENUM Description
ASC The sort order is ascending (default).
DESC The sort order is descending.
9.9 ObjectModel Annotations
Provide definitions of text-related aspects of the CDS-based data model
Usage
Annotation Meaning
Sets the OData annotation for filterable or non-filterable elements according to the annotation value
ObjectModel.
true or false.
filter.enabl
ed The annotation overrules element default settings regarding filter enablement for the element.
If the annotated CDS view is exposed in an OData service, the non-filterable properties are marked
with an OData annotation in the OData metadata. The default of being filterable is not shown in the
metadata.
Scope: [ELEMENT]
Evaluation Runtime (Engine): SADL
Value: BOOLEAN

Annotation Meaning
ObjectModel. References the query implementation class for the unmanaged query.
query.implem Scope: [VIEW]
entedBy:
This annotation is evaluated when the unmanaged query is executed whereby the query implementa-
tion class is called to perform the query.
To reference the query implementation class, ABAP: must be added to the string reference.
 Example
@ObjectModel.query.implementedBy: 'ABAP:<query_impl_class>'.
This annotation can be used in all CDS entity types except of abstract entities. When using this
annotation, the fields defined in the CDS view refer to the custom query and need to match the data
coming from the referenced query implementation class.
 Note
This annotation substitutes the deprecated annotation @QueryImplementedBy: ''.
Sets the OData annotation for sortable or non-sortable properties according to the annotation value
ObjectModel.
true or false.
sort.enabled
The annotation overrules element default settings regarding sorting enablement for the element.
If the annotated CDS view is exposed in an OData service, the non-sortable properties are marked
with an OData annotation in the OData metadata. The default of being sortable is not shown in the
metadata.
Scope: [ELEMENT]
Evaluation Runtime (Engine): SADL
Value: BOOLEAN
ObjectModel. Defines the associated view, which provides textual descriptions for the annotated field.
text.associa
Scope: [ELEMENT]
tion
Evaluation Runtime (Engine):
• SADL - Enriches the OData entity type of the view with the textual description of the target
view applying an automated language filtering. The name of the auto-generated text property
will be composed out of the annotated field name and the constant suffix _Text. This OData
property is mapped onto the first text field of the associated target CDS view annotated with
@Semantics.text:true.
• Analytic Manager - Uses the associated view as TEXT view for annotated field.
Establishes the conjunction of a field with its descriptive language-independent texts.

ObjectModel.
text.elemen Scope: [ELEMENT]
t[ ] Evaluation Runtime (Engine): SADL - First text field listed in the annotation array will be handled as
descriptive text of the annotated field in OData exposure scenarios.

Annotation Meaning
ObjectModel. • Value: { ASSOCIATED_TEXT_UI_HIDDEN }

text.control Scope: [VIEW, ELEMENT]
Suppresses the text element of the text association to be visible on the UI.
• Value: { NONE }
Scope: [ ELEMENT]
Overrules the annotation ObjectModel.text.control:
{ ASSOCIATED_TEXT_UI_HIDDEN } that is specified on entity level. For the annotated
element the text element of the text association is visible on the UI.
ObjectModel. Scope: [VIEW, ELEMENT]
text.referen Value: 'AssocRef'

ce.associati
The annotations defines an associated view which defines textual description for the annotated field.
on
The corresponding code field in the associated view is defined by the on-condition of the association.
ObjectModel. To support the decision on cache strategies for higher layers and to enable client-side statement
usageType.da routing using these caches, the data class is used. The different data classes correspond to different
life time cycles. The annotation dataClass has the following values:
taClass
• TRANSACTIONAL: The view contains data which is written or changed in high volume transac-
tions (also for background processing). Examples are header and items for Sales Order process-
ing or Financial Postings.
• MASTER: Master data is read but not written or changed in high volume transactions (also for
background processing). It typically drives the business process decisions when business logic is
executed. It is also shown to the user as context information and to enable user decisions when
these transactions are executed manually. Examples are material, business partner or account.
• ORGANIZATIONAL: The data describes the organizational structure of a company and its busi-
ness processes. It can be seen as a special type of master data. This data is only written or
changed when organization changes are implemented at the customer. Examples are sales unit,
distribution channel and cost center.
• CUSTOMIZING: The data describes how a concrete business process is executed at the cus-
tomer. It consists typically of content delivered by SAP enriched and extended by the customer.
This data is typically even less common changed. Examples are countries, unit of measures,
currency.
• META: Meta data specifies how the system is configured or describes the technical structure of
entities. Typically this is part of shipped content. Changes are done in fixes or upgrades. Examples
are DDIC structures, field control, authorization objects.
• MIXED: This option is chosen if the CDS view contains data of multiple data classes
ObjectModel. The category serviceQuality reflects the quality of service with regards to the expected performance
usageType.se of the CDS view. Based on the serviceQuality, the consumer can decide if a view fits to the demanded
rviceQuality response time and throughput requirements. There are 4 levels of service quality: 'A', 'B', 'C' and 'D'
corresponding to decreasing KPIs. 'A' has the highest requirements and 'D' the lowest. There is one
additional level 'X' where no KPIs are specified. This level is used as the default. serviceQuality 'P' is
reserved for views that are used to structure the view hierarchy and that don't have any consumer
outside of the hierarchy.
Scope:[#ENTITY, #TABLE_FUNCTION]

Annotation Meaning
ObjectModel. The sizeCategory is used to support the resource consumption within HANA . The resource consump-
usageType.si tion on HANA is mainly driven by the set of data which has to be searched through and the set of data
which has to be materialized in order to compute the result set. These are the different sizeCategory
zeCategory
labels for CDS views:
• S: Expected number of rows is < 1.000

• M: Expected number of rows is is between 1.000 and 99.999
• L: Expected number of rows is between 100.000 and 9.999.999
• XL: Expected number of rows is between 10.000.000 and 99.999.999
• XXL: expected number of rows is >= 100.000.000
Scope:[#ENTITY, #TABLE_FUNCTION]
ObjectModel. References the calculation class for the annotated virtual element.
virtualEleme Scope: [ELEMENT]
ntCalculated
By: This annotation defines the code exit for virtual elements. The query framework is left during runtime
to retreive the values for the virtual element in the calculation class.
To reference the calculation class, ABAP: must be added tot he string reference.
Examples
Example 1
This example demonstrates how you can define language-dependent texts with a text association.
 Sample Code

define view I_Material
association [0..*] to I_MaterialText as _Text ... {
@ObjectModel.text.association: ’_Text’
key Material,
_Text, ...
}
define view I_MaterialText ... {
key Material,
key Language,
MaterialName,
MaterialDescription, ...
}

Example 2
This example demonstrates how you can define language-independent texts within the same view.
 Sample Code

define view I_Plant ... {

@ObjectModel.text.element: [’PlantName’]
key Plant,
PlantName, ...
}

9.10 OData Annotations
Capture OData-related aspects to expose data gained from a CDS entity in an OData service.
Annotation OData

{
@Scope:[#ELEMENT]
etag : Boolean default true;
@Scope:[#ENTITY]
entitySet
{
name : String(30);
};
entityType
{
name : String(128);
};
action: array of {
name : String(128);
localName : String(30);
};
property
{
name : String(128);
};
@Scope:[#SERVICE]
schema
{
name : String(128);
};

Usage
OData annotations define OData specific properties in backend development objects.
Runtime:
• Exposed for OData

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
OaS
r
Dc
ro
a
ap
ty
e
ao
:
.f[
aM
E
caL
tnE
idM
E
oa
N
nt
oT
r]
yD
Ve
an
lo
ut
ee
ss
:t
h• l
e
o
e
c
x
t
a
e l
r N
n a
a m
l
e
n
a
• N
m a
e m
o e

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
f
a
n
a
c
t
i
o
n
f
o
r
a
n
a
r
b
i
t
r
a
r
y
O
D
a
t
a
s
e
r
v
i
c
e
.
T
h

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
e
a
n
n
o
t
a
t
i
o
n
m
a
p
s
t
h
e
l
o
c
a
l
N
a
m
e to the external OData name.

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
lSD
ote
n
cr
o
ai
t
lne
Ng(
s
a3t
m0h
e)e
a
c
t
i
o
n
n
a
m
e
f
o
r
m
a
p
p
i
n
g
t
o
t
h
e
O
D
a
t
a
a
c
t
i

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
o
n
n
a
m
e
(
n
a
m
e
)
.
nSP
atr
o
mr
v
ei
i
nd
g(
e
1s
2t
8h
e
a
c
t
i
o
n
n
a
m
e
f
o
r
O
D
a
t
a
.

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
OSS
Dtc
aro
tip
ane
.g(
:
e3[
n0E
t)N
iT
tI
yT
SY
e]
t
D
.
e
n
n
a
o
m
t
e
e
s
t
h
e
e
x
t
e
r
n
a
l
n
a
m
e
o

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
f
t
h
e
e
n
t
i
t
y
s
e
t
f
o
r
a
n
a
r
b
i
t
r
a
r
y
O
D
a
t
a
s
e
r
v
i
c

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
e
.


N
o
t
e
Y
o
u
c
a
n
a
l
s
o
d
e
fi
n
e
t
h
e
n
a
m
e
o
f
t
h
e

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
e
n
t
i
t
y
s
e
t
i
n
t
h
e
s
e
r
v
i
c
e
d
e
fi
n
i
t
i
o
n
b
y
u
s
i
n
g

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
a
n
a
l
i
a
s
:
e
x
p
o
s
e
/
D
M
O
/
C
_
T
r
a
v
e
l
_
U
a
s
T
r
a

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
v
e
l
.
T
h
e
n
a
m
e
o
f
t
h
e
a
l
i
a
s
i
n
t
h
e
s
e
r
v
i
c
e
d
e
fi
n

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
i
t
i
o
n
w
i
l
l
b
e
u
s
e
d
e
v
e
n
i
f
y
o
u
u
s
e
t
h
e
a
n
n
o
t
a
t

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
i
o
n
i
n
t
h
e
C
D
S
v
i
e
w
.

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
OSS
Dtc
aro
tip
ane
.g(
:
e1[
n2E
t8N
i)T
tI
yT
TY
y]
p
D
e
e
.
n
n
o
a
t
m
e
e
s
t
h
e
e
x
t
e
r
n
a
l
n
a
m
e
o

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
f
t
h
e
e
n
t
i
t
y
t
y
p
e
f
o
r
a
n
a
r
b
i
t
r
a
r
y
O
D
a
t
a
s
e
r
v
i

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
c
e
.


E
x
a
m
p
l
e
T
h
i
s
e
x
a
m
p
l
e
d
e
m
o
n
s
t
r
a
t
e

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
s
h
o
w
O
D
a
t
a
a
n
n
o
t
a
t
i
o
n
s
c
a
n
b
e
u
s
e
d
t
o
c
h
a
n
g
e

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
t
h
e
n
a
m
e
o
f
t
h
e
e
n
t
i
t
y
t
y
p
e
i
n
t
h
e
m
e
t
a
d
a
t
a
o
f

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
t
h
e
O
D
a
t
a
s
e
r
v
i
c
e
:
:
@
O
D
a
t
a
.
e
n
t
i
t
y
S
e
t
.
n
a
m
e
:
'
T
r

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
a
v
e
l
'

@
O
D
a
t
a
.
e
n
t
i
t
y
T
y
p
e
.
n
a
m
e
:
'
T
r
a
v
e
l
T
y
p
e
'
d
e
f
i
n
e
r
o

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
o
t
e
n
t
i
t
y
/
D
M
O
/
I
_
T
R
A
V
E
L
{
k
e
y
T
r
a
v
e
l
I
D
a
b

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
a
p
.
n
u
m
c(
)
;

…

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
OBS
Doc
o
ao
p
tl
e
ae:
.a[
enE
tdN
aeT
I
gf
T
aY
u]
l
D
t
o
t
n
r
o
u
t
e
u
s
e
t
h
i
s
a
n
n
o
t
a
t
i
o
n
.
D
e

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
c
l
a
r
e
E
T
a
g
s
i
n
b
e
h
a
v
i
o
r
d
e
fi
n
i
t
i
o
n
s
.

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
OSS
Dtc
aro
tip
ane
.g(
:
p1[
r2E
o8L
p)E
eM
rE
tN
yT
.]
ni
an
ma
eb
s
t
r
a
c
t
e
n
t
i
t
i
e
s
D
e
n
o

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
t
e
s
t
h
e
e
x
t
e
r
n
a
l
n
a
m
e
o
f
C
D
S
e
l
e
m
e
n
t
s
,
p
a
r
a
m
e

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
t
e
r
s
o
r
a
s
s
o
c
i
a
t
i
o
n
s
f
o
r
t
h
e
p
r
o
p
e
r
t
i
e
s
o
f
a
n

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
a
b
s
t
r
a
c
t
e
n
t
i
t
y
.

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
OSS
Dtc
aro
tip
ane
.g(
:
s1[
c2S
h8E
e)R
mV
aI
.C
nE
a]
m
D
e
e
n
o
t
e
s
t
h
e
e
x
t
e
r
n
a
l
n
a
m
e

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
o
f
t
h
e
s
e
r
v
i
c
e
i
n
a
n
O
D
a
t
a
r
e
p
r
e
s
e
n
t
a
t
i
o
n
.

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
T
h
i
s
a
n
n
o
t
a
t
i
o
n
i
s
u
s
e
d
i
n
s
e
r
v
i
c
e
d
e
fi
n
i
t
i
o
n

D
Ae
ns
nc
or
ti
aV p
tat
i li
ouo
nen
s
.
9.11 Search Annotations
This annotation marks a view as searchable. You define the fuzziness threshold as well as the specifics of term
mappings at element level.
@Scope:[#ENTITY]

Annotation Search
{
searchable : Boolean default true;
};
@Scope:[#ELEMENT]
Annotation Search
{
defaultSearchElement : Boolean default true;
ranking : String(6) enum { HIGH = 'high'; MEDIUM = 'medium'; LOW = 'low'; }
default #MEDIUM;
fuzzinessThreshold : Decimal(3,2);
termMappingDictionary : String(128);
termMappingListId : array of String(32);

};

Usage
Annotation Meaning
Search.searchable Defines if a CDS entity is generally relevant for search scenarios. This annotation must
be set in case other search-related annotations are being defined for elements of the
respective CDS entity. The annotation offers a general switch and a means to quickly detect
whether a view is relevant or not.
Scope: #Entity
Evaluation Runtime (Engine): Interpreted by Enterprise Search and SADL
Values:
Value Description
Boolean (true, false) Defines whether a view is relevant for search or not.
Default: true
Search.defaultSearc Specifies that the element is to be considered in a freestyle search (for example a
hElement SELECT…) where no columns are specified.
Usually, such a search must not operate on all elements – for performance reasons, and
because not all elements (e.g. internal keys) do qualify for this kind of access.
Scope: #Element
Evaluation Runtime (Engine): Interpreted by Enterprise Search and SADL
Values:
Value Description
Boolean (true, false) Defines weather the element is to be considered in a free-

style search.
Default: true
Search.ranking Specifies how relevant the values of an element are for ranking, if the freestyle search terms
match the element value.
Scope: #Element
Evaluation Runtime (Engine) : Interpreted by Enterprise Search
Values:
Value Description
HIGH The element is of high relevancy; this holds usually for ID

and their descriptions.
MEDIUM The element is of medium relevancy; this holds usually for

other, important element. This is the default.
LOW Although the element is relevant for freestyle search, a hit

in this element has no real significance for a result item's
ranking.

Annotation Meaning
Search.fuzzinessThr Specifies the least level of fuzziness (with regard to some comparison criteria passed at
eshold runtime) the element has to have to be considered in a fuzzy search at all.
 Note
A fuzzy search enables a certain degree of error tolerance and returns records even
if the search term contains additional or missing characters or other types of spelling
errors.
 Note
To perform a fuzzy search you have to set the search mode to fuzzy in the cus-
tomizing settings of your ABAP system. Find the customizing node under SAP
NetWeaver Implementation Guide Search and Operational Analytics Enterprise
Search Search Configuration Set Parameters for Federated Search .
If in the customizing a value for Fuzzy Similarity is present, the value of the
parameter Search.fuzzinessThreshold will become void.
Scope: #Element
Evaluation Runtime (Engine): Interpreted by SADL
Values:
Value Description
Decimal (3,2) The least level of fuzziness the element has to have to be
considered in a fuzzy search at all, e.g. 0.7.
The value can be between 0 and 1.
We recommend using the default value 0.7 to start with.

Later on, you can fine-tune the search settings based on
your experiences with the search. You can also fine-tune the
search using feedback collected from your users. A value
between 0.7 and 0.99 would be most useful. Use 1 for
exact matches.
Search.termMappingD Specifies the table that holds the term mappings (synonyms) to be considered in the
ictionary context of a search on this view.
Scope: #Element
Evaluation Runtime (Engine): No engine usage right now. Reserved for future usage.
Values:
Value Description
String(128) Defines the term mapping dictionary, e.g. a table or entity.

Annotation Meaning
Search.termMappingL Specifies one or multiple list IDs within the term mapping dictionary mentioned before.
istID
The list is implemented as a column of the term mapping table, with the list ID as content
of this column. This concept has the aim to enable overarching term mapping dictionaries
while being able to separate domain-specific content at the same time.
Scope: #Element
Evaluation Runtime (Engine): No engine usage right now. Reserved for future usage.
Values:
Value Description
Array of String(32) Defines one or more columns of the term mapping diction-
ary.
Example
The following example demonstrates how the search annotations are used in a CDS view.
 Sample Code

define view demo_search
as select from db_flight
{
key carrid,
key connid,
fldate,
price,
currencycode

}
The search is executed primarily on the elements carrid and fldate with a fuzziness threshold of 0.7.

9.12 Semantics Annotations
Used by the core engines for data processing and data consumption
@Scope: [#ELEMENT, #PARAMETER]

Annotation Semantics
address
{
type : array of String(10) enum
{
HOME;
WORK;
PREF;
OTHER;
};
city : Boolean default true;
street : Boolean default true;
streetNoNumber : Boolean default true;
number : Boolean default true;
country : Boolean default true;
region : Boolean default true;
subRegion : Boolean default true;
zipCode : Boolean default true;
postBox : Boolean default true;
label : Boolean default true;
};
amount
{
currencyCode : ElementRef;
};
businessDate
{
at : Boolean default true;
from : Boolean default true;
to : Boolean default true;
};
calendar
{
dayOfMonth : Boolean default true;
dayOfYear : Boolean default true;
week : Boolean default true;
month : Boolean default true;
quarter : Boolean default true;
halfyear : Boolean default true;
year : Boolean default true;
yearWeek : Boolean default true;
yearMonth : Boolean default true;
yearQuarter : Boolean default true;
yearHalfyear : Boolean default true;
};
currencyCode : Boolean default true;
dateTime : Boolean default true;
durationInDays : Boolean default true;
durationInHours : Boolean default true;
durationInMinutes : Boolean default true;
durationInSeconds : Boolean default true;
eMail
{

{
HOME;
WORK;
PREF;
OTHER;
};
address : Boolean default true;
from : Boolean default true;
sender : Boolean default true;
to : Boolean default true;
cc : Boolean default true;
bcc : Boolean default true;
subject : Boolean default true;
body : Boolean default true;
keywords : Boolean default true;
received : Boolean default true;
};
fiscal
{
yearVariant : Boolean default true;
period : Boolean default true;
year : Boolean default true;
yearPeriod : Boolean default true;
quarter : Boolean default true;
yearQuarter : Boolean default true;
week : Boolean default true;
yearWeek : Boolean default true;
dayOfYear : Boolean default true;
};
language : Boolean default true;
largeObject
{
mimeType : ElementRef;
fileName : ElementRef;
contentDispositionPreference: String(30) enum { ATTACHMENT;
INLINE; };
};
mimeType : Boolean default true;
name
{
fullName : Boolean default true;
givenName : Boolean default true;
additionalName : Boolean default true;
familyName : Boolean default true;
nickName : Boolean default true;
suffix : Boolean default true;
prefix : Boolean default true;
jobTitle : Boolean default true;
};
organization
{
name : Boolean default true;
unit : Boolean default true;
role : Boolean default true;
};
quantity
{
unitOfMeasure : ElementRef;
};
signReversalIndicator : Boolean default true;
systemDateTime
{
createdAt : Boolean default true;
lastChangedAt : Boolean default true;
localInstanceLastChangedAt : Boolean default true;
};
telephone

{
{
HOME;
CELL;
WORK;
FAX;
PREF;
TEXT;
VOICE;
VIDEO;
PAGER;
TEXT_PHONE;
};
};
text : Boolean default true;
unitOfMeasure : Boolean default true;
user
{
createdBy : Boolean default true;
lastChangedBy : Boolean default true;
localInstanceLastChangedBy : Boolean default true;
};

uuid : Boolean default true;
Usage
Semantic annotations complement the concept of semantic data types, while semantic data types always
introduce specific behavior in the provider/core infrastructure (through dedicated operations or conversion
functions).
Semantic annotations allow the standardizing of semantics that only have an impact on the consumption side
(such as currency code representation together with the amount).
Annotation Meaning
Annotations belonging to Semantics.address tag elements of addresses that can be used in contact cards.
Evaluation Runtime (Engine): Interpreted by the RAP runtime engine (SADL): Translates CDS annotations into the corre-
sponding OData annotations.
Semantics.address.type This annotation tags an element that contains an address.

[]
Scope: [ELEMENT]
Values: String(10)
The following enumerations are provided
#HOME Home address
#WORK Work address
#PREF Preferred address (default)

Annotation Meaning
OTHER other address
Semantics.address.city Boolean default true The annotated field contains a

plain-text string that contains the
name of a city.
Semantics.address.count The annotated field contains a

ry plain-text string that contains the
name of a country.
Semantics.address.label The annotated field contains a

plain-text string representing the
formatted address for printing.
Semantics.address.numbe The annotated field contains a

r street number separated from a
street name.
Semantics.address.postB The annotated field contains infor-

ox mation about a post office box.
Semantics.address.regio The annotated field contains a

n plain-text string that contains the
name of a region.
Semantics.address.stree The annotated field contains a

t street name and a street number.
Semantics.address.stree The annotated field contains a

tNoNumber street name separated from a
street number.
Semantics.address.subRe The annotated field contains a

gion plain-text string that contains the
name of a subregion.
Semantics.address.zipCo The annotated field contains a nu-

de meric string that contains the ZIP
code (type of postal code used
within the United States).
Semantics.amount.curren This annotation tags an element that contains a currency amount.

cyCode
Scope: [ELEMENT]
Evaluation Runtime (Engine): Interpreted by the RAP runtime engine (SADL). Trans-
lates CDS annotations into the corresponding OData annotations.
Values:
elementRef The annotated field contains a

monetary amount, and the cor-
responding currency code is con-
tained in the referenced field.

Annotation Meaning
Annotations belonging to Semantics.businessDate denotes dates in the business context.
Evaluation Runtime (Engine):Interpreted by the RAP runtime engine (SADL). Translates CDS annotations into the corre-
Semantics.businessDate. Boolean default true The value of the annotated field

at contains a business date referring
to a point in time.
Semantics.businessDate. The value of the annotated field

from contains a business date specify-
ing the start of a time period.
Semantics.businessDate. The value of the annotated field

to contains a business date specify-
ing the end of a time period.
Annotations belonging to Semantics.calendar follow the iCalendar standard (RFC5545 )
Evaluation Runtime (Engine): SADL: Translates CDS annotations into the corresponding OData annotations
Values: Boolean default true
Semantics.calendar.dayO Boolean default true The value of the annotated field is

fMonth a day number relative to a calen-
dar month.
 Example
1 - 31
Semantics.calendar.dayO The value of the annotated field is

fYear a day number relative to a calen-
dar year.
 Example
1 - 366
Semantics.calendar.half The value of the annotated field

year is a half year number relative to a
calendar year.
 Example
1 or 2

Annotation Meaning
Semantics.calendar.mont The value of the annotated field

h encodes a calendar month num-
ber as a string following the logical
pattern MM consisting of two dig-
its.
 Example
The string matches the regex

pattern 0[1-9]|1[0-2]
Semantics.calendar.quar The value of the annotated field

ter encodes a calendar quarter num-
ber as a string following the logi-
cal pattern Q consisting of a single
digit.
 Example

pattern [1-4]
Semantics.calendar.week The value of the annotated field

encodes a calendar week number
as a string following the logical
pattern WW consisting of two dig-
its.
 Example
The string matches the re-

gex pattern 0[1-9]|[1-4]
[0-9]|5[2-3]
Semantics.calendar.year The value of the annotated field

encodes a year number as a
string following the logical pattern
(-?)YYYY(Y*) consisting of an
optional minus sign for years B.C.,
followed by at least four digits.
 Example
The string matches the

regex pattern -?([1-9]
[0-9]{3,}|0[0-9]{3})

Annotation Meaning
Semantics.currencyCode This annotation tags a field containing a currency code
This can be either an ISO code or an SAP currency code (data type CUKY).
Semantics.dateTime This annotation tags a field containing a date with time value.
Scope: [ELEMENT,PARAMETER]
Semantics.durationInDay This annotation tags a field containing a number that describes a time period in days.
s
Semantics.durationInHou This annotation tags a field containing a number that described a time period in hours.
rs
Semantics.durationInMin This annotation tags a field containing a number that describes a time period in mi-
utes nutes.
Semantics.durationInSec This annotation tags a field containing a number that describes a time period in sec-
onds onds.

Annotation Meaning
Annotations belonging to Semantics.fiscal are required for time-based calculations in analytical use cases.
Evaluation Runtime (Engine): Some attributes contain the respective information (as plain integers), and the processor
needs the semantics in order to identify them.
Semantics.fiscal.period Boolean default true A fiscal period is covered by finan-

cial reports, for example, an an-
nual report covers a fiscal period
of one year, but a quarterly report
includes accounting data for three
months.
The value of the annotated field

encodes a fiscal period as a string
following the logical pattern PPP
consisting of three digits. This fis-
cal period usually is a quarter of a
year.
 Example

pattern [0-9]{3}
Semantics.fiscal.quarte A fiscal period is covered by finan-

r cial reports, for example, an an-
months.

encodes a fiscal quarter as a
Q consisting of one digit.
 Example

pattern [1-4]

Annotation Meaning
Semantics.fiscal.week A fiscal period is covered by finan-

cial reports, for example, an an-
months.

encodes a fiscal week as a string
following the pattern WW consist-
ing of two digits.
 Example
The string matches the re-

gex pattern 0[1-9]|[1-4][0-9]|
5[2-3]
Semantics.fiscal.year The value of the annotated field

encodes a fiscal year number as a
YYYY consisting of four digits.
 Example

pattern [1-9][0-9]{3}
Semantics.fiscal.yearPe The value of the annotated field

riod encodes a fiscal year and period
pattern YYYYPPP consisting of
seven digits. The last three digits
represent the fiscal period in the
year.
 Example

pattern ([1-9][0-9]{3})([0-9]
{3})

Annotation Meaning
Semantics.fiscal.yearQu The value of the annotated field

arter encodes a fiscal year and quarter
pattern YYYYQ consisting of five
digits. The last digit represents the
fiscal quarter in the year.
 Example

pattern ([1-9][0-9]{3,}|0[0-9]
{3})[1-4]
Semantics.fiscal.yearWe The value of the annotated field

ek encodes a fiscal year and period
pattern YYYYWW consisting of
seven digits. The last three digits
represent the fiscal period in the
year.
 Example

pattern ([1-9][0-9]{3,}|0[0-9]
{3})(0[1-9]|[1-4][0-9]|5[2-3])
Semantics.fiscal.yearVa The value of the annotated field

riant encodes a fiscal year variant,
which describes the number of pe-
riods in a fiscal year and how they
match the calendar year.
Semantics.language This annotation identifies a language.
Annotations belonging to Semantics.organization tag elements that refer to details about an organization.
Evaluation Runtime (Engine):Interpreted by the RAP runtime engine (SADL). Translates CDS annotations into the corre-
Semantics.organization. Boolean default true The value of the annotated field

name contains the organization name.

Annotation Meaning
Semantics.organization. The value of the annotated field

role specify the function or part played
in a particular situation by the ob-
ject the vCard represents.
 Example
ROLE:Project Leader
Semantics.organization. The value of the annotated field

unit contains the name of the organi-
zation unit.
Semantics.quantity.unit This annotation tags an element that contains a measured quantity.

OfMeasure
Values:
elementRef The value of the annotated field

references a unit of measure re-
lated to a measured quantity.
Semantics.signReversalI This annotation reverses the sign of the annotated view element
ndicator
This annotation is used in analytical queries of CDS view with

@ObjectModel.dataCatagory: #HIERARCHY annotations.
Values: Boolean (default true)
Annotations belonging to Semantics.systemDate tag elements that specify the date/time that is recorded by the
technical infrastructure/database.
Evaluation Runtime (Engine): Interpreted by the RAP runtime engine (SADL). Translates CDS annotations into the corre-
Semantics.systemDateTim The annotated element contains a timestamp indicating when the database record
e.createdAt was created.
e.lastChangedAt was last changed.
The annotated element is used for the total ETag field in managed scenarios with draft.
It is automatically updated by the RAP managed runtime framework.

Annotation Meaning
e.LocalInstanceLastChan was last changed.
gedAt
The annotated element is used for the ETag master field in managed scenarios. It is
automatically updated by the RAP managed runtime framework.
Semantics.text This annotation identifies a human-readable text that is not necessarily language-de-
pendent.
Semantics.unitOfMeasure This annotation tags a field as containing a unit of measure.
Annotations belonging to Semantics.user tag elements that define the ID of the user related to the data record.
Evaluation Runtime (Engine): Interpreted by the RAP runtime engine (SADL). Translates CDS annotations into the corre-
Semantics.user.createdB The value of the annotated field specifies the user who created a data record.
y
Semantics.user.lastChan The value of the annotated field specifies the user who changed a data record at last.
gedBy
Semantics.user.localIns The value of the annotated field specifies the user who changed a data record at last.
tanceLastChangedBy
Semantics.url.mimeType This annotated field contains a URL and the value is the mime type of the resource
addressed by the URL. A mime type is required when opening a document for viewing,
or when accessing document content during text analysis. In UIs, documents are
usually presented with an icon that symbolizes their mime type.”

Annotation Meaning
Semantics.mimeType The annotated field contains a mime type. It is required when opening a document for
viewing, or when accessing document content during text analysis. In UIs, documents
are usually presented with an icon that symbolizes their mime type.
Values:Boolean default true
Semantics.largeObject.f The annotation references an optional field containing the file name of a mime object.
ileName
Values:String(30) enum
Semantics.largeObject.a The annotation provides a list of acceptable mime types for the related stream prop-
cceptableMimeType erty to restrict or verify the user entry accordingly. If any subtype is accepted, this can
be indicated by *.
Values:Array of String(255)
Examples
Example 1
The following CDS view fetches sales order items. Here, the annotations assign the units and currencies to the
corresponding fields.
 Sample Code
DEFINE VIEW SalesOrderItem as select from ...

{
...
@Semantics.currencyCode
gross_amount as GrossAmount,
@Semantics.unitOfMeasure
unit_of_measure as UnitOfMeasure,
@Semantics.quantity.unitOfMeasure: 'UnitOfMeasure'
quantity as Quantity,
...

}
Example 2
The following CDS view fetches language-dependant data annotating the corresponding language fields and
text fields:
 Sample Code
DEFINE VIEW chartOfAccountsTexts AS SELECT FROM ...

{

key ktopl AS chartOfAccounts,
key spras AS language,
ktplt AS chartOfAccountsName

}
9.13 UI Annotations
Represent semantic views on business data through the use of specific patterns that areindependent of UI
technologies.
 Sample Code
@MetadataExtension.usageAllowed : true

{
@Scope:[#ENTITY]
headerInfo
{
@LanguageDependency.maxLength : 40
typeName : String(60);
typeNamePlural : String(60);
typeImageUrl : String(1024);
imageUrl : ElementRef;
title
{
type : String(40) enum
{
STANDARD;
WITH_INTENT_BASED_NAVIGATION;
WITH_NAVIGATION_PATH;
WITH_URL;
} default #STANDARD;
label : String(60);
iconUrl : String(1024);
criticality : ElementRef;
criticalityRepresentation : String(12) enum
{
WITHOUT_ICON;
WITH_ICON;
} default #WITHOUT_ICON;
value : ElementRef;
targetElement : ElementRef;
url : ElementRef;
};
description
{
{
STANDARD;

WITH_URL;
label : String(60);
{
WITHOUT_ICON;
WITH_ICON;
value : ElementRef;
url : ElementRef;
};
};
@Scope:[#ENTITY]
badge
{
headLine
{
{
STANDARD;
WITH_URL;
label : String(60);
{
WITHOUT_ICON;
WITH_ICON;
value : ElementRef;
url : ElementRef;
};
title
{
{
STANDARD;
WITH_URL;
label : String(60);
{
WITHOUT_ICON;
WITH_ICON;
value : ElementRef;
url : ElementRef;
};
typeImageUrl : String(1024);
imageUrl : ElementRef;
mainInfo
{

{
STANDARD;
WITH_URL;
label : String(60);
{
WITHOUT_ICON;
WITH_ICON;
value : ElementRef;
url : ElementRef;
};
secondaryInfo
{
{
STANDARD;
WITH_URL;
label : String(60);
{
WITHOUT_ICON;
WITH_ICON;
value : ElementRef;
url : ElementRef;
};
};
@Scope:[#ENTITY]
chart : array of
{
qualifier : String(120);
title : String(60);
description : String(120);
chartType : String(40) enum
{
COLUMN;
COLUMN_STACKED;
COLUMN_STACKED_100;
COLUMN_DUAL;
COLUMN_STACKED_DUAL;
COLUMN_STACKED_DUAL_100;
BAR;
BAR_STACKED;
BAR_STACKED_100;
BAR_DUAL;
BAR_STACKED_DUAL;
BAR_STACKED_DUAL_100;
AREA;
AREA_STACKED;
AREA_STACKED_100;

HORIZONTAL_AREA;
HORIZONTAL_AREA_STACKED;
HORIZONTAL_AREA_STACKED_100;
LINE;
LINE_DUAL;
COMBINATION;
COMBINATION_STACKED;
COMBINATION_STACKED_DUAL;
HORIZONTAL_COMBINATION_STACKED;
HORIZONTAL_COMBINATION_STACKED_DUAL;
PIE;
DONUT;
SCATTER;
BUBBLE;
RADAR;
HEAT_MAP;
TREE_MAP;
WATERFALL;
BULLET;
VERTICAL_BULLET;
HORIZONTAL_WATERFALL;
HORIZONTAL_COMBINATION_DUAL;
DONUT_100;
};
dimensions : array of ElementRef;
measures : array of ElementRef;
dimensionAttributes : array of
{
dimension : ElementRef;
role : String(10) enum
{
CATEGORY;
SERIES;
CATEGORY2;
};
valuesForSequentialColorLevels: array of String(1024);
emphasizedValues: array of String(1024);
};
measureAttributes : array of
{
measure : ElementRef;
role : String(10) enum
{
AXIS_1;
AXIS_2;
AXIS_3;
};
asDataPoint : Boolean default true;
useSequentialColorLevels: Boolean default true;
};
actions : array of
{
{
FOR_ACTION;
FOR_INTENT_BASED_NAVIGATION;
};
label : String(60);
dataAction : String(120);
requiresContext : Boolean default true;
invocationGrouping : String(12) enum
{
ISOLATED;
CHANGE_SET;
} default #ISOLATED;
semanticObjectAction : String(120);
};

};
@Scope:[#ENTITY]
selectionPresentationVariant : array of
{
id : String(120);
text : String(60);
selectionVariantQualifier : String(120);
presentationVariantQualifier : String(120);
};
@Scope:[#ENTITY]
selectionVariant : array of
{
id : String(120);
text : String(60);
parameters : array of
{
name : ParameterRef;
};
filter : String(1024);
};
@Scope:[#ENTITY]
presentationVariant : array of
{
id : String(120);
text : String(60);
maxItems : Integer;
sortOrder : array of
{
by : ElementRef;
direction : String(4) enum
{
ASC;
DESC;
};
};
groupBy : array of ElementRef;
totalBy : array of ElementRef;
total : array of ElementRef;
includeGrandTotal : Boolean default true;
initialExpansionLevel : Integer;
requestAtLeast : array of ElementRef;
visualizations : array of
{
{
AS_LINEITEM;
AS_CHART;
AS_DATAPOINT;
};
element : ElementRef;
};
selectionFieldsQualifier : String(120);
};
@Scope:[#ELEMENT]
masked : Boolean default true;
@Scope:[#ELEMENT]
multiLineText : Boolean default true;
@Scope:[#ELEMENT]

lineItem : array of
{
@Scope: [#ELEMENT, #ENTITY]
position : DecimalFloat;
exclude : Boolean default true;
importance : String(6) enum { HIGH; MEDIUM; LOW; };
{
AS_ADDRESS;
AS_CHART;
AS_CONNECTED_FIELDS;
AS_CONTACT;
AS_DATAPOINT;
AS_FIELDGROUP;
FOR_ACTION;
STANDARD;
WITH_URL;
label : String(60);
@Scope: [#ELEMENT, #ENTITY]
{
WITHOUT_ICON;
WITH_ICON;
invocationGrouping : String(12) enum { ISOLATED; CHANGE_SET; }
default #ISOLATED;
value : ElementRef;
valueQualifier : String(120);
url : ElementRef;
};
@Scope:[#ELEMENT]
identification : array of
{
{
AS_ADDRESS;
AS_CHART;
AS_CONTACT;
AS_DATAPOINT;
AS_FIELDGROUP;
FOR_ACTION;
STANDARD;
WITH_URL;
label : String(60);

{
WITHOUT_ICON;
WITH_ICON;
default #ISOLATED;
value : ElementRef;
url : ElementRef;
};
@Scope:[#ELEMENT]
statusInfo : array of
{
{
AS_ADDRESS;
AS_CHART;
AS_CONTACT;
AS_DATAPOINT;
AS_FIELDGROUP;
FOR_ACTION;
STANDARD;
WITH_URL;
label : String(60);
{
WITHOUT_ICON;
WITH_ICON;
default #ISOLATED;
value : ElementRef;
url : ElementRef;
};
@Scope:[#ELEMENT]
fieldGroup : array of
{
groupLabel : String(60);
{
AS_ADDRESS;
AS_CHART;

AS_CONTACT;
AS_DATAPOINT;
AS_FIELDGROUP;
FOR_ACTION;
STANDARD;
WITH_URL;
label : String(60);
{
WITHOUT_ICON;
WITH_ICON;
default #ISOLATED;
value : ElementRef;
url : ElementRef;
};
@Scope:[#ELEMENT]
dataPoint
{
title : String(60);
longDescription : String(250);
targetValue : DecimalFloat;
targetValueElement : ElementRef;
forecastValue : ElementRef;
minimumValue : DecimalFloat;
maximumValue : DecimalFloat;
visualization : String(12) enum
{
NUMBER;
BULLET_CHART;
DONUT;
PROGRESS;
RATING;
};
valueFormat
{
scaleFactor : DecimalFloat;
numberOfFractionalDigits : Integer;
};
referencePeriod
{
start : ElementRef;
end : ElementRef;
};
criticalityValue : Integer enum
{

NEGATIVE;
CRITICAL;
POSITIVE;
};
{
WITHOUT_ICON;
WITH_ICON;
criticalityCalculation
{
improvementDirection : String(8) enum
{
MINIMIZE;
TARGET;
MAXIMIZE;
};
acceptanceRangeLowValue : DecimalFloat;
acceptanceRangeHighValue : DecimalFloat;
toleranceRangeLowValue : DecimalFloat;
toleranceRangeLowValueElement : ElementRef;
toleranceRangeHighValue : DecimalFloat;
toleranceRangeHighValueElement : ElementRef;
deviationRangeLowValue : DecimalFloat;
deviationRangeLowValueElement : ElementRef;
deviationRangeHighValue : DecimalFloat;
deviationRangeHighValueElement : ElementRef;
constantThresholds: array of
{
aggregationLevel: array of ElementRef;
acceptanceRangeLowValue: DecimalFloat;
acceptanceRangeHighValue: DecimalFloat;
toleranceRangeLowValue: DecimalFloat;
toleranceRangeHighValue: DecimalFloat;
deviationRangeLowValue: DecimalFloat;
deviationRangeHighValue: DecimalFloat;
};
};
trend : ElementRef;
trendCalculation
{
referenceValue : ElementRef;
isRelativeDifference : Boolean default true;
upDifference : DecimalFloat;
upDifferenceElement : ElementRef;
strongUpDifference : DecimalFloat;
strongUpDifferenceElement : ElementRef;
downDifference : DecimalFloat;
downDifferenceElement : ElementRef;
strongDownDifference : DecimalFloat;
strongDownDifferenceElement : ElementRef;
};
responsible : ElementRef;
responsibleName : String(120);
};
@Scope:[#ELEMENT]
selectionField : array of
{
element : ElementRef;
};
@Scope:[#ELEMENT]
facet : array of
{

@CompatibilityContract: {
c1: { usageAllowed: false },
c2: { usageAllowed: true,
allowedChanges.annotation: [ #REMOVE ],
allowedChanges.value: [ #NONE ]} }
feature : String(40);
id : String(120);
purpose : String(40) enum
{
STANDARD;
HEADER;
QUICK_VIEW;
QUICK_CREATE;
FILTER;
parentId : String(120);
isPartOfPreview : Boolean default true;
isSummary : Boolean default true;
isMap : Boolean default true;
importance : String(6) enum
{
HIGH;
MEDIUM;
LOW;
};
label : String(60);
{
COLLECTION;
ADDRESS_REFERENCE;
BADGE_REFERENCE;
CHART_REFERENCE;
CONTACT_REFERENCE;
DATAPOINT_REFERENCE;
FIELDGROUP_REFERENCE;
HEADERINFO_REFERENCE;
IDENTIFICATION_REFERENCE;
LINEITEM_REFERENCE;
STATUSINFO_REFERENCE;
URL_REFERENCE;
};
targetQualifier : String(120);
url : ElementRef;
};
@Scope:[#ENTITY, #ELEMENT]
textArrangement : String(13) enum
{
TEXT_FIRST;
TEXT_LAST;
TEXT_ONLY;
TEXT_SEPARATE;
};
//=================================================
// Version 7.69
//=================================================
@Scope: [#ELEMENT]
kpi : array of
{
id : String(120);
@LanguageDependency.maxLength: 10
shortDescription : String(20);
selectionVariantQualifier : String(120);

detail
{
defaultPresentationVariantQualifier : String(120);
alternativePresentationVariantQualifiers : array of String(120);
semanticObject : String(120);
};
dataPoint
{
title : String(60);
longDescription : String(250);
targetValue : DecimalFloat;
forecastValue : DecimalFloat;
minimumValue : DecimalFloat;
maximumValue : DecimalFloat;
valueFormat
{
scaleFactor : DecimalFloat;
numberOfFractionalDigits : Integer;
};
visualization : String(12) enum
{
NUMBER;
BULLET_CHART;
DONUT;
PROGRESS;
RATING;
};
referencePeriod {
start : ElementRef;
end : ElementRef;
};
criticalityValue : Integer enum
{
NEGATIVE;
CRITICAL;
POSITIVE;
};
{
WITHOUT_ICON;
WITH_ICON;
criticalityCalculation
{
improvementDirection : String(8) enum
{
MINIMIZE;
TARGET;
MAXIMIZE;
};
constantThresholds : array of
{
aggregationLevel : array of ElementRef;

};
};
trend : ElementRef;
trendCalculation
{
referenceValue : ElementRef;
isRelativeDifference : Boolean ;
upDifference : DecimalFloat;
strongUpDifference : DecimalFloat;
downDifference : DecimalFloat;
strongDownDifference : DecimalFloat;
};
responsible : ElementRef;
responsibleName: String(120);
};
};
@Scope: [#ELEMENT]
valueCriticality: array of
{
criticality : Integer enum
{
NEGATIVE;
CRITICAL;
POSITIVE;
};
};
@Scope: [#ELEMENT]
criticalityLabels : array of {
qualifier: String(120);
criticality: Integer enum
{
NEGATIVE;
CRITICAL;
POSITIVE;
};
label: String(60);
};
@Scope: [#ELEMENT]
connectedFields : array of
{
groupLabel : String(60);
template : String(255);
name : String(120);
{
AS_ADDRESS;
AS_CHART;
AS_CONTACT;
AS_DATAPOINT;

AS_FIELDGROUP;
FOR_ACTION;
STANDARD;
WITH_URL;
label : String(60);
{
WITHOUT_ICON;
WITH_ICON;
default #ISOLATED;
value : ElementRef;
url : ElementRef;
};
};

Usage
The focus of OData UI vocabulary developed by SAP is on usage patterns of data in UIs, not on UI patterns.
The vocabulary is completely independent of the UI technologies or devices that consume the data. The usage
patterns of data used by the OData UI vocabulary represent certain semantic views on business data. Some
of them are very generic, others are based on the concept of an entity, something tangible to end-users.
Examples for entities are semantic object instances or business object instances. Looking at different UI
patterns, these data usage patterns reoccur again and again. To generate OData annotations from CDS views,
CDS annotations are reused from different domains, for example Consumption, Communication, Semantics,
EndUserText. The CDS annotations that are additionally required in a UI domain are listed in the following table.

UI Annotations
Parent Annotation Annotation Type Value Description
UI.headerInfo Annotations belonging

to UI.headerInfo de-
scribe an entity, its ti-
tle, and an optional
short description, the
name of its entity
in singular and plural
form, and optional im-
age URLs for the indi-
vidual entity.
Scope:ENTITY
Evaluation Runtime
(Engine): SADL:
Translates CDS anno-
tations into the corre-
sponding OData anno-
tations
Values:
UI.headerInfo .typeName String(60) #mandatory This annotation repre-

sents the title of an ob-
 Note
ject page, for example.
This annotation can
be omitted only
when the @End-
UserText.label is
specified on view
level.
UI.headerInfo typeNamePlural String(60) #mandatory This annotation repre-

sents a list title, for ex-
ample.

UI.headerInfo typeImageUrl String(1024) #optional This annotation con-

tains the URL of an
image representing an
entity. Alternatively,
you can reference a
variable that contains
the URL to the image,
e.g. a field.
 Note
When users open

a SAP Fiori appli-
cation, they can
see an image re-
lated to the en-
tity type to which
all items displayed
on that page be-
long to.
UI.headerInfo imageUrl elementRef #optional This annotation con-

sists of an URL or a
path representing the
entity instance.
UI.headerInfo imageData elementRef This annotation allows

referencing an ele-
ment that contains the
image BLOB and is it-
self annotated with
Semantics.large
Object.
UI.headerInfo title.

UI.headerInfo title.type String(40) enum • STANDARD: Annotations belonging

Maps to standard to UI.headerInfo.title
DataField. You use represent a property
this type if you want of type UI.DataFiel-
a field to be dis- dAbstract restricted
played without any to the types STAND-
additional function- ARD, WITH_NAV-
ality. IGATION_PATH,
A standard WITH_URL,
DataField refers to and WITH_IN-
a property of the TENT_BASED_NAVI-
OData service used. GATION. @UI.header-
When you use this Info.title annotations
type, you can use are mandatory and are
the following ele- usually used to repre-
ments: sent the title of an item
• label on the header of an
• value item's object page..
• criticality The OData anno-

• WITH_URL: Maps to tations DataFieldAb-
DataFieldWithURL. stract are the basis for
DataFieldWithURL all DataField types and
is based on represent values with
DataField, and de- optional labels that
fines a label–value can trigger navigation
pair that refers a to related data, or exe-
property of the cute actions on data.
OData service used.
The definition con-
sists a URL to nav-
igate to a new tar-
get, that is a URL.
For more informa-
tion, see With URL
[page 844].
When you use this
type, you can use
the following ele-
ments:
• label
• value
When you use this
type, you must use
the following ele-
ments:

• url
• WITH_NAVIGATION
_PATH:Maps to
DataFieldWithNavig
ationPath.
DataFieldWithNavig
ationPath is based
on DataField, and
defines a label-
value pair that re-
fers to a property of
the OData service
used. The definition
consists of a link to
navigate to a new
target, based on a
navigation property
provided by the
OData service, or
defined in the anno-
tation file.
For more informa-
tion, see With Nav-
igation Path [page
842].
When you use this
type, you can use
the following ele-
ments:
• label
• value
When you use this
type, you must use
the following ele-
ments:
• targetElement
• WITH_IN-
TENT_BASED_NAV
IGATION;
Default: STANDARD;

UI.headerInfo title.label String(60) #optional This annotation con-

tains a language-de-
pendent text that can
be used for titles in
page headers of ob-
ject-page floorplans.
Object-page floorplans
are SAP Fiori floorplan
to view, edit and create
objects.
If omitted, the label

of the annotated ele-
ment, or the label of
the element are refer-
enced via the value.
UI.headerInfo title.iconUrl String(1024) #optional This annotation con-

tains the URL to an
icon image.
UI.headerInfo title.criticality elementRef This annotation referen-

 Note
ces to another element
that has the values 0, 1, This annotation
2, or 3. can be specified
if the badge
• Neutral : 0
headline type is
• Negative: 1 STANDARD.
• Critical : 2
• Positive: 3
UI.headerInfo title.criticalityRepresen String(12) enum #mandatory

tation
• WITHOUT_ICON
• WITH_ICON
Default:
WITHOUT_ICON
UI.headerInfo title.value ElementRef This annotation refers

to a value. If you refer
to a value that is in the
same view, specify the
element name. If you
use an association to
refer to a value, spec-
ify the path to the ele-
ment.

UI.headerInfo title.targetElement ElementRef This annotation repre-

sents the path to an el-
ement of an associ-
ated CDS view. The
path is converted to an
OData
NavigationPropertyPat
h. Using This annota-
tion, you can link from
the header part of an
object view floorplan
to a target element.
You need to specify
UI.badge.headLine.targ
etElement when you
use the annotation
UI.badge.headLine.typ
e of type
WITH_NAVIGATION_P
ATH. You might, for ex-
ample, provide back-
ground information to
an item that is opened
on the object view
floorplan.
UI.headerInfo title.url ElementRef This annotation repre-

sents the path to a
structural element
that contains a naviga-
tion URL. You need to
specify
UI.badge.headLine.url
when you use the an-
notation
e of type WITH_URL.
UI.headerInfo description

UI.headerInfo description.type String(40) enum • STANDARD: Annotations belonging


OData service used.
The definition con-
sists a URL to nav-
igate to a new tar-
get, that is a URL.
For more informa-
tion, see With URL
[page 844].
When you use this
type, you can use
the following ele-
ments:
• label
• value
When you use this
type, you must use
the following ele-
ments:

• url
• WITH_NAVIGATION
_PATH:Maps to
DataFieldWithNavig
ationPath.
DataFieldWithNavig
ationPath is based
on DataField, and
defines a label-
value pair that re-
the OData service
navigate to a new
target, based on a
navigation property
provided by the
OData service, or
tation file.
For more informa-
tion, see With Nav-
igation Path [page
842].
When you use this
type, you can use
the following ele-
ments:
• label
• value
When you use this
type, you must use
the following ele-
ments:
• targetElement
• WITH_IN-
TENT_BASED_NAV
IGATION;
Default: STANDARD;

UI.headerInfo description.label String(60) #optional This annotation con-

page headers of ob-
objects.

UI.headerInfo description.iconUrl String(1024) #optional This annotation con-

tains the URL to an
icon image.
UI.headerInfo description.criticality elementRef This annotation referen-

 Note
if the badge
• Neutral : 0
headline type is
• Critical : 2
• Positive: 3
UI.headerInfo description.criticalityR String(12) enum #mandatory

epresentation
• WITHOUT_ICON
• WITH_ICON
Default:
WITHOUT_ICON
UI.headerInfo description.value ElementRef This annotation refers

ment.

UI.headerInfo description.targetElem ElementRef This annotation repre-

ent sents the path to an el-
ement of an associ-
ated CDS view. The
OData
You need to specify
etElement when you
use the annotation
e of type
WITH_NAVIGATION_P
on the object view
floorplan.
UI.headerInfo description.url ElementRef This annotation repre-

sents the path to a
structural element
specify
notation
e of type WITH_URL.

UI.badge .headLine.type String(40) enum • STANDARD: This annotation is

Maps to standard used to define, what
can be shown in the ti-
DataField. You use
tle of a table or
this type if you want
list.UI.badge.headLine
a field to be dis- represent a property
played without any of type
additional function- UI.DataFieldAbstract
ality. restricted to the types
STANDARD,
A standard
WITH_NAVIGATION_P
DataField refers to
ATH, and WITH_URL.
a property of the
OData service used. The OData
When you use this annotations
type, you can use DataFieldAbstract are
the following ele- the basis for all
ments: DataField types and
represent values with
• label
optional labels that
• value
can trigger navigation
• criticality to related data, or exe-
• WITH_URL: Maps to cute actions on data.
DataFieldWithURL.
DataFieldWithURL
is based on
DataField, and de-
fines a label–value
pair that refers a
property of the
OData service used.
The definition con-
sists a URL to nav-
igate to a new tar-
get, that is a URL.
For more informa-
tion, see With URL
[page 844].
When you use this
type, you can use
the following ele-
ments:
• label
• value
When you use this
type, you must use
the following ele-
ments:

• url
• WITH_NAVIGATION
_PATH:Maps to
DataFieldWithNavig
ationPath.
DataFieldWithNavig
ationPath is based
on DataField, and
defines a label-
value pair that re-
the OData service
navigate to a new
target, based on a
navigation property
provided by the
OData service, or
tation file.
For more informa-
tion, see With Nav-
igation Path [page
842].
When you use this
type, you can use
the following ele-
ments:
• label
• value
When you use this
type, you must use
the following ele-
ments:
• targetElement
• WITH_IN-
TENT_BASED_NAV
IGATION;
Default: STANDARD;

UI.badge .headLine.label String (60) #Optional This annotation con-

pendent text. If omit-
ted, the label of the
annotated element, or
the label of the ele-
ment referenced via
the value is used. The
element is optional.
UI.badge .headLine.iconURL String (1024) #Optional This annotation con-

tains the URL to an
icon image. This anno-
tation is optional.
UI.badge .headLine.criticality ElementRef This annotation referen-

 Note
if the badge
• Neutral : 0
headline type is
• Critical : 2
• Positive: 3
UI.badge .headLine.criticalityRe String(12) enum • WITHOUT_ICON

presentation
• WITH_ICON
Default:
WITHOUT_ICON
UI.badge .headLine.value ElementRef This annotation refers

ment.

UI.badge .headLine.targetEleme ElementRef This annotation repre-

nt sents the path to an el-
ement of an associ-
ated CDS view. The
OData
You need to specify
etElement when you
use the annotation
e of type
WITH_NAVIGATION_P
on the object view
floorplan.
UI.badge .headLine.url ElementRef This annotation repre-

sents the path to a
structural element
specify
notation
e of type WITH_URL.
UI.badge title.

UI.badge title.type String(40) enum • STANDARD: Annotations belonging


OData service used.
The definition con-
sists a URL to nav-
igate to a new tar-
get, that is a URL.
For more informa-
tion, see With URL
[page 844].
When you use this
type, you can use
the following ele-
ments:
• label
• value
When you use this
type, you must use
the following ele-
ments:

• url
• WITH_NAVIGATION
_PATH:Maps to
DataFieldWithNavig
ationPath.
DataFieldWithNavig
ationPath is based
on DataField, and
defines a label-
value pair that re-
the OData service
navigate to a new
target, based on a
navigation property
provided by the
OData service, or
tation file.
For more informa-
tion, see With Nav-
igation Path [page
842].
When you use this
type, you can use
the following ele-
ments:
• label
• value
When you use this
type, you must use
the following ele-
ments:
• targetElement
• WITH_IN-
TENT_BASED_NAV
IGATION;
Default: STANDARD;

UI.badge title.label String(60) #optional This annotation con-

page headers of ob-
objects.

UI.badge title.iconUrl String(1024) #optional This annotation con-

tains the URL to an
icon image.
UI.badge title.criticality elementRef This annotation referen-

 Note
if the badge
• Neutral : 0
headline type is
• Critical : 2
• Positive: 3
UI.badge title.criticalityRepresen String(12) enum #mandatory

tation
• WITHOUT_ICON
• WITH_ICON
Default:
WITHOUT_ICON
UI.badge title.value ElementRef This annotation refers

ment.

UI.badge title.targetElement ElementRef This annotation repre-

sents the path to an el-
ement of an associ-
ated CDS view. The
OData
You need to specify
etElement when you
use the annotation
e of type
WITH_NAVIGATION_P
on the object view
floorplan.
UI.badge title.url ElementRef This annotation repre-

sents the path to a
structural element
specify
notation
e of type WITH_URL.
UI.badge typeImageUrl String(1024); #optional This annotation con-

tains the URL of an
image representing an
entity. Alternatively,
you can reference a
variable that contains
the URL to the image,
e.g. a field.

UI.badge imageUrl ElementRef #optional This annotation repre-

sents a path to an el-
ement containing the
URL of an image rep-
resenting the entity in-
stance.
UI.badge mainInfo The content of

UI.badge.mainInfo an-
notations is high-
lighted on the badge.
These annotations
represent a property
of type UI.DataFiel-
dAbstract restricted
to the types STAND-
ARD, WITH_NAVIGA-
TION_PATH, and
WITH_URL.
The OData anno-

tations DataFieldAb-
stract are the basis for
all DataField types and
to related data, or exe-
cute actions on data.

UI.badge mainInfo.type String(40) enum • STANDARD: Annotations belonging


OData service used.
The definition con-
sists a URL to nav-
igate to a new tar-
get, that is a URL.
For more informa-
tion, see With URL
[page 844].
When you use this
type, you can use
the following ele-
ments:
• label
• value
When you use this
type, you must use
the following ele-
ments:

• url
• WITH_NAVIGATION
_PATH:Maps to
DataFieldWithNavig
ationPath.
DataFieldWithNavig
ationPath is based
on DataField, and
defines a label-
value pair that re-
the OData service
navigate to a new
target, based on a
navigation property
provided by the
OData service, or
tation file.
For more informa-
tion, see With Nav-
igation Path [page
842].
When you use this
type, you can use
the following ele-
ments:
• label
• value
When you use this
type, you must use
the following ele-
ments:
• targetElement
• WITH_IN-
TENT_BASED_NAV
IGATION;
Default: STANDARD;

UI.badge mainInfo.label String(60) #optional This annotation con-

page headers of ob-
objects.

UI.badge mainInfo.iconUrl String(1024) #optional This annotation con-

tains the URL to an
icon image.
UI.badge mainInfo.criticality elementRef This annotation referen-

 Note
if the badge
• Neutral : 0
headline type is
• Critical : 2
• Positive: 3
UI.badge mainInfo.criticalityRep String(12) enum #mandatory

resentation
• WITHOUT_ICON
• WITH_ICON
Default:
WITHOUT_ICON
UI.badge mainInfo.value ElementRef This annotation refers

ment.

UI.badge mainInfo.targetElemen ElementRef This annotation repre-

t sents the path to an el-
ement of an associ-
ated CDS view. The
OData
You need to specify
etElement when you
use the annotation
e of type
WITH_NAVIGATION_P
on the object view
floorplan.
UI.badge mainInfo.url ElementRef This annotation repre-

sents the path to a
structural element
specify
notation
e of type WITH_URL.

UI.badge secondaryInfo The content

of UI.badge.secondar-
yInfo annotations
is subordinate to
the content of the
UI.badge.mainInfo an-
notations. This an-
notation represents
a property of
type UI.DataFieldAb-
stract restricted to
the types STAND-
ARD, WITH_NAVIGA-
TION_PATH, and
WITH_URL.
The OData anno-

tations DataFieldAb-
stract are the basis for
all DataField types and
to related data, or exe-
cute actions on data.

UI.badge secondaryInfo.type String(40) enum • STANDARD: Annotations belonging


OData service used.
The definition con-
sists a URL to nav-
igate to a new tar-
get, that is a URL.
For more informa-
tion, see With URL
[page 844].
When you use this
type, you can use
the following ele-
ments:
• label
• value
When you use this
type, you must use
the following ele-
ments:

• url
• WITH_NAVIGATION
_PATH:Maps to
DataFieldWithNavig
ationPath.
DataFieldWithNavig
ationPath is based
on DataField, and
defines a label-
value pair that re-
the OData service
navigate to a new
target, based on a
navigation property
provided by the
OData service, or
tation file.
For more informa-
tion, see With Nav-
igation Path [page
842].
When you use this
type, you can use
the following ele-
ments:
• label
• value
When you use this
type, you must use
the following ele-
ments:
• targetElement
• WITH_IN-
TENT_BASED_NAV
IGATION;
Default: STANDARD;

UI.badge secondaryInfo.label String(60) #optional This annotation con-

page headers of ob-
objects.

UI.badge secondaryInfo.iconUrl String(1024) #optional This annotation con-

tains the URL to an
icon image.
UI.badge secondaryInfo.criticalit elementRef This annotation referen-

y  Note
if the badge
• Neutral : 0
headline type is
• Critical : 2
• Positive: 3
UI.badge secondaryInfo.criticalit String(12) enum #mandatory

yRepresentation
• WITHOUT_ICON
• WITH_ICON
Default:
WITHOUT_ICON
UI.badge secondaryInfo.value ElementRef This annotation refers

ment.

UI.badge secondaryInfo.targetEl ElementRef This annotation repre-

ement sents the path to an el-
ement of an associ-
ated CDS view. The
OData
You need to specify
etElement when you
use the annotation
e of type
WITH_NAVIGATION_P
on the object view
floorplan.
UI.badge secondaryInfo.url ElementRef This annotation repre-

sents the path to a
structural element
specify
notation
e of type WITH_URL.
UI.datapoint qualifier String(120)

UI.datapoint title String(60) #mandatory This annotation con-
tains the title of the
 Note
data point.
The element can be
omitted only if the
@EndUserText.label
is specified.

UI.datapoint description String(120) #optional This annotation con-

tains a description
of the data point.
If omitted, the @End-
UserText.quickinfo is
used, if specified.
UI.datapoint longDescription String(250) #optional This annotation con-

tains a detailed de-
scription of the data
point.
UI.datapoint targetValue DecimalFloat #not compatible with This annotation speci-

UI.dataPoint.targetValue
fies the target value
of the data point as a
 Caution
constant element.
If you use this an-
notation, do not
 Tip
use the element
UI.dataPoint.target- You create a KPI in
ValueElement. which you specify
a certain revenue
that needs to be
reached at the end
of a specific year.
This is the UI.data-
Point.targetValue
that is a static
value
UI.datapoint forecastValue ElementRef This annotation refer-

ences a value such as
predicted or intended
quarterly results, for
example.
UI.datapoint minimumValue DecimalFloat This annotation speci-

fies the minimum
value of a threshold.
UI.datapoint maximumValue DecimalFloat This annotation speci-

fies the maximum
value of a threshold.

UI.datapoint valueFormat DecimalFloat #optional All

UI.dataPoint.valueFor
mat annotations are
optional. For more in-
formation about value
formats, see Person
Responsible and Ref-
erence Period [page
837].
UI.datapoint valueFormat.scaleFact DecimalFloat #optional This annotation con-

or
tains the scale factor
for the value, e.g. A
value 1000 displayed
with scaleFactor =
1000 is displayed as
1k.
UI.datapoint valueFormat.numberO Integer #optional This annotation con-

fFractionalDigits
tains the number of
fractional digits to be
displayed. If the ele-
ment value is 1, one
decimal place is ren-
dered, for example,
34.5.

UI.datapoint visualization String(12) enum • NUMBER: A data This annotation de-

point is visualized fines the preferred vis-
as a number.
ualization of a data
point.
 Caution
The following
visulizations re-
quire the anno-
tation UI.data-
Point.target-
Value.
• BULLET_CHART: A
data point is visual-
ized as a bullet
chart.
• DONUT:A data
point is visualized
as a donut chart.
• PROGRESS: A data
point is visualized
as a progress indi-
cator.
• RATING: A data
point is visualized
as partly or com-
pletely filled sym-
bols such as stars
or hearts.

UI.datapoint withCriticalityLabels Boolean #optional This annotation adds

(default: true) an optional Boolean el-
ement withCriticality-
Labels to indicate that
an annotation UI.crit-
icalityLabels at the
same view element
shall be used for pro-
viding custom critical-
ity labels. By default,
UI clients, such as
the Chart UI5, which
control rendering da-
tapoint criticality, ap-
ply predefined static
texts as labels (such
as “Good”, “Critical”,
or a value range,
the label of the data-
point property, etc.).
Applications also need
an option to specify
terms from the ap-
plication domain as
criticality labels (e.g.
“open XYZ”, “Alert”,
“Success”).
UI.datapoint referencePeriod #optional All UI.dataPoint.ref-

erencePeriod anno-
tations are op-
tional. You either
use UI.dataPoint.ref-
erencePeriod.descrip-
tion,
or UI.dataPoint.ref-
erencePeriod.start
and UI.dataPoint.refer-
encePeriod.end.
UI.datapoint referencePeriod.descri String(120) #optional This annotation de-

ption
scribes the business
period of evaluation,
for example "Oct
2012". Typical patterns
are calendar dates or
fiscal dates.

UI.datapoint referencePeriod.start elementRef #optinal This annotation con-

tains a reference to the
end date of the refer-
ence period.
UI.datapoint referencePeriod.end elementRef #optional This annotation con-

tains a reference to the
start date of the refer-
ence period.
UI.datapoint criticality elementRef This annotation referen-

that has the values 0, 1,
2, or 3.
• Neutral : 0
• Negative: 1
• Critical : 2
• Positive: 3
UI.datapoint criticalityValue Integer enum • Negative

• Critical
• Positive
UI.datapoint criticalityRepresentatio String enum #mandatory

n
• WITHOUT_ICON
• WITH_ICON
Default:
WITHOUT_ICON
UI.datapoint criticalityCalculation Annotations belonging

to UI.dataPoint.critica-
lityCalculation can be
used as an alternative
to specifying the criti-
cality in the criticality
element. The critical-
ity can be calculated
based on the values
of the criticalityCalcu-
lation annotations.

UI.datapoint criticalityCalculation.i String(8) enum • MINIMIZE; Description: This an-

mprovementDirection
• TARGET; notation calculates the
• MAXIMIZE criticality based on a
specified improvement
direction. For more in-
formation, see Trend-
Criticality Calculation
[page 834].
UI.datapoint criticalityCalculation.a DecimalFloat

cceptanceRangeLowVa
lue
UI.datapoint criticalityCalculation.a DecimalFloat

cceptanceRangeHighV
alue
UI.datapoint criticalityCalculation.to DecimalFloat

leranceRangeLowValue
UI.datapoint criticalityCalculation.to DecimalFloat

leranceRangeHighValu
e
UI.datapoint criticalityCalculation.d DecimalFloat

eviationRangeLowValu
e
UI.datapoint criticalityCalculation.d DecimalFloat

eviationRangeHighValu
e
UI.datapoint criticalityCalculation.c (array of) Thresholds depending

onstantThresholds
on the aggregation
level as a set
of constant values.
(Constant thresholds
should only be used
in order to refine
constant values given
for the datapoint over-
all (aggregationLevel
[]), but not if the
thresholds are based
on other measure ele-
ments.

UI.datapoint criticalityCalculation.c (array of) An unordered tuple

onstantThresholds.agg elementRef
of dimensions, i.e. el-
regationLevel
ements which are in-
tended to be used
for group-by in aggre-
gating requests. (In
analytical UIs, e.g.
an analytical chart,
the aggregation level
typically corresponds
to the visible dimen-
sions.)
UI.datapoint criticalityCalculation.c DecimalFloat

onstantThresholds.acc
eptanceRangeLowValu
e

onstantThresholds.acc
eptanceRangeHighVal
ue

onstantThresholds.tole
ranceRangeLowValue

onstantThresholds.tole
ranceRangeHighValue

onstantThresholds.dev
iationRangeLowValue

onstantThresholds.dev
iationRangeHighValue
UI.datapoint trend elementRef • 1: StrongUp Reference to an ele-

• 2: Up ment to visualize a
• 3: Sideways trend in form of an ar-
• 4: Down row.
• 5: StrongDown For more information,

see Trends [page 832].

UI.datapoint trendCalculation As an alternative to

specifying the trend
in the trend element,
the trend could be cal-
culated based on the
trendCalculation anno-
tations.
UI.datapoint trendCalculation.refere elementRef This annotation speci-

nceValue
fies the reference
value for the trend cal-
culation as a reference
to an element.
UI.datapoint trendCalculation.isRela boolean This boolean constant

tiveDifference
Default: False expresses whether
the difference be-
tween the value and
refrrenceValue is abso-
lute or relative.
UI.datapoint trendCalculation.upDiff DecimalFloat This annotation speci-

erence
fies a threshold as a
constant.
UI.datapoint trendCalculation.stron DecimalFloat This annotation speci-

gUpDifference
constant.
UI.datapoint trendCalculation.down DecimalFloat This annotation speci-

Difference
constant.
UI.datapoint trendCalculation.stron DecimalFloat This annotation speci-

gDownDifference
constant.

UI.datapoint responsible ElementRef # not compatible with This annotation con-

UI.dataPoint.responsible
tains an association
Name
to an entity that is
 Caution annotated with @Se-
mantics.name, @Se-
If you use this anno-
mantics.eMail, @Se-
tation, you can't use
mantics.telephone,
the annotation
@Semantics.address,
UI.dataPoint.respon
or @Semantics.organi-
sibleName.
zation.
For more information,

see Person Responsi-
ble and Reference Pe-
riod [page 837].
For an overview
of @Semantics anno-
tations, see Seman-
tics Annotations [page
1247].
 Note
If you use This an-

notation, you can-
not use element
UI.dataPoint.respo
nsibleName.
UI.datapoint responsibleName String (120) # not compatible with This annotation can be
UI.dataPoint.responsible
used as an alternative
to the responsible ele-
 Caution
ment. Only the name
If you use this anno- of the responsible per-
tation, you can't use son can be specified
the annotation here.
UI.dataPoint.respon
sible.

UI.kpi Annotations belonging

to UI.KPI represent a
single point of data,
specialized for a spe-
cific data selection
and extended with in-
formation about KPI
details, especially the
first level of drilldown,
for a progressive dis-
closure.
Scope: [ELEMENT]
UI.kpi qualifier String(120)

UI.kpi id String(120)
UI.kpi shortDescription String(120)
UI.kpi selectionVariantQualifi String(120) This element refers
er
to a UI.selectionVar-
iant annotation at the
same view via its quali-
fier.
UI.kpi detail String(120) This annotation bun-

dles additional set-
tings for a KPI which
are relevant for a sepa-
rate KPI detail display
or for progressive dis-
closure of the KPI.
UI.kpi detail.defaultPresentati String(120) This element refers

onVariantQualifier
to a UI.presentation-
Variant annotation at
the same view via its
qualifier. This presen-
tation variant should
be used to initially rep-
resent the KPI detail.

UI.kpi detail.alternativePrese (array of) This element refers

ntationVariantQualifier String(120)
to a UI.presentation-
s
Variant annotations at
the same view via
their qualifiers. These
presentation variants
should be used/of-
fered as al-ternative
representations of the
KPI detail
UI.kpi detail.semanticObject String(120)

UI.kpi detail.semanticObject String(120)
Action
UI.kpi dataPoint For the

UI.kpi.dataPoint anno-
tations you can refer
to UI.dataPoint .
UI.selectionField (array of ) Annotations belonging

to UI.selectionField al-
low filtering a list of
data. UI.selectionField
annotations are usu-
ally used in an initial
page floorplan as filter
bar.
Scope: [ELEMENT]
Evaluation Runtime
(Engine): SADL: Trans-
lates CDS annotations
into the corresponding
OData annotations
UI.selectionField qualifier String(120) This annotation is

used to group and
uniquely identify anno-
tations. You need to
specify a qualifier as
name of a selection
field to ensure that the
correct selection field
can be referenced by
the UI.

UI.selectionField position DecimalFloat #mandatory With this annotation

you specify the order
of selection fields that
are used for filtering.
UI.selectionField exclude Boolean #optional This annotation allows
Default: true excluding the element

from the OData anno-
tation on the derived
view by setting it to
true.

see Inheritance of An-
notations [page 828]
UI.selectionField element elementRef #mandatory: Must be

used when an associa-
tion is annotated, the
value is a path to an el-
ement of the associated
view. You use this option
if you want to filter a ta-
ble for a column that is
not defined in your CDS
view but in another CDS
view.
 Caution
Must not be used

when a structured
element is anno-
tated, in this case
the annotated ele-
ment is the value.
UI.valueCriticality (array of ) Scope: [ELEMENT]
UI.valueCriticality qualifier String(120);

UI.valueCriticality value Expression
UI.valueCriticality criticality Integer enum • 1: Negative
• 2: Critical
• 3: Positive
UI.criticalityLabels (array of ) Scope: [ELEMENT]
UI.criticalityLabels qualifier String(120);

UI.criticalityLabels criticality Integer enum • 1: Negative

• 2: Critical
• 3: Positive
UI.criticalityLabels label String(60);

UI.chart Annotations belonging
to UI.chart are used
to show a visual rep-
resentation of aggre-
gated data.
Scope: [ ENTITY]
Evaluation Runtime
OData annotations
Values: array of
UI.chart qualifier String(120) This annotation is

used to group and
name of a chart to
ensure that the cor-
rect chart can be ref-
erenced by the UI.
UI.chart title String(60) #optional This annotation con-

ted, the @EndUser-
Text.label of the anno-
tated entity or view is
used.
UI.chart description String(120) #optional This annotation con-

ted, the @EndUser-
Text.quickInfo of the
annotated entity or
view is used.

UI.chart chartType String enum COLUMN;
COLUMN_STACKED;
COL-
UMN_STACKED_100;
COLUMN_DUAL;
COL-
UMN_STACKED_DUAL;
COL-
UMN_STACKED_DUAL_
100;
BAR;
BAR_STACKED;
BAR_STACKED_100;
BAR_DUAL;
BAR_STACKED_DUAL;
BAR_STACKED_DUAL_1
00;
AREA;
AREA_STACKED;
AREA_STACKED_100;
HORIZONTAL_AREA;
HORIZON-
TAL_AREA_STACKED;
HORIZON-
TAL_AREA_STACKED_1
00;
LINE;
LINE_DUAL;
COMBINATION;
COMBINA-
TION_STACKED;
COMBINA-
TION_STACKED_DUAL;
HORIZONTAL_COMBI-
NATION_STACKED;

HORIZON-
TAL_COMBINA-
TION_STACKED_DUAL;
PIE;
DONUT;
SCATTER;
BUBBLE;
RADAR;
HEAT_MAP;
TREE_MAP;
WATERFALL;
BULLET;
VERTICAL_BULLET;
HORIZONTAL_WATER-
FALL;
HORIZONTAL_COMBI-
NATION_DUAL;
DONUT_100;
UI.chart dimensions elementRef This annotation is an

array of one or more
element references for
the discrete axes of
a chart. The exact se-
mantics depend on the
chart type.
UI.chart measures elementRef This annotation is an

array of zero or more
element references for
the numeric axes of
a chart. The exact se-
mantics depend on the
chart type.

UI.chart dimensionAttributes.di elementRef This annotation de-

mension
fines the dimensions
used in a chart. This
annotation must ref-
erence an element
that is contained in
UI.chart.dimensions.
UI.chart dimensionAttributes.ro String(10) enum These annotatoions de- This annotation de-
le termine the visualization
fines the manner in
of a chart.
which a dimension
• CATEGORY: For ex- is used within a
ample: Line chart: chart.This is config-
Dimensions for ured differently for
which the role is each chart type.
set to CATEGORY,
make up the X-axis
(category axis). If
no dimension is
specified with this
role, the first di-
mension is used as
the X-axis.
• SERIES: For exam-
ple:
Line chart: Dimen-
sions for which
the role is set to
SERIES make up
the line segments
of the chart, with
different colors as-
signed to each
dimension value.
If multiple dimen-
sions are assigned
to this role, the val-
ues of all such di-
mensions together
are considered as
one dimension and
a color is assigned.
• CATEGORY2
UI.chart dimensionAttributes.va array of

luesForSequentialColo String(1024)
rLevels

UI.chart dimensionAttributes.e array of

mphasizedValues String(1024)
UI.chart measureAttributes (array of) Annotations belonging
to UI.chart.measureAt-
tributes are used to
specify the measure
attributes of a chart.
UI.chart measureAttributes.me ElementRef This annotation de-

asure
fines the measures
used in a chart. This
annotation must ref-
erence an element
that is contained in
UI.chart.measures and
has a UI.dataPoint an-
notation.
UI.chart measureAttributes.role String(10) enum This annotation deter- This annotation de-
mines the visualization
fines the manner in
of a chart.
which a measure is
• AXIS_1: used within a chart.
Example This is configured dif-
Bubble chart: The ferently for each chart
first measure for type.
which the role is
set to AXIS_1, or
if none exists, the
first measure for
which the role is
set to AXIS_2, or
if none exists, the
first measure for
which the role is
set to AXIS_3, is as-
signed to the feed
UID valueAxis. This
makes up the X-
axis.
• AXIS_2:
For an example, see
the description of
AXIS_1.
• AXIS_3:
For an example, see
the description of
AXIS_1.

UI.chart measureAttributes.asD Boolean This annotation de-

ataPoint
Default : true fines whether or
not measures are dis-
played as data points
in addition to a
chart. The element an-
notated with this UI
annotation needs to
have an annotation to
a data point.
UI.chart measureAttributes.use Boolean

SequentialColorLevels
Default : false
UI.chart actions
UI.chart actions.type String(40) enum • FOR_ACTION

• FOR_IN-
TENT_BASED_NAV
IGATION
UI.chart actions.label String(60)

UI.chart actions.dataAction String(120)
UI.chart actions.requiresContex Boolean
t
Default: true

UI.chart actions. String(12) enum • ISOLATED: This annotation ex-

invocationGrouping Describes the er- presses how multiple
ror handling when invocations of the
an action cannot same action on mul-
be executed on all tiple instances are
selected instances: grouped.
The action is exe-
ISOLATED Example:
cuted on all instan-
ces except for in- A user selects five
stance on which the items in a list and
action cannot be wants to copy them.
executed. One item cannot be
copied. This item will
• CHANGE_SET:
Describes the error not be copied, the
handling when an other four items are
action cannot be copied.
executed on all se- CHANGE_SET Exam-

lected instances: If ple:
an action cannot be A user selects five
executed on one of items in a list and
the selected instan- wants to copy them.
ces, the action is One item cannot be
executed on none copied. None of the
of the selected in- selected items are
stances. copied.
Default: ISOLATED
UI.chart actions.semanticObjec String(120)

tAction
UI. Annotations belonging

selectionPresentationV
to UI.selectionPresen-
ariant
tationVariant are used
to bundle annotations
of UI.presentationVar-
iant and UI.selection-
Variant.
Scope: [ENTITY]
Evaluation Runtime
OData annotations
Values: array of

UI. qualifier String(120) This annotation is

used to group and
ariant
name of a selection
presentation variant to
ensure that the cor-
rect selection presen-
tation variant can be
referenced by the UI.
UI. id String(120) This annotation con-

tains an identifier to
ariant
reference this instance
from an external con-
text.
UI. text String(60) This annotation con-

tains the language-de-
ariant
pendent name of the
selection presentation
variant.
UI. selectionVariantQualifi String(120) This annotation is

selectionPresentationV er
used to group and
ariant
name of a selection
variant to ensure that
the correct selection
variant can be refer-
enced by the selection
presentation variant

UI. presentationVariantQu String(120) This annotation is

selectionPresentationV alifier
used to group and
ariant
name of a presenta-
tion variant to ensure
that the correct pre-
sentation variant can
be referenced by the
selection presentation
variant.
UI selectionVariant Annotations belonging

to UI.selectionVariant
are used to denote a
combination of param-
eters and filters used
to query the annotated
entity set.
Scope: [ ENTITY]
Evaluation Runtime
OData annotations
Values: array of
UI.selectionVariant qualifier String(120) This annotation is

used to group and
name of a selection
variant to ensure that
the correct selection
variant can be refer-
enced by the UI.
UI.selectionVariant id : String(120) This annotation can

contain an identifier to
text.

UI.selectionVariant text String(60) This annotation con-

pendent name of the
selection variant.
UI.selectionVariant parameters (array of) Annotations belong-

ing to UI.selectionVar-
iant.parameters repre-
sent a collection of
parameters used to
query the annotated
entity set.
UI.selectionVariant parameters.name ParameterRef This annotation refer-

ences to a parameter
name.
UI.selectionVariant parameters.value String(1024) This annotation con-

tains a parameter
value.
UI.selectionVariant filter String(1024) This annotation con-

tains a filter used to
query the annotated
entity set.
UI.presentationVariant qualifier String(120) This annotation is

used to group and
name of a presenta-
tion variant to ensure
that the correct pre-
sentation variant can
UI.
UI.presentationVariant id : String(120) This annotation con-

tains an identifier to
text.
UI.presentationVariant text String(60) This annotation con-

pendent name of the
presentation variant.

UI.presentationVariant maxItems Integer This annotation de-

fines the maximum
number of items that
should be included in
the result.
UI.presentationVariant sortOrder (array of) Annotations belonging

to UI.presentationVar-
iant.sortOrder repre-
sent a collection of
sorting parameters
that can be provided
inline or by a reference
to a Common.SortOr-
der annotation (syntax
is identical to Annota-
tionPath).
UI.presentationVariant sortOrder.by elementRef This annotation de-

fines by what prop-
erty queried collec-
tions can be sorted.
UI.presentationVariant sortOrder.direction String(4) enum • ASC: Sort in as- This annotation de-
cending order. fines the sorting direc-
• DESC: Sort in de- tion of queried collec-
scending order. tions.

UI.presentationVariant groupBy rray of This annotation de-

elementRef fines a sequence of
groupable properties
(p1, p2, pn) that de-
fine how the result
of a queried collec-
tion is composed of in-
stances that represent
groups, one group for
each combination of
value properties in the
queried collection.
The sequence speci-

fies a certain level
of aggregation for the
queried collection, and
every group instance
provides aggregated
values for properties
that are aggregatable.
Moreover, the series of
sub-sequences, for ex-
ample (p1), (p1, p2), ...,
forms a leveled hierar-
chy that can be used
in combination with
the annotation UI.pre-
sentationVariant.initia-
lExpansionLevel.

UI.presentationVariant totalBy array of This annotation de-

elementRef fines the sub-se-
quence q1, q2, qn of
the properties p1, p2,
pn specified in the
annotation UI.presen-
tationVariant.groupBy.
With this, additional
levels of aggregation
are requested in addi-
tion to the most granu-
lar level defined by the
annptation UI.presen-
tationVariant.groupBy.
Every element in the
series of sub-sequen-
ces, for example (q1),
(q1, q2), ..., introduces
an additional aggrega-
tion level included in
the result of the quer-
ied collection.
UI.presentationVariant total array of This annotation con-

elementRef tains aggregatable
properties for which
aggregated values are
to be provided for the
additional aggregation
levels specified in the
tationVariant.totalBy.
UI.presentationVariant includeGrandTotal Boolean This annotation speci-
Default: true fies that the result of

the queried collection
includes a grand to-
tal for the properties
specified in the anno-
tation UI.presentation-
Variant.total.

UI.presentationVariant initialExpansionLevel Integer This annotation con-

tains the initial num-
ber of expansion levels
of a hierarchy defined
for the queried collec-
tion. The hierarchy can
be implicitly imposed
by the sequence of the
tationVariant.groupBy,
or by an explicit hierar-
chy annotation.
UI.presentationVariant requestAtLeast array of This annotation de-

elementRef fines the properties
that should always be
included in the result
of the queried collec-
tion.
UI.presentationVariant visualizations (array of) Annotations belonging

to UI.presentationVar-
iant.visualizations rep-
resent a collection of
available visualization
types. The following
types are supported:
UI.lineItem
UI.chart
UI.dataPoint

UI.presentationVariant visualizations.type String(40) enum • AS_LINEITEM: The This annotation de-

queried collection fines the representa-
is visualized as line
tion type. For each
item.
type, only one single
• AS_CHART: The
annotation is mean-
queried collection
ingful. Multiple instan-
is visualized as
chart. ces of the same visu-
alization type shall be
• AS_DATAPOINT:
The queried collec- modeled with different
tion is visualized as presentation variants.
data point. A reference to the
annotation UI.lineItem
Default: AS_LINEITEM
should always be part
of the collection (least
common denominator
for renderers).
UI.presentationVariant visualizations.qualifier String(120) This annotation is

used to group and
name of a visualization
to ensure that the cor-
rect visualization can
UI.
UI.presentationVariant visualizations.element ElementRef This annotation refer-

ences the annotation
UI.lineItem.
UI.presentationVariant selectionFieldsQualifie String(120)

r

UI.hidden Boolean . To enable end-user
Default true personalization, the

client may offer the
possibility to add fields
that are hidden for
UI consumption, for
example in facets on
the object page. You
can use the annotation
@UI.hidden to prevent
fields from being dis-
played on the UI and
in the personalization
dialog, but leaving the
field available for a
WebAPI client. The an-
noation can be applied
for example to fields
in CDS views or par-
amters of an axtion.
see Hiding Fields on
the Object Page [page
812]
Scope: [ELEMENT, PA-

RAMETER]
Evaluation Runtime
OData annotations

UI.masked Boolean This annotation refers
Default true to, for example, pass-

words or pass phrases.
The user interface
may offer to show
the value in clear text
upon explicit user in-
teraction. For more in-
formation, see Field
Masking.
Scope: [ELEMENT]
Evaluation Runtime
OData annotations
UI.multiLineText Boolean UI.multiLineText
Default true This annotation con-

tains text that is
rendered as multiple
lines.For more infor-
mation, see Multi-Line
Text [page 826].
Scope: [ELEMENT]
Evaluation Runtime
OData annotations

UI.textArrangement String(13) enum • TEXT_FIRST: The Description: This an-

text is displayed in notation specifies the
front of the code.
arrangement of code-
• TEXT_LAST: The text pairs.
code is displayed in
front of the text. Scope: [ENTITY, ELE-
• TEXT_ONLY: The MENT]
text is displayed
Evaluation Runtime
without the code.
• TEXT_SEPARATE:
TEXT_SEPARATE
The text and the into the corresponding
code are displayed OData annotations
separately.
Values:
String
UI.facet qualifier String(120) This element uniquely

identifies alternative
values for an annota-
tion; only allowed if pa-
rentId is not specified.
UI.facet feature String(40) This annotation speci-

fies the name of a fea-
ture toggle that deter-
mines visibility of the
facet.
UI.facet id String(120) This element is the

identifier of the facet
UI.facet purpose String(40) enum #not compatible with This annotation speci-
UI.facet.parentID
fies the purpose of a
facet; only allowed if
 Caution
parentId is not speci-
You can only use fied
this annotation, if
parentId is not
specified.
STANDARD;
HEADER;
QUICK_VIEW;
QUICK_CREATE;
FILTER;
default: STANDARD;

UI.facet parentId String(120) #not compatible with This annotation identi-

UI.facet.purpose
fies the parent facet.
only allowed if purpose
 Caution
is not specified
You can only use
this annotation, if
purpose is not
specified.
UI.facet position DecimalFloat This annotation speci-

fies the relative posi-
tion of the Facet within
its parent or term.
Must be specified to
allow interspersing ex-
tension elements via
extend views.
UI.facet exclude Boolean Marker to explicitly ex-
Default: true clude a CDS element

from the collection of
DataField for a derived
view.
UI.facet hidden Boolean The annotation hid-
Default: true den allows providing

a static Boolean value
(for facets hidden by
de-fault and e.g. made
visible via code exit in
the UI), but usually the
value will be provided
by referencing a Boo-
lean element of the
same view using the
#(...) syntax. The lat-
ter allows to dynami-
cally switch the facet
on or off.
UI.facet isPartOfPreview Boolean This annotation deter-
Default: true mines that this facet

and all included facets
are part of the thing
preview.

UI.facet isSummary Boolean This annotation speci-
Default: true fies that this facet and

all included facets are
the summary of the
thing. At most one
facet of a thing can be
tagged with this term
UI.facet isMap Boolean This annotation speci-
Default: true fies that this facet is

best represented as a
geographic map.
UI.facet importance String(6) enum • HIGH This expresses the im-

• MEDIUM portance of dataFields
• LOW or other annotations.
It can be used e.g. in
dynamic rendering ap-
proaches with respon-
sive design.
UI.facet label String(60) #optional This annotation can

contain a language-de-
pendent text; if omit-
ted, the label of the an-
notated element or the
label of the element
referenced via value
which is used.

UI.facet type String(40) enum • COLLECTION: This enumeration el-

• id element is re- ement specifies the
quired concrete type of the
• no additional ele- facet. The enumera-
ments are available tion type value deter-
• ADDRESS_REFERE mines which CDS an-
NCE notation elements are
- targetElement ele- required or available
ment is available
- targetQualifier ele-
ment is available
- isMap element is
available
• BADGE_REFERENC
E
- targetElement ele-
ment is available
• CHART_REFERENC
E
ment is available
ment is available
• CONTACT_REFERE
NCE
ment is available
ment is available
• DATAPOINT_REFER
ENCE
ment is available
ment is required
• HEADERINFO_REFE
RENCE
ment is available
ment is required
• IDENTIFICATION_R
EFERENCE
ment is available
• LINEITEM_REFERE
NCE

ment is available
ment is available
• STATUSINFO_REFE
RENCE
ment is available
ment is available
• URL_REFERENCE
- url element is
available
UI.facet targetElement elementRef This annotation speci-

fies a path to the
CDS view whose an-
notation is referenced.
Not specified means
the current view. The
path is converted to
an OData Annotation-
Path.
UI.facet targetQualifier String(120) This annotation is the

qualifier of the refer-
enced annotation.
UI.facet url ElementRef This annotation speci-

fies a path to struc-
tural element contain-
ing the navigation
URL.

UI.lineItem Annotations belonging

to UI.lineItem repre-
sent an ordered col-
lection of data fields
that is used to repre-
sent data from multi-
ple data instances in
a table or a list. For
more information, see
Columns.
Scope: [ELEMENT, EN-

TITY]
Evaluation Runtime
OData annotations
UI.lineItem qualifier String(120) This annotation is

used to group and
tations.
If you want to use

more than one table,
you need a qualifier
to distinguish them on
the UI.
UI.lineItem position DecimalFloat #mandatory With this annotation

of the columns of a
list.
UI.lineItem exclude Boolean This annotation allows
Default: True excluding the element

true. The element is
optional.


UI.lineItem hidden Boolean The annotation hid-
Default: True den allows providing a

static boolean value,
but usually the value
will be provided by ref-
erencing a Boolean el-
ement of the same
view using the #(...)
syntax.
UI.lineItem importance String(6) enum This annotation ex-

 Note
presses the impor-
If no importance
tance of dataFields
is defined, the line
or other annotations.
item is treated like
having importance The element can be
LOW. used, for example, in
• HIGH proaches with respon-
• MEDIUM sive design patterns.
• LOW Example:
You defined a ta-

ble with several col-
umns. The columns
that need to be dis-
played always, get im-
portance HIGH. This
ensures that these col-
umns are displayed in
a table when this table
is rendered on a small
display.

UI.lineItem type String(40) enum AS_ADDRESS;
AS_CHART;
AS_CON-
NECTED_FIELDS;
AS_CONTACT;
AS_DATAPOINT;
AS_FIELDGROUP;
FOR_ACTION;
FOR_IN-
TENT_BASED_NAVIGA-
TION;
STANDARD;
WITH_IN-
TENT_BASED_NAVIGA-
TION;
WITH_NAVIGA-
TION_PATH;
WITH_URL;
label
UI.lineItem label String(60) #optional This annotation con-

be used for column ti-
tles in tables headers.

of the annotated el-
ement, or the label
of the element refer-
enced via the value is
used.
UI.lineItem iconUrl String(1024) #optional This annotation con-

tains the URL to an
icon image.

UI.lineItem criticality ElementRef This annotation referen-

2, or 3.
• Neutral : 0
• Negative: 1
• Critical : 2
• Positive: 3
UI.lineItem criticalityRepresentatio String(12) enum • WITHOUT_ICON

n
• WITH_ICON
Default:
WITHOUT_ICON
UI.lineItem dataAction String(120) This annotation can

be used if the line
item type is FOR_AC-
TION. The element ref-
erences the technial
name of an action of
the Business Object
Processing Framework
(BOPF), for example.
In this case, the string
pattern is BOPF:<tech-
nical name of action in
BOPF>.
UI.lineItem requiresContext Boolean
Default: True

UI.lineItem invocationGrouping String(12) enum #optional This annotation ex-

presses how multiple
 Note
invocations of the
This annotation same action on mul-
needs to be speci-
tiple instances are
fied if you use
grouped.
UI.lineItem.type of
type FOR_ACTION. ISOLATED Example:
A user selects five

• ISOLATED:
items in a list and
Describes the er-
wants to copy them.
ror handling when
One item cannot be
an action cannot
be executed on all
not be copied, the
selected instances:
other four items are
The action is exe-
copied.
ces except for in- CHANGE_SET Exam-
ple:
stance on which the
action cannot be A user selects five
executed. items in a list and
• CHANGE_SET: wants to copy them.
Describes the error One item cannot be
handling when an copied. None of the
action cannot be selected items are
executed on all se- copied.
lected instances: If
an action cannot be
executed on one of
the selected instan-
ces, the action is
executed on none
of the selected in-
stances.
Default: ISOLATED
UI.lineItem semanticObjectAction String(120) This annotation refers

to the name of an
action on the seman-
tic object. The seman-
tic object is taken
from @Consump-
tion.semanticObject
or derived via an asso-
ciation from the defin-
ing view.

UI.lineItem value ElementRef For type AS_ADDRESS: This annotation refers

to a value.
• Value element
must not used
when a structural
element is anno-
tated. Use instead
@com.sap.vocabu-
laries.Communica-
tion.v1.Address (or
a shorter alias-
qualified name) as
value.
• Value element must
be used when an el-
ement of an asso-
ciated CDS view is
annotated. A value
of '.' refers to @Se-
mantics.address on
the view that is di-
rectly associated.
• If you want to
reference @Seman-
tics.address on a
view that is indi-
rectly associated,
use a path starting
with a dot as value.
All other types:

not be used when
an element is anno-
tated, in this case
the annotated ele-
ment is the value.
be used when an
association is anno-
tated. The value is a
path to an element
of the associated
view.
UI.lineItem valueQualifier String(120)

UI.lineItem targetElement ElementRef This annotation repre-

sents the path to an
element of an associ-
ated CDS view. The
OData NavigationPro-
pertyPath. Using this
annotation, you can
link from the header
part of an object view
floorplan to a target
element. You need to
specify UI.lineItem.tar-
getElement when you
use the annotation
UI.lineItem.type of
type WITH_NAVIGA-
TION_PATH.
You might, for ex-

on the object view
floorplan.
UI.lineItem url ElementRef This annotation rep-

 Caution resents the path to
You need to specify a structural element
UI.lineItem.url when that contains a naviga-
you use the annotation URL.
tion UI.lineItem.type
of type WITH_URL

UI.identification Annotation belonging

to UI.identification
represent an ordered
collection of specific
data fields that to-
gether with headerInfo
identifies an entity to
an end user.
Example
This annotation is dis-

played in the General
Information section in
the body of the object
view floorplan of an
item, for example.
Scope: [ELEMENT]
Evaluation Runtime
OData annotations
Values: array of
UI.identification qualifier String(120) This annotation is

used to group and
tations.
If you want to use

the UI.
UI.identification position DecimalFloat #mandatory With this annotation

of the columns of a
list.

UI.identification exclude Boolean This annotation allows

optional.

UI.identification hidden Boolean The annotation hid-

ement of the same
syntax.
UI.identification importance String(6) enum This annotation ex-

 Note
presses the impor-
If no importance
tance of dataFields
• LOW Example:
You defined a ta-

umns. The columns
portance HIGH. This
display.

UI.identification type String(40) enum AS_ADDRESS;
AS_CHART;
AS_CON-
NECTED_FIELDS;
AS_CONTACT;
AS_DATAPOINT;
AS_FIELDGROUP;
FOR_ACTION;
FOR_IN-
TENT_BASED_NAVIGA-
TION;
STANDARD;
WITH_IN-
TENT_BASED_NAVIGA-
TION;
WITH_NAVIGA-
TION_PATH;
WITH_URL;
label
UI.identification label String(60) #optional This annotation con-


ement, or the label
used.
UI.identification iconUrl String(1024) #optional This annotation con-

tains the URL to an
icon image.

UI.identification criticality ElementRef This annotation referen-

2, or 3.
• Neutral : 0
• Negative: 1
• Critical : 2
• Positive: 3
UI.identification criticalityRepresentatio String(12) enum • WITHOUT_ICON

n
• WITH_ICON
Default:
WITHOUT_ICON
UI.identification dataAction String(120) This annotation can

be used if the line
the Business Object
BOPF>.
UI.identification requiresContext Boolean
Default: True

UI.identification invocationGrouping String(12) enum #optional This annotation ex-

 Note
invocations of the
needs to be speci-
tiple instances are
fied if you use
grouped.
UI.lineItem.type of
A user selects five

• ISOLATED:
items in a list and
Describes the er-
wants to copy them.
ror handling when
One item cannot be
an action cannot
be executed on all
not be copied, the
selected instances:
The action is exe-
copied.
ple:
stance on which the
an action cannot be
executed on one of
ces, the action is
executed on none
of the selected in-
stances.
Default: ISOLATED
UI.identification semanticObjectAction String(120) This annotation refers

to the name of an
tic object is taken
from @Consump-
tion.semanticObject
ing view.

UI.identification value ElementRef For type AS_ADDRESS: This annotation refers

to a value.
• Value element
must not used
when a structural
element is anno-
tated. Use instead
@com.sap.vocabu-
laries.Communica-
tion.v1.Address (or
a shorter alias-
qualified name) as
value.
be used when an el-
ement of an asso-
ciated CDS view is
annotated. A value
mantics.address on
rectly associated.
• If you want to
reference @Seman-
tics.address on a
view that is indi-
rectly associated,
use a path starting
All other types:

not be used when
an element is anno-
tated, in this case
the annotated ele-
ment is the value.
be used when an
path to an element
of the associated
view.
UI.identification valueQualifier String(120)

UI.identification targetElement ElementRef This annotation repre-

ated CDS view. The
annotation, you can
getElement when you
use the annotation
UI.lineItem.type of
type WITH_NAVIGA-
TION_PATH.
You might, for ex-

on the object view
floorplan.
UI.identification url ElementRef This annotation rep-

You need to specify a structural element
UI.identification.url that contains a naviga-
when you use the tion URL.
annotation UI.iden-
tification.type of
type WITH_URL.

UI.statusInfo Annotations belonging

to UI.statusInfo repre-
sent a list of abstract
data fields that convey
the status of an en-
tity. UI.statusInfo an-
notations are usually
used in the header
section of an item's
object view floorplan.
Scope: [ELEMENT]
Evaluation Runtime
OData annotations
Values: array of
UI.statusInfo qualifier String(120) This annotation is

used to group and
tations.
If you want to use

the UI.
UI.statusInfo position DecimalFloat #mandatory With this annotation

of the columns of a
list.
UI.statusInfo exclude Boolean This annotation allows

optional.


UI.statusInfo hidden Boolean The annotation hid-

ement of the same
syntax.
UI.statusInfo importance String(6) enum This annotation ex-

 Note
presses the impor-
If no importance
tance of dataFields
• LOW Example:
You defined a ta-

umns. The columns
portance HIGH. This
display.

UI.statusInfo type String(40) enum AS_ADDRESS;
AS_CHART;
AS_CON-
NECTED_FIELDS;
AS_CONTACT;
AS_DATAPOINT;
AS_FIELDGROUP;
FOR_ACTION;
FOR_IN-
TENT_BASED_NAVIGA-
TION;
STANDARD;
WITH_IN-
TENT_BASED_NAVIGA-
TION;
WITH_NAVIGA-
TION_PATH;
WITH_URL;
label
UI.statusInfo label String(60) #optional This annotation con-


ement, or the label
used.
UI.statusInfo iconUrl String(1024) #optional This annotation con-

tains the URL to an
icon image.

UI.statusInfo criticality ElementRef This annotation referen-

2, or 3.
• Neutral : 0
• Negative: 1
• Critical : 2
• Positive: 3
UI.statusInfo criticalityRepresentatio String(12) enum • WITHOUT_ICON

n
• WITH_ICON
Default:
WITHOUT_ICON
UI.statusInfo dataAction String(120) This annotation can

be used if the line
the Business Object
BOPF>.
UI.statusInfo requiresContext Boolean
Default: True

UI.statusInfo invocationGrouping String(12) enum #optional This annotation ex-

 Note
invocations of the
needs to be speci-
tiple instances are
fied if you use
grouped.
UI.lineItem.type of
A user selects five

• ISOLATED:
items in a list and
Describes the er-
wants to copy them.
ror handling when
One item cannot be
an action cannot
be executed on all
not be copied, the
selected instances:
The action is exe-
copied.
ple:
stance on which the
an action cannot be
executed on one of
ces, the action is
executed on none
of the selected in-
stances.
Default: ISOLATED
UI.statusInfo semanticObjectAction String(120) This annotation refers

to the name of an
tic object is taken
from @Consump-
tion.semanticObject
ing view.

UI.statusInfo value ElementRef For type AS_ADDRESS: This annotation refers

to a value.
• Value element
must not used
when a structural
element is anno-
tated. Use instead
@com.sap.vocabu-
laries.Communica-
tion.v1.Address (or
a shorter alias-
qualified name) as
value.
be used when an el-
ement of an asso-
ciated CDS view is
annotated. A value
mantics.address on
rectly associated.
• If you want to
reference @Seman-
tics.address on a
view that is indi-
rectly associated,
use a path starting
All other types:

not be used when
an element is anno-
tated, in this case
the annotated ele-
ment is the value.
be used when an
path to an element
of the associated
view.
UI.statusInfo valueQualifier String(120)

UI.statusInfo targetElement ElementRef This annotation repre-

ated CDS view. The
annotation, you can
getElement when you
use the annotation
UI.lineItem.type of
type WITH_NAVIGA-
TION_PATH.
You might, for ex-

on the object view
floorplan.
UI.statusInfo url ElementRef This annotation rep-

You need to spec- a structural element
ify UI.statusInfo.url that contains a naviga-
annotation UI.sta-
tusInfo.type of type
WITH_URL..

UI.fieldGroup Annotations belonging

to UI.fieldGroup is an
ordered collection of
data fields with a la-
bel for the group.
UI.fieldGroup annota-
tions are used to rep-
resent parts of a sin-
gle data instance in a
form.
Scope: [ELEMENT]
Evaluation Runtime
OData annotations
Values: array of
UI.fieldGroup qualifier String(120) This annotation is

used to group and
tations.
If you want to use

the UI.
UI.fieldGroup groupLabel #optional This annotation

contains language-de-
pendent text that is
used as label for the
field group. The first
occurrence for a given
qualifier wins. Other
occurrences for the
same qualifier are re-
dundant.
UI.fieldGroup position DecimalFloat #mandatory With this annotation

of the columns of a
list.

UI.fieldGroup exclude Boolean This annotation allows

optional.

UI.fieldGroup hidden Boolean The annotation hid-

ement of the same
syntax.
UI.fieldGroup importance String(6) enum This annotation ex-

 Note
presses the impor-
If no importance
tance of dataFields
• LOW Example:
You defined a ta-

umns. The columns
portance HIGH. This
display.

UI.fieldGroup type String(40) enum AS_ADDRESS;
AS_CHART;
AS_CON-
NECTED_FIELDS;
AS_CONTACT;
AS_DATAPOINT;
AS_FIELDGROUP;
FOR_ACTION;
FOR_IN-
TENT_BASED_NAVIGA-
TION;
STANDARD;
WITH_IN-
TENT_BASED_NAVIGA-
TION;
WITH_NAVIGA-
TION_PATH;
WITH_URL;
label
UI.fieldGroup label String(60) #optional This annotation con-


ement, or the label
used.
UI.fieldGroup iconUrl String(1024) #optional This annotation con-

tains the URL to an
icon image.

UI.fieldGroup criticality ElementRef This annotation referen-

2, or 3.
• Neutral : 0
• Negative: 1
• Critical : 2
• Positive: 3
UI.fieldGroup criticalityRepresentatio String(12) enum • WITHOUT_ICON

n
• WITH_ICON
Default:
WITHOUT_ICON
UI.fieldGroup dataAction String(120) This annotation can

be used if the line
the Business Object
BOPF>.
UI.fieldGroup requiresContext Boolean
Default: True

UI.fieldGroup invocationGrouping String(12) enum #optional This annotation ex-

 Note
invocations of the
needs to be speci-
tiple instances are
fied if you use
grouped.
UI.lineItem.type of
A user selects five

• ISOLATED:
items in a list and
Describes the er-
wants to copy them.
ror handling when
One item cannot be
an action cannot
be executed on all
not be copied, the
selected instances:
The action is exe-
copied.
ple:
stance on which the
an action cannot be
executed on one of
ces, the action is
executed on none
of the selected in-
stances.
Default: ISOLATED
UI.fieldGroup semanticObjectAction String(120) This annotation refers

to the name of an
tic object is taken
from @Consump-
tion.semanticObject
ing view.

UI.fieldGroup value ElementRef For type AS_ADDRESS: This annotation refers

to a value.
• Value element
must not used
when a structural
element is anno-
tated. Use instead
@com.sap.vocabu-
laries.Communica-
tion.v1.Address (or
a shorter alias-
qualified name) as
value.
be used when an el-
ement of an asso-
ciated CDS view is
annotated. A value
mantics.address on
rectly associated.
• If you want to
reference @Seman-
tics.address on a
view that is indi-
rectly associated,
use a path starting
All other types:

not be used when
an element is anno-
tated, in this case
the annotated ele-
ment is the value.
be used when an
path to an element
of the associated
view.
UI.fieldGroup valueQualifier String(120)

UI.fieldGroup targetElement ElementRef This annotation repre-

ated CDS view. The
annotation, you can
getElement when you
use the annotation
UI.lineItem.type of
type WITH_NAVIGA-
TION_PATH.
You might, for ex-

on the object view
floorplan.
UI.fieldGroup url ElementRef This annotation rep-

ify UI.fieldGroup.url that contains a naviga-
when you use tion URL.
the annotation
UI.fieldGroup.type
of type WITH_URL..
UI.connectedFields
UI.connectedFields qualifier String(120) This annotation is

used to group and
tations.
If you want to use

the UI.

UI.connectedFields groupLabel #optional This annotation

contains language-de-
pendent text that is
used as label for the
field group. The first
occurrence for a given
qualifier wins. Other
occurrences for the
same qualifier are re-
dundant.
UI.connectedFields template String(255)

UI.connectedFields name String(120)
UI.connectedFields exclude Boolean This annotation allows

optional.

UI.connectedFields hidden Boolean The annotation hid-

ement of the same
syntax.

UI.connectedFields importance String(6) enum This annotation ex-

 Note
presses the impor-
If no importance
tance of dataFields
• LOW Example:
You defined a ta-

umns. The columns
portance HIGH. This
display.

UI.connectedFields type String(40) enum AS_ADDRESS;
AS_CHART;
AS_CON-
NECTED_FIELDS;
AS_CONTACT;
AS_DATAPOINT;
AS_FIELDGROUP;
FOR_ACTION;
FOR_IN-
TENT_BASED_NAVIGA-
TION;
STANDARD;
WITH_IN-
TENT_BASED_NAVIGA-
TION;
WITH_NAVIGA-
TION_PATH;
WITH_URL;
label
UI.connectedFields label String(60) #optional This annotation con-


ement, or the label
used.
UI.connectedFields iconUrl String(1024) #optional This annotation con-

tains the URL to an
icon image.

UI.connectedFields criticality ElementRef This annotation referen-

2, or 3.
• Neutral : 0
• Negative: 1
• Critical : 2
• Positive: 3
UI.connectedFields criticalityRepresentatio String(12) enum • WITHOUT_ICON

n
• WITH_ICON
Default:
WITHOUT_ICON
UI.connectedFields dataAction String(120) This annotation can

be used if the line
the Business Object
BOPF>.
UI.connectedFields requiresContext Boolean
Default: True

UI.connectedFields invocationGrouping String(12) enum #optional This annotation ex-

 Note
invocations of the
needs to be speci-
tiple instances are
fied if you use
grouped.
UI.lineItem.type of
A user selects five

• ISOLATED:
items in a list and
Describes the er-
wants to copy them.
ror handling when
One item cannot be
an action cannot
be executed on all
not be copied, the
selected instances:
The action is exe-
copied.
ple:
stance on which the
an action cannot be
executed on one of
ces, the action is
executed on none
of the selected in-
stances.
Default: ISOLATED
UI.connectedFields semanticObjectAction String(120) This annotation refers

to the name of an
tic object is taken
from @Consump-
tion.semanticObject
ing view.

UI.connectedFields value ElementRef For type AS_ADDRESS: This annotation refers

to a value.
• Value element
must not used
when a structural
element is anno-
tated. Use instead
@com.sap.vocabu-
laries.Communica-
tion.v1.Address (or
a shorter alias-
qualified name) as
value.
be used when an el-
ement of an asso-
ciated CDS view is
annotated. A value
mantics.address on
rectly associated.
• If you want to
reference @Seman-
tics.address on a
view that is indi-
rectly associated,
use a path starting
All other types:

not be used when
an element is anno-
tated, in this case
the annotated ele-
ment is the value.
be used when an
path to an element
of the associated
view.
UI.connectedFields valueQualifier String(120)

UI.connectedFields targetElement ElementRef This annotation repre-

ated CDS view. The
annotation, you can
getElement when you
use the annotation
UI.lineItem.type of
type WITH_NAVIGA-
TION_PATH.
You might, for ex-

on the object view
floorplan.
UI.connectedFields url ElementRef This annotation rep-

ify UI.fieldGroup.url that contains a naviga-
annotation UI.con-
nectedFields..type
of type WITH_URL..
Example

10 What's New
Here are descriptions of some of the changes of interest (delta information) to developers made to ABAP
RESTful Application Programming Model:
Version 2302 [page 1370]
Version 2022 FPS00 [page 1372]
10.1 Version 2302

1370 PUBLIC What's New
10.1.1 ABAP RESTful Application Programming Model
Side Effects
You can now use side effects in your RAP behavior definition to trigger reloads based on user input in draft-
enabled UI services.
For more information, see Side Effects [page 133].
Integrating BTP Workflow Services
You can now integrate BTP workflow services in your RAP BO to use the workflow capability for process
automation .
For more information, see Integrating BTP Workflow Services [page 1089].
10.2 Version 2211
Static and Dynamic Feature Control for Large Objects
You can now use dynamic and static feature control for large objects in OData V2.
For more information, see Working with Large Objects [page 882].
Define Own Authorization Context and Priviledged Access
You can use the own authorization context to define the Identity and Access signature for a RAP BO. The
own authorization context lists all authorization objects required during the RAP BO consumption at runtime.
In combination a RAP BO can offer privledged access for consumers to allows the them to bypass certain
authorization objects.
For more information, see Authorization Control [page 80].

What's New PUBLIC 1371
Static Feature Controls for Fields in RAP BO Interfaces
You can define static feature control for fields in a RAP BO interface.
For more information, see Business Object Interface [page 194].
abapGit Plugin
All RAP related development objects can be pushed and pulled with the abapGit plugin.
Modeling Parameters for Non-Standard Operations
There is now documentation about how to model parameters and use their representations in ABAP.
For more information, see Modeling Parameters for Non-Standard Operations [page 887].
10.3 Version 2022 FPS00
Using Client-Independent Tables in Transactional Apps with Draft

Capabilities
You can now use client-independent tables as data sources for managed transactional apps with draft
capabilities.
 For more information, see Using Client-Independent Database Tables [page 217].
Multiple Message Targets in OData V4 RAP Services
OData V4 now supports multiple message targets. In the reported structure of RAP handler methods, you can
define multiple elements in the derived type component %element. These elements are interpreted by OData
and are highlighted on a Fiori V4 UI.
 For more information, see OData V4 [page 279].

Using UI.hidden Annotation for Action Input Parameters
You can now use UI.hidden with action input parameters fields to prevent the input fields from being
displayed on the UI , while leaving the input parameter fields available for a WebAPI client.
 For more information, see UI Annotations [page 1260].
Read Access Logging (RAL)
You can now use Read Access Logging for your RAP services. With this feature you can monitor database read
accesses.
Service Binding Errors in ATC Checks
ATC checks now lase expose errors that are related to a RAP service. These errors are displayed in the service
binding. They can now also be retrieved by running ATC checks for the service.
 For more information, see Service Binding [page 207].
Late Numbering for Managed Implementation Type
Late numbering can now also be used for the managed implementation type.
 For more information, see Late Numbering [page 28].
Consumption of released Business Objects
You can now consume released Business Objects via C1 released RAP BO Interfaces.
 For more information, see Business Object Interface Consumption [page 1085].
Instance Factory Actions
You can now use instance factory actions to model actions that create new isntances based on an input
instance. Instance factory actions can be useful if you want to copy specific values of an instance.
 For more information, see Action Definition [page 102].

Operations in Reported Response Parameter
When providing the reported response parameter in methods of the RAP behavior pool, you must provide the
operation the provided message belongs to. The derived type component %op provides all available operations.
The relevant one must be marked with if_abap_behv=>mk-on.
 For more information, see General RAP BO Implementation Contract [page 157].
Generate ABAP Repository Objects
With the Generate ABAP Repository Objects wizard, you can now generate RAP artifacts for an end-to-end
transactional application based on a database table.
Semantic Versioning for OData V4 Service
In the service binding editor, you can now specify semantic versioning in the service version for OData V4
service by adding minor and patch version.
Changes in the Consumption or Provisioning of RAP BOs
You can find an overview of changes in the RAP framework in SAP Note 3107113 and 2943761 .
Filter Tree API for Unmanaged Queries
You can now use the method get_as_tree of the interface if_rap_query_filter in an unmanaged query
to retrieve the filter conditions in an easily parsable expression tree.
 For more information, see Implementing Filtering in an Unmanaged Query [page 925]
Business Object Interfaces
You can now use business object interfaces to introduce an additional abstraction layer between a RAP
base BO and its business service projection layer With.RAP BO interfaces, you can technically decouple
requirements for stable consumption from the behavior and data model of the underlying RAP base BO.
 For more information, see Business Object Interface [page 194].

Add Dimension to Query at Runtime (New)
With 2021 support package 1, some BI-tools like WebDynpro Grid offer the possibility to add dimensions
from the cube view with the "free"-axis at runtime. With this, it isn't necessary to include all the dimensions
into the CDS analytical query view that should be available at runtime. Only the most common ones can
be add to the query view. With this the UI view becomes clearer and performance is slightly better. Since
the cube may contain sensible dimensions that not all users are allowed to see, a query has to be enabled
for this feature with the header annotation @Analytics.Settings.runtimeExtensibility.allowed:
true. Dimensions that shouldn't be exposed at runtime can be excluded with the annotation
@Analytics.Setting.excludedFromRuntimeExtensibility on field level in the underlying cube view.
 For more information, see Analytics Annotations [page 1113].
You can now define business object interfaces to introduce an additional abstraction layer between a RAP BO
and its business service projection layer With RAP BO interfaces, you can technically decouple requirements
for stable consumption from the behavior and data model of the underlying RAP business object. You can
release RAP BO interfaces for C1 with visibility Use in Cloud Development to enable EML-consumption
between different software components.
 For more information, see Business Object Interface [page 194] and .
Unmanaged/additional save with full data
It is now possible to use the option WITH FULL DATA for an unmanaged/additional save of a managed BO.
With this option enabled, when an instance is modified, not only the changed fields but all fields are provided
into the save_modified method.
 For more information, see SAVE [page 231].
Large Objects
Business Events
You can now define and raise business events in a RAP BO or in a RAP BO behavior extension. Business events
provide the opportunity of light-weight, decoupled process integration based on standardized and stable APIs

and they are now a native part of the SAP - ABAP RESTful Application Programming Model. With the
RAP Business Event Bindings Editor, you can create RAP Event Bindings which are needed to provide
a mapping between the definition of RAP Events via behavior definition (BDEF) and the external representation
of Business Events.
For more information, see Business Events [page 135].
Extensibility-Enabling for RAP Business Objects
RAP extensibility is based on an opt-in approach to provide you with fine-granular control over which parts
of your business object can be extended. You can easily enable your RAP BO and define for which use case
extensions can be created. Using the respective CDS annotations, the BDEF syntax and the Extend release
contract , you can decide if you want to enable your BO for data model extensions, behavior extensions or node
extensions depending on your business requirements.
For more information, see RAP Extensibility-Enablement [page 949].
Extending RAP Business Objects
RAP enables you to build upgrade-safe and lifecycle-stable extensions using well-defined extension anchors
of the original business object. You can extend the data model and behavior of the original RAP BO behavior
and build data model extensions, behavior extensions or node extensions to adapt a RAP BO to your business
requirements.
For more information, see RAP Extensions [page 978].
Repeatable Actions and Functions
You can now define actions and functions that can be executed multiply on the same instance in the same
request.
For more information, see Action Definition [page 102] and Function Definition [page 112].
More Flexible Usage of Parameters
In Analytics with CDS, parameters are restricted to single values. More general input is often required in
analytics. @AnalyticsDetails.variable can be used to create any variable in the analytic query from a
parameter.
For more information, see Analytics Annotations [page 1138].

10.4 Version 2208
For more information, see Business Object Interface [page 194] and .
For more information, see SAVE [page 231].
Large Objects
Business Events
You can now define and raise business events in a RAP BO or in a RAP BO behavior extension. Business events
provide the opportunity of light-weight, decoupled process integration based on standardized and stable APIs
and they are now a native part of the SAP - ABAP RESTful Application Programming Model. With the
RAP Business Event Bindings Editor, you can create RAP Event Bindings which are needed to provide

a mapping between the definition of RAP Events via behavior definition (BDEF) and the external representation
of Business Events.
For more information, see Business Events [page 135].
Extensibility-Enabling for RAP Business Objects
RAP extensibility is based on an opt-in approach to provide you with fine-granular control over which parts
of your business object can be extended. You can easily enable your RAP BO and define for which use case
extensions can be created. Using the respective CDS annotations, the BDEF syntax and the Extend release
contract , you can decide if you want to enable your BO for data model extensions, behavior extensions or node
extensions depending on your business requirements.
For more information, see RAP Extensibility-Enablement [page 949].
Extending RAP Business Objects
RAP enables you to build upgrade-safe and lifecycle-stable extensions using well-defined extension anchors
of the original business object. You can extend the data model and behavior of the original RAP BO behavior
and build data model extensions, behavior extensions or node extensions to adapt a RAP BO to your business
requirements.
For more information, see RAP Extensions [page 978].
Repeatable Actions and Functions
You can now define actions and functions that can be executed multiply on the same instance in the same
request.
For more information, see Action Definition [page 102] and Function Definition [page 112].
More Flexible Usage of Parameters
In Analytics with CDS, parameters are restricted to single values. More general input is often required in
analytics. @AnalyticsDetails.variable can be used to create any variable in the analytic query from a
parameter.
For more information, see Analytics Annotations [page 1138].

10.5 Version 2205
 For more information, see Business Object Interface [page 194] and .
 For more information, see SAVE [page 231].
10.6 Version 2202

Filter Tree API for Unmanaged Queries
You can now use the method get_as_tree of the interface if_rap_query_filter in an unmanaged query
to retrieve the filter conditions in an easily parsable expression tree.
 For more information, see Implementing Filtering in an Unmanaged Query [page 925]
You can now use business object interfaces to introduce an additional abstraction layer between a RAP
base BO and its business service projection layer With.RAP BO interfaces, you can technically decouple
requirements for stable consumption from the behavior and data model of the underlying RAP base BO.
 For more information, see Business Object Interface [page 194].
Add Dimension to Query at Runtime (New)
With 2021 support package 1, some BI-tools like WebDynpro Grid offer the possibility to add dimensions
from the cube view with the "free"-axis at runtime. With this, it isn't necessary to include all the dimensions
into the CDS analytical query view that should be available at runtime. Only the most common ones can
be add to the query view. With this the UI view becomes clearer and performance is slightly better. Since
the cube may contain sensible dimensions that not all users are allowed to see, a query has to be enabled
for this feature with the header annotation @Analytics.Settings.runtimeExtensibility.allowed:
true. Dimensions that shouldn't be exposed at runtime can be excluded with the annotation
@Analytics.Setting.excludedFromRuntimeExtensibility on field level in the underlying cube view.
 For more information, see Analytics Annotations [page 1138].
You can find an overview of changes in the RAP framework in SAP Note 2943761 .

10.7 Version 2111
Using Client-Independent Tables in Transactional Apps with Draft

Capabilities
You can now use client-independent tables as data sources for managed transactional apps with draft
capabilities.
Multiple Message Targets in OData V4 RAP Services
OData V4 now supports multiple message targets. In the reported structure of RAP handler methods, you can
define multiple elements in the derived type component %element. These elements are interpreted by OData
and are highlighted on a Fiori V4 UI.
 For more information, see OData V4 [page 279].
Using UI.hidden Annotation for Action Input Parameters
You can now use UI.hidden with action input parameters fields to prevent the input fields from being
displayed on the UI , while leaving the input parameter fields available for a WebAPI client.
 For more information, see UI Annotations [page 1260].
Read Access Logging (RAL)
You can now use Read Access Logging for your RAP services. With this feature you can monitor database read
accesses.

Service Binding Errors in ATC Checks
ATC checks now lase expose errors that are related to a RAP service. These errors are displayed in the service
binding. They can now also be retrieved by running ATC checks for the service.
 For more information, see Service Binding [page 207].
Late Numbering for Managed Implementation Type
Late numbering can now also be used for the managed implementation type.
 For more information, see Late Numbering [page 28].
Consumption of released Business Objects
You can now consume released Business Objects via C1 released RAP BO Interfaces.
 For more information, see Business Object Interface Consumption [page 1085].
Instance Factory Actions
You can now use instance factory actions to model actions that create new isntances based on an input
instance. Instance factory actions can be useful if you want to copy specific values of an instance.
 For more information, see Action Definition [page 102].
Operations in Reported Response Parameter
When providing the reported response parameter in methods of the RAP behavior pool, you must provide the
operation the provided message belongs to. The derived type component %op provides all available operations.
The relevant one must be marked with if_abap_behv=>mk-on.
 For more information, see General RAP BO Implementation Contract [page 157].
Generate ABAP Repository Objects
With the Generate ABAP Repository Objects wizard, you can now generate RAP artifacts for an end-to-end
transactional application based on a database table.

You can find an overview of changes in the RAP framework in SAP Note 3107113 .
Using Service Binding Editor for InA Service
You can now expose CDS Analytical Queries via Information Access (InA) service using service binding. The
binding type must be chosen while creating the service binding for the service. To expose CDS Analytical Query
as an InA service, the CDS view must be added to the service definition. This service definition must be used to
create the service binding.
 For more information, see .
Creating Service Consumption Model for RFC and Web Service
You can now create a service consumption model to generate proxies for remote function call (RFC) and Web
Service.
 For more information, see
•
•
Nested Determinations on modify
It is now possible to trigger a determination on modify by another determination on modify.
 For more information, see Determinations [page 119].

Always Flag in Determine Actions
You can now use the flag always for determinations and validations that are assigned to a determine action.
When the determine action is called, determinations and validations with this flag are executed regardless of
their trigger conditions.
 For more information, see Actions [page 102] > Determine Action.
You can now define global feature control for feature control that is independent of a business object instance.
 For more information, see Global Feature Control [page 132].
Global Authorization Control
You can now define global authorization control to check authorization for incoming requests, in particular for
static operations.
 For more information, see Authorization Control [page 80].
Augmenting Incoming Requests
You can now define augmentation in your projection behavior definition to enhance incoming requests with
custom implementation, for example with default values.
 For more information, see Operation Precheck [page 115] > Augmentation for Modify Operations.
Quick Fixes For Creating Behavior Implementations
In case of missing implementation classes or missing methods, corresponding warnings are now displayed
in the Behavior Definition Editor and in the Problems View. You can apply Quick Fixes to generate the entire
implementation class or missing methods.

Quick Fixes to Generate Missing Methods
Implementing Unmanaged Early Numbering in Managed Business Objects
You can now use unmanaged early numbering to automatically draw keys for your business object during the
CREATE.
 For more information, see Early Numbering [page 24].
Retrieving Permission Information from Business Objects
You can now use the EML statement Get Permissions to retrieve information about feature control and
authorization permissions from business objects on global and instance level.
 For more information, see Accessing Business Objects with EML [page 240].
Implementing Cleanup in Managed Business Objects
You can now implement the cleanup method in managed BOs if an additional or an unmanaged save is defined
in the behavior definition. In this implementation you can handle legacy coding and dependent objects. The
cleanup for managed BOs must be defined in the behavior definition and implemented in the redefined method
in the local saver class.
 For more information, see CLEANUP [page 233].

Adding Actions and Functions in a Projection Behavior Definition
You can now add actions and functions to a projection behavior definition. You can also add authorization for
the new actions and functions.
 For more information, see Actions [page 101] and Functions [page 111].
Using Strict Mode
You can now implement your RAP business object in strict mode to ensure that your BO is modeled and
implemented in accordance with the RAP best practices.
 For more information, see Strict Mode [page 184].
RAP BO Contract
Rules on how to implement a RAP BO are now available in the RAP documentation.
 For more information, see RAP Business Object Contract [page 156].
Developing a RAP BO that Supports Multi-Inline-Editing on a Fiori UI
You can now implement a RAP business object with a singleton mechanism to support multi-inline-editing on a
Fiori UI.
 For more information, see Developing Transactional Apps with Multi-Inline-Edit Capabilities [page 693].
Flag always for Determinations/Validations on Subentities
You can now use the always flag in determine actions also for determinations or validations that act on
subentities.
 For more information, see Determine Actions [page 127].
 For more information on the syntax, see CDS BDL - determine actions (ABAP - Keyword Documentation).
Flexible Association Modeling
It is now possible to define associations to CDS projection view entities in CDS view entities in order to model
relationships between consumption / projection layers.

It is not supported to retrieve fields or other associations via such association.
 For more information on the syntax, see CDS DDL - CDS View Entity, ASSOCIATION (ABAP - Keyword
Documentation) .
Using AUTO FILL CID Option
In EML statements for static operations, you can now use the option AUTO FILL CID. This option ensures that
%cid is filled with a value automatically generated by the framework.
 For more information, see MODIFY [page 244].
 For more information on the syntax, see MODIFY ENTITY, ENTITIES, field_spec (ABAP - Keyword
Documentation).
Harmonization of Commit Work and Commit Entities
Commit Work and Commit Entities have been harmonized. so that Commit Work now triggers the RAP
save sequence.
Early Unmanaged Numbering in Unmanaged Business Objects with Draft
You can now use early unmanaged numbering in unmanaged buiness objects with managed draft.
Field Control for Modify-Enabled Fields
Virtual or denormalized fields are readonly by default. You can modify-enable them in a CDS projection
behavior definition with the syntax field (modify). Now, you can also add field characteristics to such
fields.
 For more information about the syntax, see CDS BDL - field characteristics, projection BDEF (ABAP -
 For more information on the usage, see Editing Language-Dependent Fields [page 854].

Mapping for Action and Function Parameters
You can now map names of action and function parameters that are represented as abstract entities to ABAP
dictionary tables and structures.
 For more information, see CDS BDL - type mapping (ABAP - Keyword Documentation) .
COMMIT ENTITIES in Simulation Mode
You can now use the COMMIT ENTITIES statement in simulation mode. This triggers the save sequence of
RAP BOs without actually saving data.
 For more information, see COMMIT ENTITIES [page 255].
 For more information on the syntax, see COMMIT ENTITIES (ABAP - Keyword Documentation).
Suppress Fields in Transactional Handling
You can now remove fields that are only added to a RAP BO data model for technical reasons from the
appearance in all behavior-definition-related generated components, for example in derived types or in EML
fields. The annotation @Consumption.hidden:true is a prerequisite for this.
Syntax in CDS projection or abstract behavior definition:
projection | abstract;

...
define behavior for BO_Entity
{
field ( suppress ) TechnicalField;
...

}
Authorization and Feature Control Checks in Unmanaged Business Objects
The implementation for authorization and feature control in the corresponding RAP handler methods is now
also called during every modify operation in business objects with unmanaged implementation type.
 For more information, see the runtime diagrams of Update Operation [page 91], Delete Operation [page 94],
Create by Association Operation [page 97], and Action Runtime [page 108].

Delegating Authorization Checks
You can now use the syntax authorization: update in the behavior definition to delegate an authorization
check for delete, create-by-association, or action operation to the authorization check for the update
operation.
 For more information, see Authorization Definition [page 83].
Additional Implementation for Draft Actions
You can now add an additional implementation for all draft actions to extend the RAP inherent draft
life-cycle. The additional implementation is defined in the behavior definition with with additional
implementation and implemented in the behavior pool.
 For more information, see Draft Actions [page 53].
Runtime Changes for Cleanup Execution
The Cleanup is now called after a ROLLBACK/COMMIT ENTITIES statement also for any kind of instance
access including lock operation, precheck, instance authorization, and instance features.
Idempotency for OData V4 services
Idempotent behavior is now supported for OData V4 services. With this feature, it is guaranteed that
synchronous messages are delivered exactly once.
RAP Reuse Data Elements
You can now use reuse data elements for the administrative fields in RAP applications.
 For more information, see RAP Reuse Data Elements [page 210].
Unit and Currency Types as Built-In Entity Sets
In OData V2 services, unit and currency types are automatically added to the service metadata as built-in
entity sets. With this feature, unit and currency values are always displayed correctly and validated regarding
decimals on a UI.

 For more information, seeService Binding [page 207].
Fail Causes for failed in RAP Handler Methods
The fail causes disabled, readonly and dependency can now be provided in the response parameter
failed of RAP handler methods.
 For more information, seeGeneral RAP BO Implementation Contract [page 157].
Using Service Binding Editor for SQL Service
You can now expose a RAP business service as an SQL service. The binding type must be chosen on creating
the service binding for the service.
Save Actions for Managed BOs
You can now use actions that are executed only during the save sequence. On-save actions are defined in the
behavior definition with the following syntax:
[static] save action actionName [ parameter parType ] [ result card resType ];
You can find an overview of changes in the RAP framework in SAP Note3093832 .

10.9 Version 2108
Authorization and Feature Control Checks in Unmanaged Business Objects
The implementation for authorization and feature control in the corresponding RAP handler methods is now
also called during every modify operation in business objects with unmanaged implementation type.
 For more information, see the runtime diagrams of Update Operation [page 91], Delete Operation [page 94],
Create by Association Operation [page 97], and Action Runtime [page 108].
Delegating Authorization Checks
You can now use the syntax authorization: update in the behavior definition to delegate an authorization
check for delete, create-by-association, or action operation to the authorization check for the update
operation.
 For more information, see Authorization Definition [page 83].
Additional Implementation for Draft Actions
You can now add an additional implementation for all draft actions to extend the RAP inherent draft
life-cycle. The additional implementation is defined in the behavior definition with with additional
implementation and implemented in the behavior pool.
 For more information, see Draft Actions [page 53].
Runtime Changes for Cleanup Execution
The Cleanup is now called after a ROLLBACK/COMMIT ENTITIES statement also for any kind of instance
access including lock operation, precheck, instance authorization, and instance features.

Idempotency for OData V4 services
Idempotent behavior is now supported for OData V4 services. With this feature, it is guaranteed that
synchronous messages are delivered exactly once.
RAP Reuse Data Elements
You can now use reuse data elements for the administrative fields in RAP applications.
 For more information, see RAP Reuse Data Elements [page 210].
Unit and Currency Types as Built-In Entity Sets
In OData V2 services, unit and currency types are automatically added to the service metadata as built-in
entity sets. With this feature, unit and currency values are always displayed correctly and validated regarding
decimals on a UI.
 For more information, seeService Binding [page 207].
Fail Causes for failed in RAP Handler Methods
The fail causes disabled, readonly and dependency can now be provided in the response parameter
failed of RAP handler methods.
 For more information, seeGeneral RAP BO Implementation Contract [page 157].
Using Service Binding Editor for SQL Service
You can now expose a RAP business service as an SQL service. The binding type must be chosen on creating
the service binding for the service.

Save Actions for Managed BOs
You can now use actions that are executed only during the save sequence. On-save actions are defined in the
behavior definition with the following syntax:
[static] save action actionName [ parameter parType ] [ result card resType ];
You can find an overview of changes in the RAP framework in SAP Note 3070134
10.10 Version 2105
Adding Actions and Functions in a Projection Behavior Definition
You can now add actions and functions to a projection behavior definition. You can also add authorization for
the new actions and functions.
 For more information, see Actions [page 101] and Functions [page 111].
Using Strict Mode
You can now implement your RAP business object in strict mode to ensure that your BO is modeled and
implemented in accordance with the RAP best practices.
 For more information, see Strict Mode [page 184].
RAP BO Contract
Rules on how to implement a RAP BO are now available in the RAP documentation.

 For more information, see RAP Business Object Contract [page 156].
Developing a RAP BO that Supports Multi-Inline-Editing on a Fiori UI
You can now implement a RAP business object with a singleton mechanism to support multi-inline-editing on a
Fiori UI.
 For more information, see Developing Transactional Apps with Multi-Inline-Edit Capabilities [page 693].
Using AUTO FILL CID Option
In EML statements for static operations, you can now use the option AUTO FILL CID. This option ensures that
%cid is filled with a value automatically generated by the framework.
 For more information, see MODIFY [page 244].
 For more information on the syntax, see MODIFY ENTITY, ENTITIES, field_spec (ABAP - Keyword
Documentation).
Flag always for Determinations/Validations on Subentities
You can now use the always flag in determine actions also for determinations or validations that act on
subentities.
 For more information, see Determine Actions [page 127].
 For more information on the syntax, see CDS BDL - determine actions (ABAP - Keyword Documentation).
COMMIT ENTITIES in Simulation Mode
You can now use the COMMIT ENTITIES statement in simulation mode. This triggers the save sequence of
RAP BOs without actually saving data.
 For more information, see COMMIT ENTITIES [page 255].
 For more information on the syntax, see COMMIT ENTITIES (ABAP - Keyword Documentation).
Mapping for Action and Function Parameters
You can now map names of action and function parameters that are represented as abstract entities to ABAP
dictionary tables and structures.

 For more information, see CDS BDL - type mapping (ABAP - Keyword Documentation) .
Suppress Fields in Transactional Handling
You can now remove fields that are only added to a RAP BO data model for technical reasons from the
appearance in all behavior-definition-related generated components, for example in derived types or in EML
fields. The annotation @Consumption.hidden:true is a prerequisite for this.
Syntax in CDS projection or abstract behavior definition:
projection | abstract;

...
define behavior for BO_Entity
{
field ( suppress ) TechnicalField;
...

}
Flexible Association Modeling
It is now possible to define associations to CDS projection view entities in CDS view entities in order to model
relationships between consumption / projection layers.
It is not supported to retrieve fields or other associations via such association.
 For more information on the syntax, see CDS DDL - CDS View Entity, ASSOCIATION (ABAP - Keyword
Documentation) .
Field Control for Modify-Enabled Fields
Virtual or denormalized fields are readonly by default. You can modify-enable them in a CDS projection
behavior definition with the syntax field (modify). Now, you can also add field characteristics to such
fields.
 For more information about the syntax, see CDS BDL - field characteristics, projection BDEF (ABAP -
 For more information on the usage, see Editing Language-Dependent Fields [page 854].
Early Unmanaged Numbering in Unmanaged Business Objects with Draft
You can now use early unmanaged numbering in unmanaged buiness objects with managed draft.

Harmonization of Commit Work and Commit Entities
Commit Work and Commit Entities have been harmonized. so that Commit Work now triggers the RAP
save sequence.
Possibly Incompatible Changes for ABAP RESTful Application Programming
You can find an overview of possibly incompatible changes for the ABAP RESTful Application Programming
Model in SAP Note 3050328 .
Using Service Binding Editor for OData V4 Service
You can now expose a RAP business service as an OData V4 service. The binding type must be chosen on
creating the service binding for the service.
 For more information, see Service Binding [page 207] and .
10.12 Version 2102
Implementing Unmanaged Early Numbering in Managed Business Objects
You can now use unmanaged early numbering to automatically draw keys for your business object during the
CREATE.

Retrieving Permission Information from Business Objects
You can now use the EML statement Get Permissions to retrieve information about feature control and
authorization permissions from business objects on global and instance level.
 For more information, see Accessing Business Objects with EML [page 240].
Implementing Cleanup in Managed Business Objects
You can now implement the cleanup method in managed BOs if an additional or an unmanaged save is defined
in the behavior definition. In this implementation you can handle legacy coding and dependent objects. The
cleanup for managed BOs must be defined in the behavior definition and implemented in the redefined method
in the local saver class.
You can find an overview of possibly incompatible changes for the ABAP RESTful Application Programming in
SAP Note 3017989 .
10.13 Version 2011
Using Service Binding Editor for OData V4 Service
You can now expose a RAP business service as an OData V4 service. The binding type must be chosen on
creating the service binding for the service.
 For more information, see Service Binding [page 207] and .

Using Service Binding Editor for InA Service
You can now expose CDS Analytical Queries via Information Access (InA) service using service binding. The
binding type must be chosen while creating the service binding for the service. To expose CDS Analytical Query
as an InA service, the CDS view must be added to the service definition. This service definition must be used to
create the service binding.
Setting Default Parameter Values in OData V4 UI Services
It is now possible to model a default value for action input parameters in OData V4 UI services. The default
value is defined with the annotation @Consumption.defaultValue: '<value>' in the abstract CDS entity
that defines the input parameter. This feature is only available for UI business services with OData V4.
 For more information, see Action Definition [page 102] > Input Parameter.
Nested Determinations on modify
It is now possible to trigger a determination on modify by another determination on modify.
 For more information, see Determinations [page 119].
Always Flag in Determine Actions
You can now use the flag always for determinations and validations that are assigned to a determine action.
When the determine action is called, determinations and validations with this flag are executed regardless of
their trigger conditions.
 For more information, see Actions [page 102] > Determine Action.
You can now define global feature control for feature control that is independent of a business object instance.
 For more information, see Global Feature Control [page 132].

Global Authorization Control
You can now define global authorization control to check authorization for incoming requests, in particular for
static operations.
Augmenting Incoming Requests
You can now define augmentation in your projection behavior definition to enhance incoming requests with
custom implementation, for example with default values.
 For more information, see Operation Precheck [page 115] > Augmentation for Modify Operations.
Non-Locking Actions
You can now suppress the locking mechanism for action execution with the syntax (lock: none) on action
definitions in the behavior definition.
 For more information, see Action Definition [page 102] > Non-Locking Action.
SAP Note 2943761 .
Quick Fixes For Creating Behavior Implementations
In case of missing implementation classes or missing methods, corresponding warnings are now displayed
in the Behavior Definition Editor and in the Problems View. You can apply Quick Fixes to generate the entire
implementation class or missing methods.

Quick Fixes to Generate Missing Methods
Draft Support for RAP Business Services
The ABAP RESTful Application Programming Model now provides draft support for your business services.
Draft-enabled business objects ensure that transactional data does not get lost, even if work is interrupted or
continued from a different device.
You draft-enable your business object by using the keyword with draft in the behavior definition. Draft
capabilities can be included for both business object implementation types, managed and unmanaged.
 For more information, see Draft [page 46].
Draft Scenario on GitHub
You can now download a RAP managed business service with draft from GitHub. The development objects are
now available as part of the ABAP Flight Reference Scenario that you can download directly into your ABAP
system.
 For more information, see Downloading the ABAP Flight Reference Scenario [page 314].

Controlling Active Data Access in Draft Business Objects
You can now define a designated field, the total ETag field, that controls concurrent access on active data
in draft business objects. The RAP runtime framework checks its value on every transition from draft to active
data to prevent concurrent BO consumers from overwriting each other without any information.
The total ETag is defined in the behavior definition and is updated by the RAP runtime framework
automatically if annotated with the annotation @Semantics.systemDateTime.lastChangedAt: true in
the corresponding CDS view.
 For more information, see Total ETag [page 51].
Working with Determinations and Validations
Determinations and validations are now processed by the determinations-validations-machine (DVM). You can
now define determinations and validations with all three standard operation triggers { create | update
|delete}, and in combination with field triggers. In addition, the method declaration in the behavior pool uses
different syntax:
METHODS method_name FOR VALIDATE ON SAVE

IMPORTING keys FOR AliasedEntityName~ValidationName.
METHODS method_name FOR DETERMINE ON MODIFY|SAVE

 For more information, see Validations [page 123] or Determinations [page 119].
Executing Determinations and Validations on Request
New determine actions allow the business object consumer to execute determinations and validations without
fulfilling the trigger conditions. You can now assign determinations and validations to a determine action that is
called by a consumer's trigger, just like any other actions.
 For more information, see Action Definition [page 102] > Determine Action
Prechecking Modify Operations
You can now prevent illegal changes from reaching the application buffer by prechecking modify operations.
 For more information, see Operation Precheck [page 115].

Consumer hints in the OData service metadata now include authorization control by a path expression
on the respective operation. That means, if you define authorization control for your business object, the
authorization-relevant entity sets receive a path description instead of a static information about their ability to
be updated or deleted. In addition, the corresponding properties are included in the property list of the entity
type.
 For more information, see Be prepared for the Upgrade 2008! Clean Up your RAP Implementation to Pass the
Reinforced RAP Contract Checks .
RAP Runtime Checks
Stricter RAP runtime checks are introduced to help you make your RAP implementation consistent, user-
friendly, and compatible to further RAP features. These runtime checks affect
• creating and updating read only fields via EML,

• executing modify calls in a late save phase,
• consuming actions or functions with parameters exceeding the defined length.
Documenting Service Binding
You can now provide documentation using knowledge transfer documents (KTD) for service binding.

Feature Control
You can now use mandatory:create to assure that a field is filled in during a create operation and
readonly:update to assure that the field value isn't changed during modify operations.
 For more information, see Instance Feature Control [page 129]
SAP Note 2943761 .
Implementing Own Locking Logic for Managed Business Objects
You can now define an unmanaged lock in a managed scenario. The unmanaged lock mechanism must be
defined in the behavior definition with the syntax lock master unmanaged and implemented in the behavior
pool in the method FOR LOCK, just like in an unmanaged scenario. The method is then invoked during
runtime.
 For more information, see Pessimistic Concurrency Control (Locking) [page 38].
Using dependent by _Association in Behavior Definition
You can now use the syntax dependent by _Association for lock, ETag, or authorization dependent
entities. The association to the respective master entity must be explicitly specified in the behavior definition
and implemented when using the unmanaged scenario.
 For more information, see Defining Elementary Behavior for Ready-to-Run Business Object [page 390] or
Adding Behavior to the Business Object [page 509].
Using Client-Independent Tables in Managed Scenarios
The RAP managed BO runtime now supports client-independent database tables.

Dynamic Operation Control for Create By Association
You can now dynamically control the create by association operation. The syntax for defining dynamic feature
control is the following:
_association {create (features: instance); }
Like other feature controls, the control for the create by association must be implemented in the behavior pool
with the method FOR FEATURES.
 For more information, see Instance Feature Control [page 129].
New Read-Only Associations in CDS Projection Views
It is now possible to define new read-only associations in the projection view. These associations can be
reused to display additional information in a UI service, for example analytical data which is not part of the
transactional basic business object. With associations in projection views, you can model new service-specific
relationships.
The syntax for the association definition is the same as in CDS views:
association [min..max] to TargetEntity [as _Alias] on OnCondition
 For more information, see CDS Projection View [page 201].
Filtering for Null Values in OData V2 Services
OData does not foresee initial values for the following EDM data types:
• Boolean
• GUID
• Time
• DateTime
• DateTimeOffset.
Fiori Elements UIs offer the empty operator in filter bars for these fields. Although they appear as visually
empty in the UIs, the actual value sent to the client is null.
To be able to select records with empty values for these data types, the client filters null values and the filter is
transformed to filter for initial values for the backend. Real null values cannot be retrieved from the database by
filtering for them in OData V2.
 For more information, see https://www.odata.org/documentation/odata-version-2-0/ .

Understanding Runtime Processes
The concepts section in the ABAP RESTful Application Programming Model has been enhanced with
interactive diagrams so you can get a better understanding of the runtime processes for OData requests.

• Save Sequence Runtime [page 225].
Control Structure for Import Parameter in CREATE Operations
The control structure %control for import parameters of CREATE and CREATE by Association operations
is now filled according to the elements that were sent by the OData client or were marked in the EML call. In
particular this means that the application developer knows which elements are relevant for the create.
 Example
In the following example the elements agencyid, customerid, begindate, and enddate were filled by
the OData client and thus are marked in the control structure, while the other elements are not.

Provided Elements in Create for Travel
 For more information, see <method> FOR MODIFY [page 140].
Automatically Drawing Primary Key Values for Managed Business Objects
The managed runtime framework can now automatically generate key values in scenarios with UUID keys if
managed numbering is defined in the behavior definition.
Syntax for defining managed numbering in the behavior definition:



...
{
...

field ( [read only,] numbering:managed ) KeyField1, [KeyField2];

...

}

 For more information, see Automatically Drawing Primary Key Values in Managed BOs [page 850].
New Options for Action and Function Results
The BO runtime framework now supports results for actions and functions other than $self. The results can
be entities of the same BO the action is defined for, entities of other BOs, or result structures. To differentiate
between result entities and result structures the syntax element entity has been introduced.
In addition, you can now create actions, for which the action consumer can decide whether the result shall be
returned completely or only parts of it, for example the keys only. Such an action must be marked with the
keyword selective in the behavior definition.
define behavior for CDSEntity

...
** Action with result entity
action ActionName result [cardinality] entity OutputEntity
** Action with result structure
action ActionName result [cardinality] OutputStructure
** Action with selective result
action ActionName result selective [cardinality] entity OutputEntity

…
 For more information, see Actions [page 101].
Reporting Messages in ADJUST_NUMBERS and SAVE
The implicit returning parameter REPORTED is now available for the methods adjust_numbers and save. By
filling this parameter you can report information or success messages after the point of no return in the save
sequence.
 For more information, see ADJUST_NUMBERS [page 230] and SAVE [page 231].
Documenting Behavior Definitions
Now you can document behavior definitions in the Knowledge Transfer Document editor.
From the Project Explorer, select the behavior definition you want to document. Use the context menu to create
a knowledge transfer document.

Knowledge Transfer Document Editor
Defining the Service Namespace for OData Services
You can now define the OData service namespace in service definitions with the annotation
@OData.schema.name.
 For more information, see OData Annotations [page 1211].
Filling the Result Parameter for Actions
A runtime check is introduced to enforce the proper assignment of result values in action implementations
when result parameters are declared in the corresponding action definition. Whereas actions returned the
input entity if the result parameter was not filled in the action implementation before 1911, they now return the
value of the result parameter as specified in the action definition and exactly according to its implementation.
To avoid that a Fiori UI shows initial values, if nothing is returned, you must fill the result parameter for all
actions.
 For more information, see Developing Actions [page 405] and Implementing the SET_STATUS_BOOKED
Action [page 547].

Navigating More Than One Step in OData Requests
It is now possible to navigate to associated entities using more than one navigation for both, V2 and V4
services.
 Example
To request the booking supplements for the booking entity with BookingID 5 of the travel with TravelID
1, use the following syntax.
<service_URL>/Travel('1')/to_Booking('5')/to_BookingSupplement
You can link an unlimited number of entities in one OData request.
Using Type and Control Mapping
You can now define a mapping contract for applications that include unmanaged or managed business objects
based on CDS entities on the one hand, and legacy data types that are generally older and implement the
behavior or parts of it.
The general syntax for field and control (information) mapping in a behavior definition is the following:


{
...
}

 For more information, see Using Type and Control Mapping [page 861].
Integrating Additional Save in Managed Business Objects
You can now integrate Additional Save for each entity of a given business object with managed implementation
type. This is done in the behavior definition of the business object by adding the keyword with additional
save. The actual implementation of Additional Save takes place in a local saver class as part of the behavior
pool.
 For more information, see Integrating Additional Save in Managed Business Objects [page 438].
Integrating Unmanaged Save in Managed Business Objects
You can now integrate Unmanaged Save within the transactional life cycle of managed business objects. In
order to integrate Unmanaged Save into the save sequence as a part of the managed runtime, you must first

add the corresponding syntax (with unmanaged save) to the behavior definition and then implement the
saver handler method as a part of the behavior pool.
 For more information, see Integrating Unmanaged Save in Managed Business Objects [page 447].
Using Groups for Large Implementations
Until now, the implementation of business object entity's operations and actions had to be done in the Local
Types include of the behavior pool associated with that entity. Since the Local Types include can only be
changed by one developer at a time, the efficiency of development would be significantly reduced in case of
larger implementations. As a solution, the groups can be now used to divide operations, actions and other
 For more information, see Using Groups in Large Development Projects [page 212].
Using Virtual Elements
You can now define elements in CDS projection views that are not persisted on the database. These virtual
elements are defined with the new syntax element virtual. Their calculation is done in a separate ABAP
class, which is called during runtime via an ABAP code exit for virtual elements.
 For more information, see Using Virtual Elements in CDS Projection Views [page 910].
10.15 Version 2008
Draft Support for RAP Business Services
The ABAP RESTful Application Programming Model now provides draft support for your business services.
Draft-enabled business objects ensure that transactional data does not get lost, even if work is interrupted or
continued from a different device.
You draft-enable your business object by using the keyword with draft in the behavior definition. Draft
capabilities can be included for both business object implementation types, managed and unmanaged.
 For more information, see Draft [page 46].

Draft Scenario on GitHub
You can now download a RAP managed business service with draft from GitHub. The development objects are
now available as part of the ABAP Flight Reference Scenario that you can download directly into your ABAP
system.
 For more information, see Downloading the ABAP Flight Reference Scenario [page 314].
Controlling Active Data Access in Draft Business Objects
You can now define a designated field, the total ETag field, that controls concurrent access on active data
in draft business objects. The RAP runtime framework checks its value on every transition from draft to active
data to prevent concurrent BO consumers from overwriting each other without any information.
The total ETag is defined in the behavior definition and is updated by the RAP runtime framework
automatically if annotated with the annotation @Semantics.systemDateTime.lastChangedAt: true in
the corresponding CDS view.
 For more information, see Total ETag [page 51].
Working with Determinations and Validations
Determinations and validations are now processed by the determinations-validations-machine (DVM). You can
now define determinations and validations with all three standard operation triggers { create | update
|delete}, and in combination with field triggers. In addition, the method declaration in the behavior pool uses
different syntax:
METHODS method_name FOR VALIDATE ON SAVE

METHODS method_name FOR DETERMINE ON MODIFY|SAVE

 For more information, see Validations [page 123] or Determinations [page 119].
Executing Determinations and Validations on Request
New determine actions allow the business object consumer to execute determinations and validations without
fulfilling the trigger conditions. You can now assign determinations and validations to a determine action that is
called by a consumer's trigger, just like any other actions.
 For more information, see Action Definition [page 102] > Determine Action

Prechecking Modify Operations
You can now prevent illegal changes from reaching the application buffer by prechecking modify operations.
 For more information, see Operation Precheck [page 115].
Consumer hints in the OData service metadata now include authorization control by a path expression
on the respective operation. That means, if you define authorization control for your business object, the
authorization-relevant entity sets receive a path description instead of a static information about their ability to
be updated or deleted. In addition, the corresponding properties are included in the property list of the entity
type.
RAP Runtime Checks
Stricter RAP runtime checks are introduced to help you make your RAP implementation consistent, user-
friendly, and compatible to further RAP features. These runtime checks affect
• creating and updating read only fields via EML,

• executing modify calls in a late save phase,
• consuming actions or functions with parameters exceeding the defined length.
Documenting Service Binding
You can now provide documentation using knowledge transfer documents (KTD) for service binding.

Feature Control
You can now use mandatory:create to assure that a field is filled in during a create operation and
readonly:update to assure that the field value isn't changed during modify operations.
 For more information, see Instance Feature Control [page 129]
SAP Note 2943761 .
10.16 Version 2005
Implementing Own Locking Logic for Managed Business Objects
You can now define an unmanaged lock in a managed scenario. The unmanaged lock mechanism must be
defined in the behavior definition with the syntax lock master unmanaged and implemented in the behavior
pool in the method FOR LOCK, just like in an unmanaged scenario. The method is then invoked during
runtime.
 For more information, see Pessimistic Concurrency Control (Locking) [page 38].

Using dependent by _Association in Behavior Definition
You can now use the syntax dependent by _Association for lock, ETag, or authorization dependent
entities. The association to the respective master entity must be explicitly specified in the behavior definition
and implemented when using the unmanaged scenario.
 For more information, see Defining Elementary Behavior for Ready-to-Run Business Object [page 390] or
Adding Behavior to the Business Object [page 509].
Using Client-Independent Tables in Managed Scenarios
The RAP managed BO runtime now supports client-independent database tables.
Dynamic Operation Control for Create By Association
You can now dynamically control the create by association operation. The syntax for defining dynamic feature
control is the following:
_association {create (features: instance); }
Like other feature controls, the control for the create by association must be implemented in the behavior pool
with the method FOR FEATURES.
 For more information, see Instance Feature Control [page 129].
New Read-Only Associations in CDS Projection Views
It is now possible to define new read-only associations in the projection view. These associations can be
reused to display additional information in a UI service, for example analytical data which is not part of the
transactional basic business object. With associations in projection views, you can model new service-specific
relationships.
The syntax for the association definition is the same as in CDS views:
association [min..max] to TargetEntity [as _Alias] on OnCondition
 For more information, see CDS Projection View [page 201].

Filtering for Null Values in OData V2 Services
OData does not foresee initial values for the following EDM data types:
• Boolean
• GUID
• Time
• DateTime
• DateTimeOffset.
Fiori Elements UIs offer the empty operator in filter bars for these fields. Although they appear as visually
empty in the UIs, the actual value sent to the client is null.
To be able to select records with empty values for these data types, the client filters null values and the filter is
transformed to filter for initial values for the backend. Real null values cannot be retrieved from the database by
filtering for them in OData V2.
 For more information, see https://www.odata.org/documentation/odata-version-2-0/ .
Understanding Runtime Processes
The concepts section in the ABAP RESTful Application Programming Model has been enhanced with
interactive diagrams so you can get a better understanding of the runtime processes for OData requests.

• Save Sequence Runtime [page 225].
Control Structure for Import Parameter in CREATE Operations
The control structure %control for import parameters of CREATE and CREATE by Association operations
is now filled according to the elements that were sent by the OData client or were marked in the EML call. In
particular this means that the application developer knows which elements are relevant for the create.
 Example
In the following example the elements agencyid, customerid, begindate, and enddate were filled by
the OData client and thus are marked in the control structure, while the other elements are not.

Provided Elements in Create for Travel
 For more information, see <method> FOR MODIFY [page 140].
10.17 Version 2002
Automatically Drawing Primary Key Values for Managed Business Objects
The managed runtime framework can now automatically generate key values in scenarios with UUID keys if
managed numbering is defined in the behavior definition.

Syntax for defining managed numbering in the behavior definition:



...
{
...

field ( [read only,] numbering:managed ) KeyField1, [KeyField2];

...
}

 For more information, see Automatically Drawing Primary Key Values in Managed BOs [page 850].
New Options for Action and Function Results
The BO runtime framework now supports results for actions and functions other than $self. The results can
be entities of the same BO the action is defined for, entities of other BOs, or result structures. To differentiate
between result entities and result structures the syntax element entity has been introduced.
In addition, you can now create actions, for which the action consumer can decide whether the result shall be
returned completely or only parts of it, for example the keys only. Such an action must be marked with the
keyword selective in the behavior definition.
define behavior for CDSEntity

...
** Action with result entity
action ActionName result [cardinality] entity OutputEntity
** Action with result structure
action ActionName result [cardinality] OutputStructure
** Action with selective result
action ActionName result selective [cardinality] entity OutputEntity

…
 For more information, see Actions [page 101].
Reporting Messages in ADJUST_NUMBERS and SAVE
The implicit returning parameter REPORTED is now available for the methods adjust_numbers and save. By
filling this parameter you can report information or success messages after the point of no return in the save
sequence.
 For more information, see ADJUST_NUMBERS [page 230] and SAVE [page 231].
Documenting Behavior Definitions
Now you can document behavior definitions in the Knowledge Transfer Document editor.

From the Project Explorer, select the behavior definition you want to document. Use the context menu to create
a knowledge transfer document.
Knowledge Transfer Document Editor
10.18 Version 1911
Defining the Service Namespace for OData Services
You can now define the OData service namespace in service definitions with the annotation
@OData.schema.name.
 For more information, see OData Annotations [page 1211].
Filling the Result Parameter for Actions
A runtime check is introduced to enforce the proper assignment of result values in action implementations
when result parameters are declared in the corresponding action definition. Whereas actions returned the
input entity if the result parameter was not filled in the action implementation before 1911, they now return the
value of the result parameter as specified in the action definition and exactly according to its implementation.

To avoid that a Fiori UI shows initial values, if nothing is returned, you must fill the result parameter for all
actions.
 For more information, see Developing Actions [page 405] and Implementing the SET_STATUS_BOOKED
Action [page 547].
Navigating More Than One Step in OData Requests
It is now possible to navigate to associated entities using more than one navigation for both, V2 and V4
services.
 Example
To request the booking supplements for the booking entity with BookingID 5 of the travel with TravelID
1, use the following syntax.
<service_URL>/Travel('1')/to_Booking('5')/to_BookingSupplement
You can link an unlimited number of entities in one OData request.
Outsourcing UI Metadata in Metadata Extensions
You can now use metadata extensions to define CDS annotations outside of the corresponding data definition
of the CDS projection view. The use of metadata extensions allows the separation of concerns by separating
the data model from domain-specific semantics, such as UI-related information for UI consumption.
 For more information, see Adding UI Metadata to the Data Model [page 503].
Using Type and Control Mapping
You can now define a mapping contract for applications that include unmanaged or managed business objects
based on CDS entities on the one hand, and legacy data types that are generally older and implement the
behavior or parts of it.
The general syntax for field and control (information) mapping in a behavior definition is the following:


{
...
}

 For more information, see Using Type and Control Mapping [page 861].

Integrating Additional Save in Managed Business Objects
You can now integrate Additional Save for each entity of a given business object with managed implementation
type. This is done in the behavior definition of the business object by adding the keyword with additional
save. The actual implementation of Additional Save takes place in a local saver class as part of the behavior
pool.
 For more information, see Integrating Additional Save in Managed Business Objects [page 438].
Integrating Unmanaged Save in Managed Business Objects
You can now integrate Unmanaged Save within the transactional life cycle of managed business objects. In
order to integrate Unmanaged Save into the save sequence as a part of the managed runtime, you must first
add the corresponding syntax (with unmanaged save) to the behavior definition and then implement the
saver handler method as a part of the behavior pool.
 For more information, see Integrating Unmanaged Save in Managed Business Objects [page 447].
Using Groups for Large Implementations
Until now, the implementation of business object entity's operations and actions had to be done in the Local
Types include of the behavior pool associated with that entity. Since the Local Types include can only be
changed by one developer at a time, the efficiency of development would be significantly reduced in case of
larger implementations. As a solution, the groups can be now used to divide operations, actions and other
 For more information, see Using Groups in Large Development Projects [page 212].
Using Virtual Elements
You can now define elements in CDS projection views that are not persisted on the database. These virtual
elements are defined with the new syntax element virtual. Their calculation is done in a separate ABAP
class, which is called during runtime via an ABAP code exit for virtual elements.
 For more information, see Using Virtual Elements in CDS Projection Views [page 910].
Using Service Binding Editor
Previewing Fiori Elements App

In the Service Binding editor, the preview of the Fiori elements app now automatically opens in the logon
language.

ABAP platform 1909 Feature Package FPS00 relates to the:
• Back-end version: Application Server ABAP 7.54 SP00

• ADT client version: ABAP Development Tools (ADT) 3.4.
First Shipment of ABAP RESTful Application Programming Model
Starting with Application Server ABAP 7.54 SP00, the ABAP RESTful application programming model, one
of the major investment areas in the ABAP platform is available to you. It includes essential extensions of
the ABAP language, development tools and frameworks and provides the architecture for efficient end-to-end
development of intrinsically SAP HANA-optimized OData services (such as Fiori apps) in Application Server
ABAP.
The focus of this shipment is on the use of queries (ready-only apps) and the development unmanaged
transactional apps based on existing application logic.
For more information, see ABAP RESTful Application Programming Model [page 6].
For more information, see SAP - ABAP RESTful Programming Model
10.20 Version 1908
New URL for the Documentation of the ABAP RESTful Programming Model in
SAP Cloud Platform ABAP Environment
The documentation of the ABAP RESTful Programming Model for SAP Cloud Platform ABAP Environment on
the SAP Help Portal has been moved.
 The new URL is https://help.sap.com/viewer/923180ddb98240829d935862025004d6/Cloud/en-US/

289477a81eec4d4e84c0302fb6835035.html.

Developing New Managed Transactional Apps
The ABAP RESTful Programming Model now supports the managed implementation type for developing
new transactional apps. This scenario aims at use cases to develop new transactional apps from scratch.
All required standard operations must only be specified in the behavior definition to obtain a ready-to-run
business object. The business logic is implemented using actions, validations and determinations.
 For more information, see Developing Managed Transactional Apps [page 371].
Business Object Projection
You can now use the ABAP-native approach to project and to alias a subset of the business object for a specific
business service. The projection enables flexible service consumption as well as role-based service designs.
With projections, it is possible to project one business object for different role-based UIs. An example is given
in Developing a Projection Layer for Flexible Service Consumption [page 456]. The travel business object is
exposed for a processor Fiori UI and for an approver Fiori UI.
 For conceptual information about projections, see Business Object Projection [page 198].
Implementing an Unmanaged Query
A new API is available to implement an unmanaged query in a query implementation class. In an

unmanaged query, the request is delegated to the query implementation class, which must implement

the select method the interface IF_RAP_QUERY_PROVIDER. The new interface provides methods to
implement query capabilities, such as paging, filtering, sorting, or counting. It replaces the interface
IF_A4C_RAP_QUERY_PROVIDER, which is deprecated as of 1908.
 For more information about the new API, see Unmanaged Query API [page 289].
The implementation of an unmanaged query with the interface IF_RAP_QUERY_PROVIDER is described in a

new topic in the common task section.
 For more information, see Implementing an Unmanaged Query [page 917].
Server-Side Paging
Server-side paging has now been implemented to improve performance for OData calls. If the OData client
does not provide paging query options, the default paging restricts the response to 100 data records. If $top is
set to values greater than 5000, the response is reduced to 5000 data records.
Following from this, unmanaged queries require at least the implementation for paging. If the corresponding
methods are not implemented and the unmanaged query does not return the respective information, there will
be a dump during runtime
 For more information, see Implementing an Unmanaged Query [page 917].
Additions to the Unmanaged Reference Scenario
The sources for the unmanaged reference scenario have been updated with the latest features. You can explore
the new features in the sources that you can download from GitHub and in the related description in the guide
on how to develop unmanaged transactional apps based on existing application logic.
• Mapping CDS names to database field names

By defining a mapping specification in the behavior definition, you can use the mapping operator in the
behavior implementation to write records to the database that have a discrepancy between the names of
the database table fields and the CDS view field names.
 For more information, see the information for mapping in Adding Behavior to the Business Object [page
509] and the implementation in Implementing the CREATE Operation for Travel Instances [page 522].
• Message handling
The behavior processing framework provides a message object that can be used for message handling in
the behavior pool. New message handling has been added to the unmanaged scenario. The corresponding
methods are implemented in an auxiliary class that inherits from cl_abap_behv and called from the
behavior handler.
 For more information, see the information about message handling in Implementing the CREATE
Operation for Travel Instances [page 522].

Authorizations Checks for Modifying Operations in Managed Business
Objects
To protect data from unauthorized read access, the ABAP CDS provides its own authorization concept based
on a data control language (DCL). The authorization checks for read operations allow you to limit the results
returned by an entity to those results you authorize a user to see.
For business objects that are implemented for managed contract, also modifying operations in such as
standard operations create, update, delete, create by associations, and actions must be checked against
unauthorized access. With the current release, the instance-based authorization control is supported.
Adding Dynamic Feature Control
Apart from static feature control, you can now also use dynamic feature control. In this case, it depends on a
state of the node instance if certain elements or actions are available.
Dynamic feature control is defined in the behavior definition:
...

define behavior for /DMO/I_TRAVEL_M
field (features : instance ) travel_id;
action ( features: instance ) acceptedTravel result [1] $self;

…
The implementation for the control must then be implemented in the respective methods in the behavior pool.
For example, for this behavior definition, you can implement that the field travel_id is mandatory on create,
but read-only on the update operation. The action can be implemented as disabled if the travel entity is already
set to accepted, but enabled if it is not yet accepted.
 For more information, see Feature Control [page 128].
Exploring Business Objects
A business object consists of hierarchical connected entities. The behavior for each entity is defined in the
behavior definition object and implemented in the behavior classes. In the Relation Explorer, you can see
structure and behavior of a certain business object independent of the technical location. You can navigate to
all the entities and the corresponding behavior (definition and implementation).
Sometimes you might be interested in more CDS-specific aspects and want to see access control lists or test
classes. You can achieve this by switching the context from Business Object to Core Data Services context, as
you can see in the following animation.
Switching the context in the Relation Explorer

Relation Explorer provides much more features such as further contexts, for example, to display used or using
objects for a certain class.
 For further information, see .
 Cloud Service Consumption Model Wizard
In the service consumption model creation wizard:
1. ETag support can now be selected for any entity set. If ETag support is marked in your edmx file, the Etag
support checkbox is selected by default.
2. An entity set can now be selected for the generation. You can only edit the ABAP artifact name for the
entity set that you've selected for generation.
3. Issues in an entity set are displayed and these entity sets cannot be selected for generation.

 For further information, see .
10.21 Version 1905
Understanding Concepts
As an application developer, you may not only be interested on how you can implement different scenarios
and use cases for your business applications by following the stateless programming paradigm of the ABAP
RESTful programming model. It may also be important for you to understand the main concepts behind it.

The concepts section provides you with background information of ABAP RESTful programming model and
helps you to understand main concepts from both, the design time, and runtime perspective.
 For further information, see Learn [page 9].
Test Class Generation for Service Binding
You can now generate automated tests for an OData service that you've created using service binding. The test
class provides guidance on how to access the OData service using ABAP Units and provides the test code for
performing CRUD operations on an entity set.
Remote OData Access for Service Consumption Model
You can now view the code sample for performing the CRUD operations on an entity set belonging to a remote
OData service.

Defining Names for OData Entity Sets and Entity Types
You can now define external names for OData entity sets and entity types that are then used in the OData
service metadata. The annotations @OData.entitySet.name and @OData.entityType.name can now be
used in any CDS entity.
 For more information, see ObjectModel Annotations [page 1207].

10.22 Version 1902
Downloading the ABAP Flight Reference Scenario
You can now download the relevant development objects that are used in the course of the development guides
via GitHub. This enables you to import a complete OData service into your system, which you can use and
reuse for learning purposes.
Limitation: The import of a service binding artifact is not possible. To complete the OData service, you need to
create service binding in your own package.
For further information, see Downloading the ABAP Flight Reference Scenario [page 314].
Entity Manipulation Language (EML)
Entity Manipulation Language (in short: EML) is a part of the ABAP language that is used to implement the
business object’s behavior in the context of ABAP RESTful programming model. It provides a type-save read
and modifying access to data in transactional development scenarios.
For further information, see Entity Manipulation Language (EML) [page 235].
Extension of Transactional Development Guide
The development guide Developing Unmanaged Transactional Apps [page 481] was extended with a 3-tier
entity hierarchy. Booking Supplements are now part of the business object.
For further information, see Adding Another Layer to the Transactional Data Model [page 567].
In addition, the travel business object can now be consumed using EML syntax.
For further information, see Examples for Accessing Business Objects with EML [page 240].
Service Binding UI
The service binding tools come with a new UI design:
1. The binding type does not have a value populated by default.

2. The Publish and Unpublish buttons have been renamed to Activate and Deactivate.
3. Entity Set and Association was displayed with the service URL as the root node. Now, the fields are
separate and it is displayed only if the local service endpoint has been activated.

4. The Preview button is now available on the interface for previewing the SAP Fiori Elements App. This is
applicable for OData V2 UI service only.
5. The local service endpoint information now displays the service URL when it is in the activated state.
For further information, see Service Binding [page 207].
Consuming Services
The service consumption model replaces the OData client proxy to generate service artifacts for an OData
service. It comes with a new wizard and an editor to work on the generated artifacts. The service consumption
model artifact provides an overview of all abstract entities and generated behavior and service definitions that
belong to the imported service.
For further information, see .

Transactional Behavior for the Service Consumption Scenario
The guide on how to consume a remote service has been extended with transactional capabilities for additional
data. The use case of maintaining discount data in a local database is exemplified in this scenario.
For further information, see Cloud Adding Transactional Behavior to the Business Object [page 747].
Using Aggregate Data in SAP Fiori Apps
Aggregate functions, such as sum, maximum, minimum and average, as well as a counting option are now
available in the ABAP environment to be implemented in CDS and displayed in your SAP Fiori App. Annotations
are used to mark the elements as measures, whose values can be aggregated.
For further information, see Using Aggregate Data in SAP Fiori Apps [page 901].
Adding Static Feature Control in SAP Fiori Apps
In a typical transactional scenario, you have to specify which operations should be provided by the whole entity
or you must specify which fields of an entity have specific access restrictions (read-only or mandatory fields).
For further information, see Feature Control [page 128].
Freely Selectable Name for Handler Methods in Behavior Pools
The method name in handler classes is now freely selectable. What kind of method it is, is expressed by the
FOR clause.
The old syntax METHODS modify FOR BEHAVIOR … becomes now: METHODS FreeMethodName FOR
MODIFY ....
The old syntax METHODS read FOR BEHAVIOR … becomes now: METHODS FreeMethodName FOR
READ ....
The old syntax METHODS lock FOR BEHAVIOR … becomes now: METHODS FreeMethodName FOR
LOCK ....
Note that the old syntax remains valid but is no longer recommended!
For further information, see Handler Classes [page 139].

10.23 Version 1811
Defining Service Versions
The service binding tools come with a new UI design and some additional functions for versioning of (business)
services.
For further information, look at Service Binding [page 207].
Support for Compositions
The current version of the ABAP RESTful programming model supports compositions: A business object
consists of a tree of nodes where the nodes are linked by means of a special kind of associations, the
compositions. A composition is specialized association that defines a whole-part relationship. A composite
part only exists together with its parent entity (whole).
For further information, look at Providing CDS Data Model with Business Object Structure [page 487].
Developing an A2X Service
It is possible to publish an OData service as an application-to-cross application (A2X) service. That means the
service is published without information relevant for a UI service (for example Value Helps or annotation to
define a UI). An A2X service facilitates the exchange of business information between an application and any
client, including from a different system or server.
For more information, look at Develop Web APIs [page 765].
Developing a UI Service with Access to a Remote Service
With the help of the service consumption model it is now possible to consume a Web API service and build a
new SAP Fiori application by consuming the remote service. This development guide includes the definition of
a custom entity and implementing an custom query.
For more information, look at Cloud Developing a UI Service with Access to a Remote Service [page 714]

11 Glossary
You can look up all RAP-related terms in the RAP Glossary of the ABAP Keyword Documentation.
For a full list of RAP terms and their definitions, see RAP Glossary (ABAP- Keyword Documentation).

Glossary PUBLIC 1433
Important Disclaimers and Legal Information
Hyperlinks
Some links are classified by an icon and/or a mouseover text. These links provide additional information.
About the icons:
• Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your
agreements with SAP) to this:
• The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.
• SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any
damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.
• Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering an SAP-hosted Web site. By using
such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this
information.
Videos Hosted on External Platforms

Some videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any
advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within
the control or responsibility of SAP.
Beta and Other Experimental Features

Experimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by
SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use
the experimental features in a live operating environment or with data that has not been sufficiently backed up.
The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your
feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.
Example Code
Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax
and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of
example code unless damages have been caused by SAP's gross negligence or willful misconduct.
Bias-Free Language
SAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities,
genders, and abilities.

1434 PUBLIC Important Disclaimers and Legal Information
Important Disclaimers and Legal Information PUBLIC 1435
www.sap.com/contactsap
© 2023 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 https://www.sap.com/about/legal/trademark.html for

additional trademark information and notices.
THE BEST RUN

SAP - ABAP RESTful Application Programming - 2302

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

SAP - ABAP RESTful Application Programming - 2302

Uploaded by

Copyright:

Available Formats

Developer Guide | PUBLIC

SAP - ABAP RESTful Application Programming

THE BEST RUN

1 ABAP RESTful Application Programming Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

SAP - ABAP RESTful Application Programming Model

SAP - ABAP RESTful Application Programming Model

9 CDS Annotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1105

10 What's New. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1370

SAP - ABAP RESTful Application Programming Model

SAP - ABAP RESTful Application Programming Model

• Design Time [page 9]

Classification of ABAP RESTful Application Programming Model within the

SAP - ABAP RESTful Application Programming Model

ABAP Language Version

• SAP BTP ABAP environment

SAP - ABAP RESTful Application Programming Model

• SAP BTP ABAP environment

SAP - ABAP RESTful Application Programming Model

SAP - ABAP RESTful Application Programming Model

• Data Modeling and Behavior [page 12]

SAP - ABAP RESTful Application Programming Model

• UI service [page 1087]

A more detailed description is available for the following concepts:

• Data Modeling and Behavior [page 12]

SAP - ABAP RESTful Application Programming Model

2.1 Data Modeling and Behavior

SAP - ABAP RESTful Application Programming Model

Business Object [page 15]

Query [page 281]

SAP - ABAP RESTful Application Programming Model

RAP Runtime Engine

SAP - ABAP RESTful Application Programming Model

2.3 Business Object

From a formal point of view, a business object is characterized by

Structure of a Business Object

SAP - ABAP RESTful Application Programming Model

Composition Tree Reflects the Structure of a Business Object

SAP - ABAP RESTful Application Programming Model

SAP - ABAP RESTful Application Programming Model

ETag [page 33]

Draft handling [page 46]

Numbering [page 23]

Authorization Control [page 80]

SAP - ABAP RESTful Application Programming Model

For more information, see

• Create Operation [page 89]

Business Object’s Runtime

The business object runtime mainly consists of two parts:

SAP - ABAP RESTful Application Programming Model

Instantiation of Handler and Saver Classes

SAP - ABAP RESTful Application Programming Model

2.3.1 Business Object Implementation Types

Managed Implementation Type

SAP - ABAP RESTful Application Programming Model

Managed Implementation Type with Unmanaged or Additional Save

Unmanaged Implementation Type

Additional Implementation Options

SAP - ABAP RESTful Application Programming Model

2.3.2.1 RAP BO Behavior

Early and Late Numbering

SAP - ABAP RESTful Application Programming Model

Managed and Unmanaged Numbering

For more information, see: