Cheat Sheet - RAP

Cheat Sheet RAP

Die perfekte Ergänzung zu den Schulungen

von Brandeis Consulting

Das ABAP RESTful Application Programming Model (RAP), zusammen mit Fiori Elements, ermöglicht es Entwicklern, effizient Cloud-fähige, transaktionale Geschäftsanwendungen zu erstellen.

Mit RAP werden Services erstellt.

Mit Fiori Elements werden die Daten aus den Services auf Standard-Floorplans dargestellt.

Dieser Spickzettel bietet einen umfassenden Überblick über die Syntax, Beispiele und Beschreibungen der Grundlagen von RAP und Backend-Annotationen von Fiori Elements, damit Sie sich schnell mit den wichtigsten Konzepten und praktischen Aspekten der Verwendung von RAP für Ihre Entwicklungsprojekte vertraut machen können.

In diesem Cheat Sheet werden immer CDS VIEW ENTITIES statt der seit 7.57 obsoleten CDS VIEWS verwendet.


Unter der Linie sind Referenzen zu Quellen, z.B.

Read Only Anwendungen

Im ersten Schritt betrachten wir nur die Fiori Elements Anwendungen, die wir auf Basis von CDS Views, ohne CRUD erstellen. Sie bestehen im einfachsten Falle aus vier Ebenen:

  • Datenbanktabelle
  • CDS View mit Annotationen
  • Service Definition
  • Service Binding

CDS Views für Read-Only Szenarien

Damit die Oberflächen mit Fiori Elements dargestellt werden, müssen in den CDS-Views ein paar Annotationen vorhanden sein. Im folgenden sind die Wichtigsten für die jeweiligen Bereiche beschrieben:

Associations

Die Beziehungen von Objekten untereinander werden durch Assoziationen abgebildet. Auf der Object Page können so Listen bzw. Tabellen von assoziierten Objekten dargestellt werden.

Service Definition

Service Definitions legen fest, welche Business Objekte in dem Service veröffentlicht werden sollen. Mit Alias Namen können die technischen Namen nach aussen für den Service schön benannt werden.

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

Service Binding

Service Bindings sind die Implementierungen der zuvor definierten Services. Sie verbinden die Service Definitionen mit den technischen Protokollen und Endpunkten, über die die Services tatsächlich konsumiert werden können. OData kann in 2 Versionen gewählt werden, SAP empfiehlt die Version V4. Folgende Bindungstypen können gewählt werden:

  • OData 2.0 (V2) oder 4.0 (V4) – OData Service der Version V2 oder V4
    • UI – Ein UI-Service ermöglicht das Hinzufügen von SAP Fiori UI-Elementen oder anderen UI-Clients.
    • Web API – Ein webbasierter API-Dienst, der für alle Anwendungen außer Benutzeroberflächen verwendet wird.
  • InA - UI – Information Access: für Analytische Datenmodelle Bsp. für Live-Datenzugriff.
  • SQL - Web API – Zugriff auf veröffentlichte, von ABAP verwaltete Datenbank-API-Objekte mit Open SQL.

Annotationen für Fiori Elements

Damit ein Service, basierend auf einem CDS View, in Fiori Elements schön dargestellt werden kann, werden Annotationen benötigt. Diese steuern Eigenschaften der Oberfläche und teilweise auch Funktionen.

Die nachfolgenden Beispiele geben nur einen kleinen Überblick über häufig verwendete Oberflächen Annotationen.

List Report Annotations

Die Annotation @UI.lineItem definiert, dass das Feld als Spalte in einer Tabelle angezeigt wird. Meist wird mindestens die position angegeben.

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

@ObjectModel.text.element stellt die Verbindung zwischen dem Bezeichner-Element und seinen beschreibenden sprachunabhängigen Texten her.

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

Object Page Annotations

Auf der Object Page wird eine Instanz eines Objektes dargestellt. Der Header-Bereich wird durch die Header Annotationen gestaltet. Die Objekt-Daten werden in sogenannten Facetten angezeigt:

Facetten

Die Bereiche, die auf der Object Page dargestellt werden sollen, müssen mit der Annotation @UI.facet definiert werden. Obwohl sich die Definition auf alle Spalten beziehen, werden sie nicht in den View-Annotationen sondern auf Feldebene definiert. Der Grund hierfür ist, dass sie sonst nicht propagiert werden. Normalerweise werden Facetten vor dem ersten Feld definiert.

Facette für den Identifikationsbereich

Felder in diesem Bereich sollen das Objekt, gemeinsam mit den Informationen aus dem Header, eindeutig identifizieren.

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

Felder, die in dieser Facette angezeigt werden sollen, benötigen die Annotation @UI.identification:

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

Facette für Feldgruppen

Feldgruppenfacetten zeigen eine Gruppe von Feldern mit ihren Beschriftungen an.

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

Felder, die in dieser Gruppe angezeigt werden sollen, benötigen die Annotation @UI.fieldGroup:

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

Facette für Tabellen

Diese Facette wird verwendet, um assoziierte Objekte als Tabelle anzuzeigen. Der Name der Assoziation ist in targetElement anzugeben. In der zugehörigen CDS-Entität muss die Annotation @UI.lineItem für die anzuzeigenden Felder angegeben werden.

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

Ergänzen, falls noch Platz ist: Assoziationen für Unterobjekte/verlinkte Objekte

Allgemeine Feld Annotationen

Die folgenden Annotationen können an unterschiedlichen Stellen eingesetzt werden. Zum Beispiel bei @UI.lineItem ,@UI.fieldGroup, @UI.identification:

  • hidden - Das Feld wird nicht angezeigt und kann auch mit Personalisierung nicht hinzugefügt werden
  • position - Gibt die Reihenfolge der Felder in der Facette/Tabelle an
  • label - Feldlabel
  • qualifier - Bezug auf den targetQualifier der Facette. Damit können unterschiedliche Darstellungen erreicht werden.

Suchhilfen

Eine Suchhilfe ermöglicht das Auswählen von Werten. Dazu wird ein anderer CDS-View als entity.nameangegeben und das entsprechende Feld, das übernommen werden soll, als entity.element. Mit additionalBinding können zusätzliche Bindungen zum Filtern definiert werden.

@Consumption.valueHelpDefinition: [
     {
       entity: { name: 'ZI_StatusVH', 
                 element: 'Status' }

//     zusätzlich das Projekt als Filterbedingung:
       additionalBinding: [{ localElement: 'Project', 
                             element: 'Project' }]
     }
  ]
  Status;

CRUD Anwendung & Business Objekte

Mit den Annotationen aus den ersten zwei Spalten kann man Read-Only Anwendungen bauen. Ab jetzt geht es los mit CRUD. Mit der Behavior Definition wird aus dem CDS-View ein Business Objekt. Zu der Behavior Definition gibt es Implementierung in Form einer ABAP-Klasse.

Struktur von Business Objekten

Ein unabhängiges Businessobjekt, also eines, das allein existieren kann, ist eine ROOT VIEW ENTITY.

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

BOs, die Bestandteil des Root Objektes sind, werden als COMPOSITION-Assoziation verknüpft. Die Gegenrichtung ist eine TO PARENT Beziehung. Nur hier wird die Join-Bedingung mit ON definiert.

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

Nur für das Root-Objekt wird eine Behavior Definition angelegt.

Behavior Definition

Für das SAP RAP Model wird in der **Behavior Definition** mit der Sprache **Behavior Definition Language (BDL)** ein Verhalten definiert.

Syntax

managed implementation in class zbp_i_users_tp unique;strict ( 2 );define behavior for zi_users alias Userspersistent 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;
    ...
  }
}

Bestandteile

  • managed oder unmanaged - Beim Managed Szenario müssen die CRUD Operationen nicht selber implementiert werden . implementation in class ... unique - Klassenname der Implementierung. Die Klasse kann nach dem Aktivieren durch einen Quick Fix angelegt werden.
  • strict(2) - Eine gründlichere Syntaxprüfung wird durchgeführt
  • alias - gibt einen Namen für das BO, damit nicht immer der CDS-View Name verwendet werden muss
  • Standard-Aktionen - CREATE, UPDATE, DELETE
  • mapping - Wenn die Feldnamen im BO (also CDS) und der DB-Tabelle sich unterscheiden, dann wird ein Mapping benötigt. Mit CORRESPONDING wird erreicht, dass nur die Felder gemappt werden müssen, wo die Namen nicht 1:1 gleich sind.
  • etag master

Draft

Der Draft-Modus ist eine Funktion, die es Endbenutzern ermöglicht, ihre Arbeit an Entitäten zu beginnen, zu unterbrechen und zu einem späteren Zeitpunkt wieder aufzunehmen, ohne dass diese Daten sofort fest in der Datenbank gespeichert werden. Der Draft-Modus ist nur mit oData V4 verfügbar.

managed;
with draft;define behavior for zi_users alias Users
persistent table zbc_users 
draft table zbc_users_dtotal etag LastChangedAt{
  create;
  update;
  delete;
  
  draft action Activate optimized;  draft action Discard;  draft action Edit;  draft action Resume;  draft determine action Prepare;}

Zusätzliche Bestandteile

  • with draft - BO mit Draft-Modus
  • draft table - Name der Draft-Tabelle, s.u.
  • total etag - Zeitstempel für Draft
  • draft action ... - Standardaktionen für Draft

Die Draft-Tabelle

Für die Draft-Daten gibt es eine separate Tabelle mit der Struktur des BOs, d.h. die Feldnamen aus dem CDS. Zusätzlich muss diese Tabelle noch ein paar Admin-Felder der Struktur SYCH_BDL_DRAFT_ADMIN_INC enthalten:

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

Man kann sich diese Tabelle mit einem Quick-Fix generieren lassen. Dazu die Zeile

draft table <Tabellenname>

hinschreiben und dann per Strg. + 1 den Quickfix dafür aufrufen.

Sperren, ETAGs & Berechtigungen

Sperren mit LOCK

Mit der Information LOCK MASTER in der BDL wird die Instanz während der ändernden Aktionen gesperrt.

ETag

Der ETag (Entity Tag) verhindert versehentliches überschreiben bei gleichzeitiger Bearbeitung eines Objektes. Er enthält einen Zeitstempel vom Zeitpunkt des letzten Speicherns. Ein BO mit eigenem ETag setzt mit ETAG MASTER <Feldname> das Feld, in dem der Zeitstempel gespeichert werden soll.

Total ETag

??? Der Total ETag wird für Draft-Szenarien benötigt. Hier wird gespeichert, welche Version der Benutzer aktuell bearbeitet bzw. welche Version in der Draft-Tabelle aktuell ist.

Berechtigungsprüfung

Mit der Definition AUTHORIZATION MASTER ( instance ) wird für ein BO die entsprechende Methode in der Implementierung aufgerufen, wo eine Berechtigungsprüfung durchgeführt werden kann. Wenn statt instance der Wert global übergeben wird, dann können diese Prüfungen unabhängig von der einzelnen Instanz durchgeführt werden.

Master oder Dependent By

Die Definitionen ETag, Authoriation und Lock beziehen sich mit MASTER auf das BO, in dem sie definiert werden. Wenn sie sich auf ein anderes BO (häufig das Root-Objekt) beziehen sollen, so kann statt dessen DEPENDENT BY <Assoziation>angegeben werden.

Feldeigenschaften

//Schuzt vor schreibenden Zugriff
field ( readonly ) some_id, another_value

//Schreibschutz nur bei Änderungen
field ( readonly : update ) some_id;

//Pflichtfelder bei allen Schreiboperationen
field ( mandatory ) some_value, another_value;

//Pflichtfeld nur beim Anlegen
field ( mandatory: create ) a_value;

//Feld wird in den Metadaten ausgeblendet
field ( suppress ) some_value;

//verwaltete Nummerierung (managed numbering:)
field ( numbering : managed, readonly ) some_uuid;

actions

Eine Action ist ein spezifischer Vorgang einer CDS-Entität, der Änderungsvorgänge innerhalb oder außerhalb des Geschäftsobjekts durchführen kann. Erfordert eine Implementierung im Behavior Pool.

...
{
  ...
  //einfache Action
  action someAction;

  //mit input parameters (die Entität ZRAP_Parameters muss definiert sein. siehe unten)
  action someAction parameter ZRAP_Parameters;

  //mit Rückgabeparameter 
  //Mit $self wird der Rückgabeparameter mit der aktuellen Instanz der CDS Entität typisiert, die die Aktion ausführt.
  action oneMoreAction parameter ZRAP_Parameters result [1] $self;

  //draft Aktionen können mit zusätzlicher Logik versehen werden
  draft action someDraftAction with additional implementation;

}

Definition der abstrakten Entität der Eingabe Paramater. Mehrere Parameter können auf diese Weise abgebildet werden

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

Actions sind nur dann sichtbar, wenn sie auch im CDS annotiert sind. Die Annotation wird bei irgend einem Feld (z.B. dem ersten) hinzugefügt.

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

static actions (für die gesamte Entität)

Static Actions in SAP RAP führen geschäftslogische Operationen durch, die unabhängig von einer bestimmten Instanz eines Geschäftsobjekts sind und daher nicht auf spezifische Objekteigenschaften zugreifen müssen.

static action someAction;
//factory erzeugt eine neue Instanz der Entität
static factory action otherAction [1];

functions

Funktionen haben nur lesenden Zugriff auf die Daten. Sie ändern die Daten des Geschäftsobjekts nicht. Sie können jedoch berechnete Werte oder Informationen über den Status des Objekts zurückgeben. Die Syntax ist die gleiche wie unter Aktionen. Es muss nur das Wort action durch function ersetzt werden.

dertermination (Ermittlung)

Mit Hilfe von Triggern können Änderungen am Business Objekt unmittelbar vor dem Speichern vorgenommen werden. Erfordert eine Implementierung im Behavior Pool.

//kurz vor dem Speichern
determination setDetermination on save { create; }
//unmittelbar nach einer Änderung oder Löschen
determination setDetermination on modify { update; delete; }
//Auslösebedingung auf Feldebene
determination setDetermination2 on modify { field SomeField, SecondField }
//Bedingungen können kombiniert werden (löst beim löschen und beim Ändern des Feldes SomeField aus)
determination setDetermination3 on modify { delete; field SomeField }

validation (Validierung)

Dadurch wird sichergestellt, dass die definierte Validierungslogik bei der Erstellung oder Aktualisierung der Daten zum Zeitpunkt der Speicherung angewendet wird. Erfordert eine Implementierung im Behavior Pool.

validation checkSomething on save { create; update; delete; }

Mehrere Auslösebedingungen können kombiniert werden, Auslösebedingungen können auch auf Feldebene definiert werden.

validation validateSomething on save { create; field some_field, other_field; }

dynamic feature control

Felder, Standard-Operationen und Aktionen können durch Features beeinflusst werden. Dazu ist eine Implementierung im Behavior Pool erforderlich. Es können inszanzbasierte ( features:instance ) oder globale features ( features:global) verwendet werden.

...
{
...
 //Felder
 field ( features : instance )SomeField;
 
 //Operationen
 create ( features : global );
 
 //Assoziationen
 association _Child { create (features : global); }
 
 //Aktionen
 action ( features : instance ) someAction;
 static action ( features : global ) otherAction;
}

Business Logic

wird in den Behaviospool-Klassen implementiert. Hierzu wird EML verwendet. EML ist Teil der ABAP-Sprache.

EML (Entity Manipulation Language)

Buch S. 230 ff.

EML ermöglicht den Zugriff auf Geschäftsobjekte (auch von außen) und die Implementierung von deren Verhalten.

in local mode

ermöglicht den Zugriff auf ein Objekt ohne Zugriffs- und Berechtigungskontrolle

READ ENTITIES

Lesezugriff auf Entitäten. READ ENTITIES greift auf den Transaktionspuffer des aktuellen Business Objekts zu, um z.B. Feldinhalte zu lesen.

DATA: lt_entities TYPE TABLE OF your_entity_type.
READ ENTITIES OF your_entity in LOCAL MODE
  ENTITY entity_name
  FIELDS ( field1 field2 field3 )
  WITH CORRESPONDING #( VALUE #( ( %key = '0001' ) ( %key = '0002' ) ) )
  INTO TABLE @lt_entities
  FAILED FAILED_SUB.

IF failed IS INITIAL.
  " Verarbeitung der gelesenen Daten
ELSE.
  " Fehlerbehandlung
ENDIF.

MODIFY ENTITIES

schreibender Zugriff auf die Eintitäten.

" Daten vorbereiten
DATA(lt_changes) = VALUE your_entity_type(
  ( %key = '0001' field1 = 'new value 1' field2 = 'new value 2' )
  ( %key = '0002' field1 = 'new value 3' field2 = 'new value 4' ) ).

MODIFY ENTITIES OF your_entity
  ENTITY entity_name
  CREATE FIELDS ( field1 field2 )
  WITH CORRESPONDING #( lt_changes )
MAPPED mapped 
FAILED  failed
REPORTED reported.

IF failed IS INITIAL.
  " Verarbeitung der Erfolgsfälle
ELSE.
  " Fehlerbehandlung
ENDIF.

Löschen von ENTITIES

MODIFY ENTITIES OF /DMO/I_Travel_D
 ENTITY TRAVEL 
  DELETE FROM VALUE #( ( TravelUUID = lv_travel_id 
                        %is_draft = if_abap_behv->mk-off_))
 FAILED DATA(failed) 
 REPORTED DATA(reported)

Vorlage

Schichten

Im SAP RAP Model werden CDS Views in verschiedene Sichten unterteilt, um eine klare Trennung von Verantwortlichkeiten und eine bessere Wartbarkeit zu gewährleisten.

  • I_ Basic Interface (Basis-Interface-Schicht): Diese Schicht definiert grundlegende Datenmodelle und stellt die Rohdaten aus der Datenbank bereit.
  • C Consumption (Consumption-Schicht): Diese Schicht ist für die Bereitstellung der Daten an die Endanwendungen oder Benutzer zuständig. Sie konsumiert die CDS-Views aus der I Schicht und fügt zusätzliche Logik, Aggregationen, Berechnungen und benutzerfreundliche Formate hinzu

CDS-Projektion

Projektionsansichten stellen eine eingeschränkte Sicht auf die Entitäten dar. Sie können auch mit Informationen angereichert werden, die nicht zum Kern des Datenmodells gehören. Sie basieren immer auf genau einem existierenden CDS-View oder einem CDS-DDIC-basierten View.

Wenn eine Projektion eine Kind-Beziehung hat, kann diese mit redirected to composition child definiert werden.

Wenn eine Projektion eine Beziehung zu einer übergeordneten Entität hat, kann diese über redirected to parent definiert werden.

@EndUserText.label: 'Projection View Consumption'
@AccessControl.authorizationCheck: #NOT_REQUIRED
define root view entity ZC_USERS as projection on zr_users_TP
{
    key UserId,
    Firstname,
    Lastname,
    Name,
    ...
    LocalLastChanged,

    /* Associations */
    _TasksToDo 
    //_TasksToDo : redirected to composition child zr_tasks_tp //Association als Komposition (composition)
    //_TasksToDo : redirected to parent zr_tasks_tp //Association zum Parent (association to parent)
}

RAP Generator

Mit einem Rechtsklick auf die Datenbanktabelle können über "Generate ABAP Repository Objects..." alle Repository-Objekte erzeugt werden.