The perfect complement to training courses

from Brandeis Consulting

The ABAP RESTful Application Programming Model (RAP), together with Fiori Elements, enables developers to efficiently create cloud-enabled, transactional business applications.

Services are created with RAP. Fiori Elements displays the data from the services on standard floor plans.

This cheat sheet provides an initial overview of the syntax, examples, and descriptions of the basics of RAP and backend annotations for Fiori Elements, so you can quickly familiarize yourself with the most important concepts and practical aspects of using SAP RAP for your development projects. The naming conventions in the illustrations refer to the current standard at SAP. Customers must prefix them with the Z or Y namespace accordingly.

This cheat sheet consistently uses CDS View Entities instead of CDS Views, which have been obsolete since 7.57.

Read-only applications

In the first step, we will only look at Fiori Elements applications that we create based on CDS views, without CRUD. In the simplest case, they consist of four levels:

• Database table
• CDS view with annotations
• Service definition
• Service binding

CDS Views for Read-Only Scenarios

In order for the interfaces to be displayed with Fiori Elements, a few annotations must be present in the CDS views. The most important ones for the respective areas are described below:

• List Report
• Object Page
• Header Definition
• Filter Bar

Associations

The relationships between objects are mapped by associations. Lists or tables of associated objects can thus be displayed on the Object Page.

Service definitions specify which business objects are to be published in the service. Alias names can be used to give the technical names attractive names for the service.

@EndUserText.label: 'Task Management'
DEFINE SERVICE zbc_tm {
EXPOSE zc_users AS Users;
EXPOSE zc_tasks AS Tasks;
}

Service Bindings assign a protocol to the previously defined services. They can be published locally directly. In V4, this is done using the transaction /IWFND/V4_ADMIN. The following binding types can be selected:

• OData 2.0 (V2) or 4.0 (V4) - Version V2 or V4
• UI - Transfers the UI annotations
• Web API - Without UI annotations
• InA - UI - For analytical data models, e.g., for live data access.
• SQL - Web API - Access with Open SQL.

V2 or V4

SAP recommends using V4. This fully supports Fiori Elements with Draft only. V2 is not deprecated or obsolete, but it transfers more data volume.

Annotations for Fiori Elements

Annotations are required to ensure that a service based on a CDS view can be displayed correctly in Fiori Elements. These control the properties of the interface and, in some cases, its functions.

The following examples provide only a brief overview of frequently used interface annotations.

Header Annotations

At the view level, i.e., before the actual definition of the view. These annotations refer to the entire view and are not propagated upwards. The standard annotations from the templates are not shown here.

@UI: {
headerInfo: {
typeName: 'Task',
typeNamePlural: 'Tasks',
typeImageUrl: 'sap-icon: //activity-items',
title: {
type: #STANDARD , 
value: 'Summary'
}
}
}
...
define root view entity zbc_c_tasks 
as select from zbc_tasks {
...

List Report Annotations

The annotation @UI.lineItem defines that the field is displayed as a column in a table. Usually, at least the position is specified.

@UI.lineItem: [ { position: 30 , 
label: 'Assignee' ,
importance: #HIGH
} ] 
Assignee,

@ObjectModel.text.element establishes the connection between the identifier element and its descriptive language-independent texts.

@ObjectModel.text.element: [ 'Name' ]
key user_id as UserId,

Filtering and searching

Filters

The filter fields of a list report can be set by the user using the Customize filter button. If the annotation @UI.selectionField is used, these can be preset. Here, too, at least the position must be specified.

@UI.selectionField: [ { position: 10, 
label: 'Task status',
exclude: true } ]
Status,

Search

For a fuzzy search across multiple fields, the @Search annotation can be used at the view level.

@Search.searchable: true 

For each field that is to be searchable, the following annotations are added:

@Search:{ defaultSearchElement: true,
fuzzinessThreshold: 0.7 } 

The fuzzinessThreshold (interval 0 to 1) specifies how fuzzy the search should be. SAP recommends a starting value of 0.7.

Object Page Annotations

An instance of an object is displayed on the Object Page. The header area is designed using the header annotations. The object data is displayed in so-called facets:

Facets

The areas to be displayed on the Object Page must be defined with the annotation @UI.facet. Although the definition refers to all columns, they are not defined in the view annotations but at field level. The reason for this is that otherwise they will not be propagated. Normally, facets are defined before the first field.

Facet for the identification area

Fields in this area should uniquely identify the object, together with the information from the header.

@UI.facet: [ {
id: 'idIdentification',
type: #IDENTIFICATION_REFERENCE,
label: 'Task',
position: 10
} ]
TaskKey;

Fields that are to be displayed in this facet require the annotation @UI.identification:

@UI.identification:[ { position: 20, 
label: 'Processor' } ]}
Firstname

Facet for field groups

Field group facets display a group of fields with their labels.

@UI.facet: [ {
id: 'idHeader',
label: 'Task',
type: #FIELDGROUP_REFERENCE,
targetQualifier: 'AddressQ'
} ]
...

Fields to be displayed in this group require the annotation @UI.fieldGroup:

@UI.fieldGroup: [ { qualifier: 'AddressQ',
position: 10,
label: 'Name'
} ]
Firstname;

Facet for tables

This facet is used to display associated objects as a table. The name of the association must be specified in targetElement. In the associated CDS entity, the annotation @UI.lineItem must be specified for the fields to be displayed.

@UI.facet: [ {
id: 'idItem',
label: 'Ref',
type: #LINEITEM_REFERENCE,
targetElement: '_Items'
} ]
...

General field annotations

The following annotations can be used in different places. For example, in @UI.lineItem, @UI.fieldGroup, @UI.identification:

• hidden - The field is not displayed and cannot be added even with personalization
• position - Specifies the order of the fields in the facet/table
• label - Field label
• qualifier - Reference to the targetQualifier of the facet. This allows different representations to be achieved.

Search help

Search help allows values to be selected. To do this, a CDS view other than entity.name is specified and the corresponding field to be transferred is specified as entity.element. Additional bindings for filtering can be defined with additionalBinding.

@Consumption.valueHelpDefinition: [ {
entity: { name: 'ZI_StatusVH', 
element: 'Status' }
useForValidation: true,
additionalBinding: [ { localElement: 'Project', 
element: 'Project' } ]
} ]
Status;

Texts for keys

To ensure that the corresponding texts are also displayed on the interface for key values, you can associate a text view with appropriate annotations:

define view entity zac_gender_text
as select from DDCDS_CUSTOMER_DOMAIN_VALUE_T( p_domain_name : 'ZBC_GENDER' ){
@Semantics.language: true
key language,
key value_low as gender,
@Semantics.text: true
text
}

The field of the view being used must have the annotation @ObjectModel.text.association: '<TextAssociation>'.

CRUD Application & Business Objects

The annotations from the first two columns can be used to build read-only applications. Now we're ready to start with CRUD. The behavior definition turns the CDS view into a business object. The behavior definition is implemented in the form of an ABAP class.

An independent business object, i.e., one that can exist on its own, is a root view entity.

define root view entity zr_tasks_tp
as select from zi_Tasks
composition [0..*] of zr_comments_tp as _Comments
{
...

BOs that are part of the root object are linked as a composition association. The opposite direction is a to parent relationship. Only here is the join condition defined with on.

define view entity zr_comments_tp
as select from zi_comments
association to parent zr_tasks_tp as _Task 
on $projection.TaskKey = _Task.TaskKey
{
...

A behavior definition is only created for the root object.

For the SAP RAP model, behavior is defined in the Behavior Definition using the Behavior Definition Language (BDL).

Syntax

managed implementation in class zbp_i_users_tp unique;
strict ( 2 );
define behavior for zi_users alias Users
persistent table zbc_users
lock master
etag master LocalLastChanged
{
create;
update;
delete;
mapping for zbc_users corresponding
{
UserId = user_id;
DateOfBirth = date_of_birth;
ChangedBy = changed_by;
...
}
}

Components

• managed or unmanaged (line 1) - In the managed scenario, the CRUD operations do not have to be implemented yourself. implementation in class ... unique - Class name of the implementation. The class can be created after activation by a quick fix.
• strict(2) (line 2) - A more thorough syntax check is performed
• alias (line 3) - gives a name for the BO so that the CDS view name does not always have to be used
• Standard actions (lines 8-10) - CREATE, UPDATE, DELETE
• mapping (line 11 ff.) - If the field names in the BO (i.e., CDS) and the DB table differ, then a mapping is required. With CORRESPONDING, only those fields where the names are not 1:1 identical need to be mapped.
• etag master

Draft

Draft mode is a feature that allows end users to start, interrupt, and resume their work on entities at a later time without this data being immediately stored permanently in the database.

managed implementation in class zbp_i_users_tp unique;
strict ( 2 );
with draft;
define behavior for zi_users alias Users
persistent table zbc_users 
draft table zbc_users_d
lock master
total etag LastChangedAt
{ 
//entity behavior body
create;
update;
delete;

draft action Activate optimized;
draft action Discard;
draft action Edit;
draft action Resume;
draft determine action Prepare;
}

Additional components

• with draft - BO with draft mode
• draft table - Name of the draft table, see below
• total etag - Timestamp for draft
• draft action ... - Standard actions for draft

The draft table

There is a separate database table for draft data with the structure of the BO, i.e., the field names from the CDS. In addition, this table must contain a few admin fields of the structure SYCH_BDL_DRAFT_ADMIN_INC:

define table DraftTable 
{
key client: abap.clnt not null;
...
“%admin”: include sych_bdl_draft_admin_inc;
}

You can generate this table with a quick fix. To do this, write the line

draft table <table name>

and then call up the quick fix for it with Ctrl + 1.

Locks, ETAGs & Permissions

Locks with lock

The lock master information in the BDL locks the instance during the changing actions.

ETag

The ETag (Entity Tag) prevents accidental overwriting when editing an object simultaneously. It contains a timestamp from the time of the last save. A BO with its own ETag uses etag master <field name> to set the field in which the timestamp is to be stored.

Total ETag

The Total ETag is required for draft scenarios. It stores which version the user is currently editing or which version is current in the draft table.

Authorization check

With the definition authorization master ( instance ), the corresponding method is called in the implementation for a BO where an authorization check can be performed. If the value global is passed instead of instance, these checks can be performed independently of the individual instance.

Master or Dependent By

The definitions ETag, Authorization, and Lock refer to the BO in which they are defined with master. If they are to refer to another BO (often the root object), dependent by <association> can be specified instead.

Field Properties

The field properties are defined in the Entity Behavior Body:

field ( readonly ) fieldName;

• field ( readonly ) - Display only
• field ( readonly : update ) - Display only except when creating
• field (mandatory) - Mandatory field
• field (suppress) - Metadata is not displayed
• field (numbering: managed)

Multiple field properties can be combined. In Draft mode, mandatory fields are impractical during creation.

RAP BOs with custom implementation

So far, we haven't had to write a single line of ABAP. All properties and actions were implemented by the RAP framework. For actions, determinations, and validations, we need to write our own ABAP code. We write this in the implementation class, which is also called the Behavior Pool.

The behavior pool is a global class, but it does not have any public methods or properties. All implementations are implemented in a local class. The necessary classes, methods, and their signatures are generated with quick fixes.

Actions

An action defines a method of a CDS entity that can perform processing within or outside the business object.

Declaration of the action

{ ...
// Simple action
action someAction;

// Action with parameters
action someAction parameter zrap_parameters;
...}

After the action has been added to the BDL file, a warning is displayed indicating that the implementation is missing. This can be created with a quick fix in the behavior pool.

Action parameters

The action parameters are specified as a structure. This is an abstract CDS entity:

define abstract entity zrap_parameters
{
parameter1: abap.char(3);
parameter2: abap_boolean;
}

Actions on the interface

Actions are only visible if they are also annotated in the CDS. Depending on the position of the button, the action is integrated with different annotations:

• identification - Top right
• lineItem - In the table
• fieldGroup - In the field group

@UI.lineItem:[ { position: 10 ,
type: #FOR_ACTION, 
dataAction: 'myAction', 
label: 'Do Something' } ]

CDS & RAP Layer

In the SAP RAP model, CDS views and behavior definitions are divided into different layers to ensure a clear separation of responsibilities and better maintainability:

• C_ Consumption Layer - Specialization for a single app or service, projection of the reuse layer
• R_ Reuse Layer - RAP-specific, data modeling of the business object, total amount of all data
• I_ Interface View (VDM) - Tasks of this layer:
• Renaming of fields
• General annotations, e.g., currencies, semantics, ...
• Replacing data elements
• Database table