ABAP RESTful Application

Programming Model
Part-4
 9/2/2024

Input
The following table de nes which components are imported into the function handler method.

Input Components for Functions

Function Type Obligatory Input Components

Instance function Instance identi er: %tky

Static function Content identi er: %cid

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

Function Implementation Specific Rules

Description Expected Provider Example Further information

Implementation

Successful function operation. If the function has a result Existing instance identi ers on result
parameter, the implementation instance functions.
lls the response parameter
Distinct content identi ers of
result. For every output
static functions.
parameter instance, it lists the
input identi er and the
calculated function result in
%param.

Unsuccessful function Implementation returns one row Non-existing instance identi er failed
operation. for each failed input identi er in for instance functions. (Fail
failed. It lists the input cause not_found.)
identi er with the correct fail
Unauthorized for function
cause and ags the %action
operation. This is only
component on the correct
applicable if authorization is
function. (Duplicates may
implemented in modify
appear)
handlers in an unmanaged BO.
For every input identi er listed (Fail cause unauthorized.)
in failed with fail cause other
Feature-control disabled
than not_found, there is one
operation. This is only
related error message returned
applicable if feature control is
in reported.
implemented in modify
handlers in an unmanaged BO.
(Fail cause disabled.)

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, eld, action and function control. Depending on the
permission value a RAP consumer is allowed to execute an operation, action or function, or change a eld 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

This is custom documentation. For more information, please visit the SAP Help Portal 151
 9/2/2024
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 identi ers.

For more information, see GET PERMISSIONS.

Input
The following list de nes which components are imported into the feature control handler method.

Input Components for Feature Control

Feature Control Type Obligatory Input Components

Instance feature control Instance identi er: %tky

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

Description Expected Provider Example Further information

Implementation

Successful instance feature Implementation returns exactly Existing instance identi ers. result
control. one row for each existing
Duplicate existing instance
instance identi er in result. It
identi ers.
lists the input identi er and the
feature control permission
values.

At least the requested features

are returned, optionally more.

Successful global feature Implementation returns the result

control. feature control permission
values in result.

At least the requested features

are returned, optionally more.

This is custom documentation. For more information, please visit the SAP Help Portal 152
 9/2/2024

Description Expected Provider Example Further information

Implementation

Unsuccessful feature control. For instance feature control, the Non-existing (duplicate) failed
implementation returns one row instance identi ers. (Fail cause
for each failed instance not_found.)
identi er in failed. It lists the
source instance identi ers with
the correct fail cause and initial
%op. (Duplicates may appear.)

The global feature control

implementation does not return
failed.

For every input identi er listed

in failed with fail cause other
than not_found, there is one
related error message returned
in reported.

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.

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 identi ers in case of instance
authorization, or permission values that are valid globally.

For more information, see GET PERMISSIONS.

Input
The following list de nes which components are imported into the authorization control handler method.

Input Components for Authorization Control

Action Type Obligatory Input Components

Instance authorization control Instance identi er: %tky

Requested features

Global authorization control Requested features

Output
The following table summarizes the provider rules for the authorization control implementation.

This is custom documentation. For more information, please visit the SAP Help Portal 153
 9/2/2024
Authorization Control Implementation Specific Rules

Description Expected Provider Example Further information

Implementation

Successful instance Implementation returns exactly Existing instance identi ers. result
authorization control. one row for each existing
Duplicate existing instance
instance identi er in result. It
identi ers.
lists the input identi er and the
authorization control permission
values.

At least the requested features

are returned, optionally more.

Successful global authorization Implementation returns the result

control. authorization control permission
values in result.

At least the requested features

are returned, optionally more.

Unsuccessful authorization For instance authorization Non-existing (duplicate) failed

control. control, the implementation instance identi ers. (Fail cause
returns one row for each failed not_found.)
instance identi er in failed. It
lists the source instance
identi ers with the correct fail
cause and initial %op.
(Duplicates may appear.)

For every input identi er listed

in failed with fail cause other
than not_found, there is one
related error message returned
in reported.

The global authorization control

implementation does not return
failed.

Strict Mode
The strict mode ensures that a RAP business object is lifycycle-stable and upgrade-save.

About Strict Mode

 Note
It is best practice to use strict(2) for all RAP BOs, except for:

Business Con guration (BC) BOs

BOs that consume a BC API or one of the following:

CL_EXCHANGE_RATES

CL_NUMBERRANGE_INTERVALS

CL_UOM_DIM_MAINTENANCE

This is custom documentation. For more information, please visit the SAP Help Portal 154
 9/2/2024
CL_UOM_MAINTENANCE

XCO I18N APIs

XCO Transport APIs

The strict mode represents the best practices regarding modeling and implementing a RAP business object. When a BO is
de ned as strict, this set of best-practice rules is technically enforced with additional syntax checks on speci c 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 de ned, some syntax checks that lead to warnings without strict mode then lead to runtime errors.

The syntax checks in strict mode ensure that:

the syntax in the behavior de nition 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 for an overview.

De nition
You enable the strict mode with the addition strict directly after the implementation type in the behavior de nition. The
strict mode is available for the implementation types managedand unmanaged. For more information about strict, see CDS
BDL - strict (ABAP Keyword Documentation).

Strict Mode - Implementation Requirements

De ning strict or strict(2) for your base or projection behavior de nition results in speci c implementation and modeling
requirements that re ect the RAP best practices. If you de ne 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 De nition

Strict Mode: Abstract Behavior De nition

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).

This is custom documentation. For more information, please visit the SAP Help Portal 155
 9/2/2024

Transactional Behavior De nitions

Strict Mode Implementation: Transactional BDEFs

Requirement Implementation Strict Mode Affects More Information

Type Version

De ne strict for the base

Managed Strict mode Projection
behavior de nition, if you
version 1: Behavior
want to de ne strict in the Unmanaged strict De nition
projection behavior
de nition.

De ne strict(2) for the

Managed Strict mode Base Behavior RAP Extensibility-
base and projection behavior
version 2: Implementation Enablement
de nition, if you want to Unmanaged strict(2)
release the BO for the Projection
Extend (C0) or ABAP Behavior
for Cloud Development Implementation
(C1) release contract.

With strict(2), %ASSOC

Managed Strict mode Base Behavior
is not part of the respective
version 2: Implementation
derived types, when child Unmanaged strict(2)
nodes de ne Projection
authorization:update. Behavior
Implementation

De ne the root entity as lock

Managed Strict mode Base Behavior Concurrency
master and all child nodes as
version 1: De nition Root Control
lock dependent. Unmanaged strict
Base Behavior
De nition Child
Nodes

De ne the root entity as

authorization master Managed Strict mode Base Behavior Authorization
version 1: De nition Root Control
and all child nodes as Unmanaged strict
authorization
Base Behavior
dependent. De nition Child
Nodes

De ne each BO node either ETag De nition

Managed Strict mode Base Behavior
as etag master or etag
version 1: De nition Root
master/etag dependent Unmanaged strict
unless a node is de ned as Base Behavior
abstract. De nition Child
Nodes

This is custom documentation. For more information, please visit the SAP Help Portal 156
 9/2/2024

Requirement Implementation Strict Mode Affects More Information

Type Version

In strict mode, derived

Managed Strict mode Base Behavior
types and ready-results are
version 1: Implementation
only compatible with Unmanaged strict
themselves in the Projection
implementation. Behavior
Implementation
 Note
Without strict, derived
types and ready-results
were implicitly
compatible with
structurally identical data
types in some
implementation
scenarios. Now, the
compatibility must be
de ned explicitly in the
implementation with
CORRESPONDING.

Access the derived types for Methods in the

Managed Strict mode Derived Data Types
the following operation types RAP behavior
version 1:
only from provider side: Unmanaged pool:
strict
Authorizations FOR FEATURES

Features FOR INSTANCE

AUTHORIZATION
Determinations
Determinations
Validations
Validations
Additional save

Build a projection behavior

Managed Strict mode Projection
de nition on a BDEF with
version 1: Behavior
implementation type Unmanaged strict De nition Nodes
managed or unmanaged.

 Note
Projection BDEFs can't be
based on abstract base
behavior de nitions.

Create child instances only

Managed Strict mode Base Behavior Create by
with explicitly stated
Creates-By- version 1: De nition Child Association
Unmanaged strict Nodes Operation Runtime
Association. A direct
CREATE on a subnode isn't
allowed in most cases.

Implement the
Managed Strict mode Base Behavior ADJUST_NUMBERS
ADJUST_NUMBERS method
version 1: De nition Nodes
in the behavior pool, if you've Unmanaged strict
de ned late numbering.

This is custom documentation. For more information, please visit the SAP Help Portal 157
 9/2/2024

Requirement Implementation Strict Mode Affects More Information

Type Version

Explicitly enable all

Managed Strict mode Base Behavior
expected behavior in the
version 1: De nition Nodes
behavior de nition. Unmanaged strict
 Note Projection
Behavior
Strict mode enforces
De nition
explicit de nition of all
expected behavior and
any implicit enablement
is suppressed, like, for
example, implicit read-
enablement in toParent
compositions or implicit
enablement of CUD
operations for a managed
RAP business object.

Use only derived types from

Managed Strict mode Base Behavior
explicitly enabled operations
version 1: Implementation
in your implementation. Unmanaged strict
Projection
Behavior
Implementation

Use the newest syntax in For EML:

Managed Strict mode Base Behavior
your behavior de nition and
version 1: De nition and Examples for
implementation. Unmanaged strict Implementation Accessing Business
 Note Objects with EML
Projection
Strict mode result in
Behavior
syntax errors if
De nition and
deprecated syntax is
Implementation
used in the behavior
de nition or
implementation.

Only use EML invocations for

Managed Strict mode Base Behavior
explicitly enabled standard
version 1: De nition and
operations. Unmanaged strict Implementation
 Note
Projection
You can only implement
Behavior
an EML delete for a RAP
De nition and
BO, if the DELETE is
Implementation
enabled in the
corresponding behavior
de nition.

Ensure that feature control

Managed Strict mode Base Behavior
isn't used in combination
version 1: De nition
with readonly. Unmanaged strict
Projection
Behavior
De nition

This is custom documentation. For more information, please visit the SAP Help Portal 158
 9/2/2024

Requirement Implementation Strict Mode Affects More Information

Type Version

Explicitly de ne all draft

Managed Strict mode Base Behavior Draft Actions
actions if your BO is draft-
(only if draft- version 1: De nition
enabled:
enabled) strict
draft action resume;
Unmanaged
draft action Edit; (only if draft-
enabled)
draft action Activate;

draft action Discard;

draft determine
action Prepare { }

Explicitly display all draft

Managed Strict mode Projection Draft Actions
actions in your projection
(only if draft- version 1: Behavior
BDEF, if the projection is
enabled) strict De nition
de ned as strict:
Unmanaged
use action Resume;
(only if draft-
use action Edit; enabled)

use action Activate;

use action Discard;

use action Prepare;

De ne the draft determine

Managed Strict mode Base Behavior
action Prepare without
(only if draft- version 1: De nition
authorization control.
enabled) strict

Unmanaged
(only if draft-
enabled)

De ne functions as FOR
Managed Strict mode Base Behavior
FUNCTION in the method
version 1: Implementation
de nition of your behavior Unmanaged strict
implementation. Projection
Behavior
 Note Implementation
The de nition FOR
ACTION for a function
results in a syntax error.

Rename actions in the BDEF

Managed Strict mode Projection
projection with the addition
version 1: Behavior
as *ActionName*, if Unmanaged strict De nition
another action has the same
identi er.

Use view entities as data

Managed Strict mode Projection
sources for a RAP business
version 1: Behavior
objects. CDS views aren't Unmanaged strict De nition
supported in strictmode.

This is custom documentation. For more information, please visit the SAP Help Portal 159
 9/2/2024

Requirement Implementation Strict Mode Affects More Information

Type Version

Use late numbering

Managed Strict mode Base Behavior
instead of late
version 1: De nition and
numbering in place. Unmanaged strict Implementation

Don't use the MAPPED

Unmanaged Strict mode Base/Projection
parameter in your
version 1: Behavior
READ/LOCK implementation
strict Implementation
and don't use IMAGE in your
READ implementation .

De ne EML calls of static

Managed Strict mode Base Behavior
actions or functions explicitly
version 1: Implementation
as in local mode if Unmanaged strict
necessary. Projection
Behavior
Implementation

Ensure that toParent/toChild

Managed Strict mode Base/Projection
associations aren't de ned
version 1: Behavior
as internal and are Unmanaged strict De nition
explicitly de ned in the
behavior de nition.

Only use CDS abstract

Managed Strict mode Base/Projection
entities or classic DDIC
version 1: Behavior
types in your action or Unmanaged strict Implementation
function implementation.

Ensure that your action or

Managed Strict mode Base/Projection
function implementation has
version 1: Behavior
either $self, entity, CDS Unmanaged strict Implementation
abstract entities, or a DDIC
type as returning parameter.

De ne an
implementation in Managed Strict mode Base Behavior
class version 1: De nition
Unmanaged strict
*ImplementationClass*
Projection
unique for each BO node Behavior
where an implementation is De nition
required.

Ensure that your composition

Managed Strict mode Base Behavior
hierarchy is modeled
version 1: De nition
consistently and without any Unmanaged strict
gaps: That means that parent Projection
entities must always be Behavior
de ned in the behavior De nition
de nition if their child entity
is de ned. However, you can
de ne a parent entity without
its dependent entities.

This is custom documentation. For more information, please visit the SAP Help Portal 160
 9/2/2024

Requirement Implementation Strict Mode Affects More Information

Type Version

Ensure that you de ne the

Managed Strict mode Base Behavior
associations in the behavior
version 1: De nition
de nition if the respective Unmanaged strict
entity is de ned in the Projection
behavior de nition: Behavior
De nition
 Example
In a composition with a
travel entity as root
node and a booking
entity as child entity the
following applies:

If booking is de ned with

Define behavior for
*booking_entity*, the
travel entity must contain
association _Booking
{...}.

If you've de ned late

Managed Strict mode Base Behavior
numbering for a parent
version 1: De nition
entity, it recommended use Unmanaged strict
late numbering also for its
child entit'ses. However, the
%PID isn't inherited
implicitly by child entities in
strict mode.

Abstract Behavior De nition

Strict Mode Implementation: Abstract BDEFs

Requirement Implementation Type Affects More Information

Use abstract CDS entities as (Abstract) Base

Abstract
data sources , if you want to Behavior De nition
de ne an abstract behavior
de nition.

This is custom documentation. For more information, please visit the SAP Help Portal 161
 9/2/2024

Requirement Implementation Type Affects More Information

De ne an abstract behavior (Abstract) Base

Abstract
de nition without any Behavior De nition
transactional behavior like:

Feature Control

Standard or Non-
Standard Operations

Locks

Etag handling

Foreign Entity

...

Only de ne behavior de nition

elements such as associations
and compositions , or mappings
for an abstract BDEF.

Related Information
Strict Mode

Business Object Interface

A business object interface is required if you want to release your business object for e.g. usage/extensibility in other software
components via stability contracts. Business object interfaces are not required if no cross component access is intended. For
more information on stability contracts for business object interfaces, see What are RAP Business Object Interfaces?.

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 speci c BDEF type without a runtime handler and thus without implementation class and behavior pool,
that speci es 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:

This is custom documentation. For more information, please visit the SAP Help Portal 162
 9/2/2024

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 - DEFINE VIEW ENTITY AS PROJECTION ON, Transactional Interface
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 a projection layer that technically decouples requirements for stable consumption
from the behavior and data model of the underlying RAP base BO. The interface layer distinctly speci es a subset of elements or
behaviors from a RAP base BO like elds or actions. The interface ensures lifecycle-stable consumption for RAP BO consumers :
To ensure lifecycle-stability, development objects are released for speci c API states, e.g. for Use System-Internally
(C1). Released development objects must abide by speci c 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 speci ed for consumption in the interface layer. Other
elements that are only contained in the RAP base BO remain unaffected and can be changed without in uencing 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 de ne or rede ne static feature control on the interface layer for elements from the RAP base BO. For
example, you can de ne a elds as readonly in a BO interface when the same eld 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.

This is custom documentation. For more information, please visit the SAP Help Portal 163
 9/2/2024
An overview of the consumption possibilites of business objects and their interfaces can be found in chapter Consume.

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.

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.

Annotation propagation
The interface projection layer is used to decouple requirements for the stable consumption of a business object from its
underlying base data model and behavior. With respect to annotations, this means that annotation changes in the base data
model must have no impact on the data model in the interface projection layer and above. Hence it is best practice to use the
annotation @Metadata.ignorePropagatedAnnotations: true in the header section of the interface projection view.
This annotation prevents annotations from the underlying base data model from being propagated further through the CDS
view stack, thus possibly impacting projections that are built on top of the RAP BO interface. The annotations that are supposed
to be effective in superjacent projections should be de ned explicitly in the interface projection view.

Business Service

De nition
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 de ned by exposing its data model together with the associated behavior. It consists of a service de nition
and a service binding.

Business Services in the ABAP RESTful Application Programming Model

As illustrated in the gure below, the programming model distinguishes between the data model and behavior and the service
that is de ned by exposing these data models together with the behavior. The data model and the behavior layer contain
domain-speci c semantic entities like business objects, list views, and analytical queries, and, in addition, related functionality
such as value help, feature control, and reuse objects.

This is custom documentation. For more information, please visit the SAP Help Portal 164
 9/2/2024

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-speci c 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 De nition 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-speci c way. The service de nition is a
projection of the data model and the related behavior to be exposed, whereas the service binding de nes a speci c
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 de nitions to be integrated into various communication protocols without the hassle of re-
implementation.

Example

Let us assume that a business object SalesOrder is de ned and implemented in the data model and the behavior layer with the
related value help and authorization management. The service de nition 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 de nition and the related projection views that project the service relevant parts of the data model
implemented in CDS and the behavior de nition where it projects the operations that should be exposed. For example,
the SalesOrder BO might offer the operations: create, update, delete, and 10 different application-speci c actions.
However, for a concrete role-speci c 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 de ned in the service de nition to bind the package to a
service type (Web API, UI service, INA service) and a protocol type (OData V2, OData V4).

Related Information
This is custom documentation. For more information, please visit the SAP Help Portal 165
 9/2/2024
Service De nition
Service Binding
Working with Business Services

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 speci c business service. The projection enables exible service consumption as well as role-
based service designs.

Introduction
A service projection layer is required for a exible 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 rst layer in the
development ow of the ABAP RESTful Programming Model that is service speci c. When projecting the basic BO, you de ne
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-speci c ne-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 exibility 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 speci c subset of the general business object and thus, the
service remains stable under modi cation of the underlying business object. In addition, aliasing in the projection views allows
context-speci c adaptions of the business object for a service.

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-speci c differences can then be implemented in the respective projection layers. For example, UI speci cations are
de ned only in the BO projection that is exposed for the UI service. Furthermore, with projections, you cannot only de ne 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-speci c 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 speci c 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.

This is custom documentation. For more information, please visit the SAP Help Portal 166
 9/2/2024

Business Partner Projections

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:

This is custom documentation. For more information, please visit the SAP Help Portal 167
 9/2/2024
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 de ned as root projection view. The compositions are redirected to the new target projection
entity.

Travel BO Projection

For a detailed description on CDS projection views and their syntax, see CDS Projection View.

Projection Behavior De nition

The projection of the behavior is done in a behavior de nition of type projection, which is declared in the header of
the behavior de nition. According to this type, only syntactical elements for projections can be used.

For more information on projection behavior de nitions and their syntax, see Projection Behavior De nition.

CDS Projection View

Projection views provide means within the speci c service to de ne service-speci c projections including denormalization of the
underlying data model. Fine-tuning, which does not belong to the general data model layer is de ned in projection views. For
example, UI annotations, value helps, calculations or defaulting.

CDS projection views are de ned in data de nition development objects. The wizard for data de nitions provides a template for
projection views.

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 de ned 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 elds from new associated entity in the projection view. New
associated entities cannot be accessed transactionally. Associations, including compositions, that are de ned in the projected

This is custom documentation. For more information, please visit the SAP Help Portal 168
 9/2/2024
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 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 De ne View Entity as Projection (ABAP Keyword Documentation).

Annotation Propagation to Projection Views

Annotations that are de ned 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
rede ne 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,
...}

This is custom documentation. For more information, please visit the SAP Help Portal 169
 9/2/2024

De ning UI Speci cs in the Projection Views

From a design time point of view, the projection layer is the rst service-speci c layer. If the resulting OData service is a UI
service, all UI speci cations or other service-speci c annotations must be de ned in the CDS projection views via CDS
annotations. The following UI speci cs are relevant on the projection BO layer:

UI annotations de ning 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

Projection Behavior De nition

A projection behavior de nition provides means to de ne service-speci c behavior for a BO projection.

The behavior de nition with type projection is created equally to other types of behavior de nitions. When creating a
behavior de nition based on a CDS projection view, the syntax template directly uses the projection type.

In a behavior de nition, only behavior characteristics and operations that are de ned in the underlying behavior de nition can
be de ned for the BO projection. The syntax for this is use <Element>.

For details about the syntax of a projection behavior de nition, see CDS BDL - implementation type (ABAP Keyword
Documentation).

Explanation

The keyword use exposes the following characteristics or operations for the service-speci c projection. In the projection, only
elements can be used that were de ned in the underlying behavior de nition. These elements can be

ETag

standard operations

actions

functions

create_by_association

Every operation that you want to expose to your service must be listed in the projection behavior de nition. New aliases can be
assigned for actions and functions. Projection behavior de nitions do not have a behavior implementation. The complete
behavior is realized by mapping it to the underlying behavior.

This is custom documentation. For more information, please visit the SAP Help Portal 170
 9/2/2024
The de nitions 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 eld control is de ned in the underlying behavior de nition, you can add this de nition in the projection behavior
de nition. If it is already de ned in the underlying behavior de nition, you cannot de ne the opposite in the projection layer. If
you do, you will get an error during runtime. New dynamic eld control cannot be de ned in the projection behavior de nition, as
there is no option to implement the feature.

Related Information
Providing Behavior for Projections

Service De nition

De nition
A business service de nition (short form: service de nition) describes which CDS entities of a data model are to be exposed so
that a speci c business service, for example, Sales Order handling, can be enabled. It is an ABAP Repository object that
describes the consumer-speci c 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 de nition represents the service model that is generically derived from the underlying CDS-based data model.

You use a service de nition to de ne which data is to be exposed as a business service using one or more service bindings. A
service de nition 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 use of a service de nition only in connection with at least one service
binding.

 Note
You cannot expose an OData service that includes abstract entities for Web APIs or UI services. You can expose abstract
entities in a service de nition, but only if they are created using OData client proxy tools (service consumption use case).
The publishing of a service via a service binding causes a dump error.

For details about the syntax to de ne a service, see CDS SDL - DEFINE SERVICE (ABAP Keyword Documentation)

Explanation

The source code of the actual service de nition 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 speci ed text value should consist of a meaningful short text that describes the service in the original
language of the source code.

This is custom documentation. For more information, please visit the SAP Help Portal 171
 9/2/2024
Depending on the needs of your scenario, further optional annotations @<Annotation_1> ... @<Annotation_n> can be
speci ed. If you expose a complete business object structure with more than one CDS entity for a service you can use the
annotation @ObjectModel.leadingEntity.name: to de ne the root entity of the business service and hence the primary
entrance point to the business service. The annotation provokes that the entity is marked in the entity tree in the service
binding editor and appears as the rst entity in the list.

The service de nition is initiated with the DEFINE SERVICE keyword followed by the name for the service de nition.

The source code of a service de nition 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 de nes 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 identi ers in the service de nition and thus decoupling the service semantics from the concrete technical
names resulting from the data de nition.

Similar to the CDS syntax rules, each statement is completed by a semicolon.

Example

/DMO/Travel, de nes 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 de nition /DMO/TRAVEL. The travel management
service to be de ned in this way includes all dependencies that come from the root entity /DMO/I_TRAVEL.

@EndUserText.label: 'Service for managing travels'

@ObjectModel.leadingEntity.name: '/DMO/I_TRAVEL'
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;
}

This is custom documentation. For more information, please visit the SAP Help Portal 172
 9/2/2024

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

Related Information
Service Binding
Creating Service De nitions

Service De nition Extension

A RAP Service Definition Extension extends an existing service de nition 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.

Service Binding
De nition
The business service binding (short form: service binding) is an ABAP Repository object used to bind a service de nition 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 gure below, a service binding relies directly on a service de nition that is derived from the underlying CDS-
based data model. Based on an individual service de nition, a plurality of service bindings can be created. The separation
between the service de nition 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:

Service Name

De nes a unique system-wide name for the service and is identical to the name of the service binding.

 Tip
We recommend using the pre x API_ for Web API services and the pre x UI_ for UI services.

This is custom documentation. For more information, please visit the SAP Help Portal 173
 9/2/2024

Binding Type

The binding type speci es the service type and the speci c 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 identi ed using
Uniform Resource Identi ers (URIs) and de ned 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, le 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:

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.

This is custom documentation. For more information, please visit the SAP Help Portal 174
 9/2/2024

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 de nition to the existing service binding. By means of this further
service de nition, functional changes or extensions (compared to the previous version) are exposed. And, vice versa, the version
number can be decreased by removing a service de nition 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
speci es the virtual directory of the service by following the syntax: /sap/opu/odata/<service_binding_name>

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.

OData Exposure Comparison

Business services bound to the OData protocol differ depending on the type and the version chosen respectively in the service
binding. The following table outlines differences between these types and versions:

Feature WebAPI V2 WebAPI V4 UI Service V2 UI Service V4

UI annotations No UI speci c No UI speci c UI speci c information UI speci c information

information contained in information contained in contained in metadata contained in metadata
metadata metadata

Value help Not available Available

Side Effetcs Not available Available

Feature control Not exposed as part of service Exposed as part of service

PDF Export Not available Available via entity sets

Release for contracts C2 possible in ADT Service Binding context C1 possible in ADT Service Binding context
menu API state . See also: Releasing menu API state . See also: Releasing
Development Objects Development Objects

Fiori Elements preview Not available Available in service binding

Code lists for units of Not available Contained in service Contained in entity sets Contained in service
measure / currencies group SAP__Currency and group
SAP__UnitOfMeasure

This is custom documentation. For more information, please visit the SAP Help Portal 175
 9/2/2024

Feature WebAPI V2 WebAPI V4 UI Service V2 UI Service V4

ISO conversion of Available Not available

currency code format

ISO conversion of unit of Conversion disabled for ISO / SAP Unit validation Conversion disabled for ISO / SAP Unit validation
measure SAP Unit SAP Unit

Conversion Exit CUNIT Removed for the ISO unit of measure property Available

More information as well as examples for the business service exposure of business objects is available in the section Develop.

 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 quali cation 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.

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 De nition

RAP Reuse Data Elements

You can use speci c data elements in all RAP application for typing administrative elds.

The following list of reuse data elements can be used for the administrative elds in RAP BOs of all implementation types. These
data elements are available for reuse in all systems.

Data Element De nition

ABP_CREATION_USER Identi er 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 Identi er 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 compositional
subtree was last changed.

This is custom documentation. For more information, please visit the SAP Help Portal 176
 9/2/2024

Data Element De nition

ABP_LASTCHANGE_TIME Time at which the data of the local instance or its compositional
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 Identi er of the user who changed the local instance itself (without
considering its compositional subtree) last time.

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 elds are relevant in RAP application to log data access and modi cation. 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.

For more information about the total ETag, see Total ETag.

Managed Business Objects

In managed business objects, the relevant administrative elds are updated automatically by the managed BO provider if the
elds are annotated with the corresponding annotation in CDS. See Semantics Annotations.

Unmanaged Business Objects

In unmanaged business object, updating the administrative elds on data modi cation 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 elds for the creation user and the
creation time are lled correctly.

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

This is custom documentation. For more information, please visit the SAP Help Portal 177
 9/2/2024
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
signi cantly 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 de ning groups for unmanaged business objects, see CDS BDL - implementation grouping
(ABAP Keyword Documentation)

Syntax: De ning Groups for Managed Business Objects

Groups can be de ned within a behavior de nition for a business object of type managed by using the following syntax:

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

define behavior for Entity [alias AliasedName]
persistent table DB_TABLE
...
{
[create;]
[update;]
[delete;]
[read;]
[association AssociationName [abbreviation AbbreviationName] {[create;] } ]

group groupName_1 implementation in class ABAP_CLASS_1 unique

{
// Implementation-relevant content of the entity
}

group groupName_2 implementation in class ABAP_CLASS_2 unique

{
// Implementation-relevant content of the entity
}

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

group ...

This is custom documentation. For more information, please visit the SAP Help Portal 178
 9/2/2024

Explanatory Notes

(1) The group name is de ned locally within the entity’s behavior de nition and must not con ict 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
de nition 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 de nition, 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 speci ed either inside or outside groups.

(4) Information on mapping (which is never relevant to implementation) must always be speci ed outside of groups.

(5) Implicit standard operations (de ned automatically and don't have to be explicitly speci ed) must be explicitly speci ed
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 de ned as lock master.

Examples

Listing: Groups in the behavior de nition 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);
This is custom documentation. For more information, please visit the SAP Help Portal 179
 9/2/2024
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;
}

mapping for /dmo/booking

{
...
}

Listing: Groups in the behavior de nition 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;

This is custom documentation. For more information, please visit the SAP Help Portal 180
 9/2/2024
association _Booking { create; }

group travel_fc implementation in class /dmo/bp_travel_fc unique

{
field ( read only ) TravelID;
field ( mandatory ) AgencyID, CustomerID, BeginDate, EndDate;
field(features:instance) overall_status;
}

group travel_cba implementation in class /dmo/bp_travel_cba unique

{
association _Booking { create; }
}

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;
field ( mandatory ) CustomerID, AirlineID, ConnectionID, FlightDate;
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

This is custom documentation. For more information, please visit the SAP Help Portal 181
 9/2/2024
(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. Speci cally, 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
de ned by specifying the group name:

class lhc_travel_fc definition inheriting from cl_abap_behavior_handler.

private section.
methods get_features for features
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.
This is custom documentation. For more information, please visit the SAP Help Portal 182
 9/2/2024
...
endmethod.
method read_bookings.
...
endmethod.
endclass.

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. You can
simply remove the client eld in the template for database tables.

The following code block shows the travel database table without a client eld. 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 {
key travel_id : /dmo/travel_id not null;
agency_id : /dmo/agency_id;
customer_id : /dmo/customer_id;
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;
@AbapCatalog.anonymizedWhenDelivered : true
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 elds 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

This is custom documentation. For more information, please visit the SAP Help Portal 183
 9/2/2024
automatically created draft tables are created client-independently. For more information about how to generate draft
database tables, refer to Draft Database Table.

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 de ned 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 eld in database tables in uences the runtime of business objects during lock. While locks are set on entity instances
only for one speci c 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 elds from other database
tables to your CDS view, the managed BO runtime locks the instances speci c to the client. This means only the elds from
the client-dependent database tables are locked. If you also want to lock the client-independent elds, 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-
speci c lock. If you want to lock client-independently, you have to use an unmanaged lock.

Related Information
Lock De nition
Integrating Unmanaged Save in Managed Business Objects

Determination and Validation Modelling

This chapter outlines the best practices for modelling determinations and validations.

For basic information on determinations and validations, see Determinations and Validations.

Trigger conditions
Determinations and validations are commonly used to rst read instance data and then to perform the modi cation/validation
based on the read data. In order to ensure, that the determinations and validations can react on changes in elds that are read
repectively, these elds should be used as their trigger conditions.

Kind independent behavior

The behavior of determinations and validations must coincide for draft and active instances. This includes the state messages
reported by determinations and validations.

In order to implement determinations and validations kind independently, use the derived type component %tky. This
component includes the draft indicator %is_draft which is set depending on the context by the framework. Before you set the
draft indicator %is_draft manually, ensure that this does not lead to an unwanted difference in behavior between draft and
active instances.

This is custom documentation. For more information, please visit the SAP Help Portal 184
 9/2/2024
For more information on the draft indicator, see Draft.

Runtime independent behavior

The behavior of determination and validation executions must be identical, irrespective from the runtime phase they are
executed in. A validation, for instance, that is part of a determine action, must provide the same reported result in the
interaction phase and in the save sequence.

Determination usage
Application logic intended to notify about saved changes must be implemented in a provider implementation that is called after
the point of no return of the save sequence, e.g. in the additional save implementation. It must not be implemented in a
determination on save.

Failed entries from determinations

Determinations don't have a failed response. In determinations where elds need to be checked before their calculation can be
performed, the application needs to store negative results of these checks. Validations then need to consider these negative
results when returning their failed response during CHECK_BEFORE_SAVE. In cases where determinations are executed
multiple times due to retriggered conditions, the check result can change during subsequent determination executions. This
needs to be considered by the determination logic that maintains the failed entries for validations.

RAP BO Runtime
The runtime of a RAP business object (BO) consists of two main parts: The interaction phase and the save sequence.

Interaction Phase
The interaction phase is the rst part of the BO runtime. In this phase, a consumer can call 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.

Save Sequence
When all changes are done, the data must be persisted. This happens in the second part of the BO runtime, the save sequence.

This image is interactive. Hover over each area for a description. Click highlighted areas for more information.

This is custom documentation. For more information, please visit the SAP Help Portal 185
 9/2/2024

Please note that image maps are not interactive in PDF output.

Implementation
The implementation of the interaction phase and the save sequence is carried out in a special type of class pool, the behavior
pool, which refers to the behavior de nition. The interaction phase is represented by the local handler class and the save
sequence by the local saver class. For more information on the implementation of business object functionality, see also :
Business Object Provider API.

Operations Runtime
The RAP Transactional Model and the SAP LUW
This topic describes how RAP supports the transactional model of a controlled 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 on the
database to another.
Save Sequence Runtime
The save sequence is part of the business object runtime and is called after at least one successful modi cation was
performed during the interaction phase.

Operations Runtime
This section describes the operations that are available for RAP business objects and their functionality.

Standard Operations Runtime

Nonstandard Operations Runtime
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-speci c behavior.

Standard Operations Runtime

This is custom documentation. For more information, please visit the SAP Help Portal 186
 9/2/2024
Standard operations in RAP business objects are operations that cover the standard functionality for creating, updating,
deleting and locking RAP BO instances.

Create Operation Runtime

In RAP, the create operation is a standard modifying operation that creates new instances of a business object entity.
Update Operation Runtime
In RAP, the update operation is a standard modifying operation that changes instances of a business object entity.
Delete Operation Runtime
In RAP, the delete operation is a standard modifying operation that deletes instances of a business object entity.
Create by Association Operation Runtime
In RAP, the create by association operation is a modify operation that creates new instances of an associated
entity.

Create Operation Runtime

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.

Instantiation of Handler Classes in the ABAP Behavior Pool

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.

This image is interactive. Hover over each area for a description.

This is custom documentation. For more information, please visit the SAP Help Portal 187
 9/2/2024

This is custom documentation. For more information, please visit the SAP Help Portal 188
 9/2/2024

Please note that image maps are not interactive in PDF output.

Parent topic: Standard Operations Runtime

Related Information
Update Operation Runtime
Delete Operation Runtime
Create by Association Operation Runtime

Update Operation Runtime

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 diagram, see Save Sequence Runtime.

Instantiation of Handler Classes in the ABAP Behavior Pool

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.

This image is interactive. Hover over each area for a description.

This is custom documentation. For more information, please visit the SAP Help Portal 189
 9/2/2024

This is custom documentation. For more information, please visit the SAP Help Portal 190
 9/2/2024

Please note that image maps are not interactive in PDF output.

Parent topic: Standard Operations Runtime

This is custom documentation. For more information, please visit the SAP Help Portal 191
 9/2/2024

Related Information
Create Operation Runtime
Delete Operation Runtime
Create by Association Operation Runtime

Delete Operation Runtime

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.

Instantiation of Handler Classes in the ABAP Behavior Pool

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.

This image is interactive. Hover over each area for a description.

This is custom documentation. For more information, please visit the SAP Help Portal 192
 9/2/2024

This is custom documentation. For more information, please visit the SAP Help Portal 193
 9/2/2024

Please note that image maps are not interactive in PDF output.

Parent topic: Standard Operations Runtime

Related Information
Create Operation Runtime
Update Operation Runtime
Create by Association Operation Runtime

Create by Association Operation Runtime

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.

Instantiation of Handler Classes in the ABAP Behavior Pool

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

This is custom documentation. For more information, please visit the SAP Help Portal 194
 9/2/2024
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.

This image is interactive. Hover over each area for a description.

This is custom documentation. For more information, please visit the SAP Help Portal 195
 9/2/2024

This is custom documentation. For more information, please visit the SAP Help Portal 196
 9/2/2024

Please note that image maps are not interactive in PDF output.

Parent topic: Standard Operations Runtime

Related Information
Create Operation Runtime
Update Operation Runtime
Delete Operation Runtime

Nonstandard Operations Runtime

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-speci c behavior.

Action Runtime
In RAP, an action is a non-standard modify operation.

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 diagram, see Save Sequence
Runtime.

Instantiation of Handler Classes in the ABAP Behavior Pool

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.

This image is interactive. Hover over each area for a description.

This is custom documentation. For more information, please visit the SAP Help Portal 197
 9/2/2024

This is custom documentation. For more information, please visit the SAP Help Portal 198
 9/2/2024

Please note that image maps are not interactive in PDF output.

Parent topic: Nonstandard Operations Runtime

Related Information
Actions
Action De nition
Action Implementation

The RAP Transactional Model and the SAP LUW

This topic describes how RAP supports the transactional model of a controlled 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 on the database to another.

This is custom documentation. For more information, please visit the SAP Help Portal 199
 9/2/2024
The ABAP RESTful Application Programming Model (RAP) does not introduce its own LUW concept, but uses the rules and
concepts of the SAP LUW. RAP strictly adheres to the rules of a SAP LUW by inherently checking transactional contexts and
only allowing developers to use or call implementations that match the transactional contexts. In that sense, the controlled
SAP LUW is inherently built into RAP. For more information about transactional consistency during the SAP LUW, see Controlled
SAP LUW.

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 by
default. This is ensured by adhering to the framework RAP provides, which entails checks for all different use cases, exactly like
the controlled SAP LUW checks the contexts. The RAP-inherent checks ensure 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 nal 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.

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 ROLLBACK ENTITIES and thus terminate the LUW with RAP
procedures.

 Note
The following violations against the SAP LUW principles will always lead to a runtime error in a RAP context:

Explicit use of COMMIT WORK or ROLLBACK WORK. The transaction handling and database commit is exclusively
handled by RAP.

Calling the update in background tasks (bgPF) in the interaction phase or the early save phase.

Some other operations only lead to runtime errors, if the RAP behavior de nition is implemented in ABAP for Cloud
Development and the strict(2)-mode is applied:

Invoking authorization checks during the save sequence

Modifying database operation in the interaction phase or early-save phase

Raising business events in the interaction phase or early-save phase

(Implicit or explicit) database commits for the primary database connection in the late-save phase.

For more information, see General RAP BO Implementation Contract.

Every BO entity instance that is involved in one LUW must be locked to avoid con icting 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).

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 is custom documentation. For more information, please visit the SAP Help Portal 200