Cheat Sheet RAP Basics

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 ersten Überblick über die Syntax, Beispiele und Beschreibungen der Grundlagen von RAP und Backend-Annotationen für Fiori Elements, damit Sie sich schnell mit den wichtigsten Konzepten und praktischen Aspekten der Verwendung von SAP RAP für Ihre Entwicklungsprojekte vertraut machen können. Die Namenskonventionen in den Abbildungen beziehen sich auf den aktuellen Standard bei der SAP. Kunden müssen entsprechend den Z- bzw. Y-Namensraum davor schreiben.

In diesem Cheat Sheet werden durchgängig CDS View Entities statt der seit 7.57 obsoleten CDS Views verwendet.

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:

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

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 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 Bindings weisen den zuvor definierten Services ein Protokoll zu. Sie können direkt lokal veröffentlicht werden. Bein V4 geht das über die Transaktion /IWFND/V4_ADMIN. Folgende Binding-Types können gewählt werden:

• OData 2.0 (V2) oder 4.0 (V4) - Version V2 oder V4
  • UI - Überträgt die UI-Annotationen
  • Web API - Ohne UI-Annotationen
• InA - UI - Für Analytische Datenmodelle Bsp. für Live-Datenzugriff.
• SQL - Web API - Zugriff mit Open SQL.

V2 oder V4

Die SAP empfiehlt die Verwendung von V4. Dieser unterstützt Fiori Elements nur mit Draft vollständig. V2 ist nicht deprecated oder veraltet, es überträgt aber mehr Datenvolumen.

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.

Header Annotations

Auf View Ebene, also vor der eigentlichen Definition des Views. Diese Annotationen beziehen sich auf den ganzen View und werden nicht nach oben propagiert. Die Standard-Annotationen aus den Templates werden hier nicht gezeigt.

@UI: {
  headerInfo: {
    typeName: 'Aufgabe',
    typeNamePlural: 'Aufgaben',
    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

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: 'Bearbeiter' ,
                  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,

Filtern und Suche

Filter

Die Filterfelder eines List Report können vom Benutzer über den Button Filter anpassen selber eingestellt werden. Wenn die Annotation @UI.selectionField verwendet wird, können diese voreingestellt werden. Auch hier muss mindestens die position angegeben werden.

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

Suche

Für eine unscharfe Suche über mehrere Felder kann die @Search Annotation auf View-Ebene verwendet werden.

@Search.searchable: true   

Für jedes Feld, das Durchsuchbar sein soll, kommen dazu noch die folgenden Annotationen:

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

Der fuzzinessThreshold (Intervall 0 bis 1) gibt an, wie unscharf gesucht werden soll. Die SAP empfiehlt als Startwert 0.7.

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'
  } ]
  ...

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.name angegeben 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' }
       useForValidation: true,
       additionalBinding: [ { localElement: 'Project', 
                              element: 'Project' } ]
     } ]
Status;

Texte zu Schlüsseln

Damit auf der Oberfläche für Schlüsselwerte auch die zugehörigen Texte angezeigt werden, kann man einen Text-View mit passenden Annotationen assoziieren:

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
}

Das Feld des verwendenden Views muss die Annotation @ObjectModel.text.association: '<TextAssoziation>' haben

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.

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.

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 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;
    ...
  }
}

Bestandteile

• managed oder unmanaged (Zeile 1) - 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) (Zeile 2) - Eine gründlichere Syntaxprüfung wird durchgeführt
• alias (Zeile 3) - gibt einen Namen für das BO, damit nicht immer der CDS-View Name verwendet werden muss
• Standard-Aktionen (Zeilen 8-10) - CREATE, UPDATE, DELETE
• mapping (Zeile 11 ff.) - 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.

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;
}

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 Datenbanktabelle 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 Quick-Fix 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

Die Feldeigenschaften werden im Entity Behavior Body definiert:

field ( readonly ) fieldName;

• field ( readonly ) - Nur anzeigen
• field ( readonly : update ) - Ausser beim Anlegen nur anzeigen
• field ( mandatory ) - Pflichtfeld
• field ( suppress ) - Metadaten werden nicht angezeigt
• field ( numbering : managed )

Mehrere Feldeigenschaften können kombiniert werden. Beim Draft Modus sind Pflichtfelder beim Anlegen unpraktisch.

RAP BOs mit eigener Implementierung

Bislang haben wir keine Zeile ABAP schreiben müssen. Alle Eigenschaften und Aktionen waren vom RAP Framework implementiert. Für Actions, Determinations und Validations müssen wir eigenen ABAP Code schreiben. Diesen schreiben wir in der Implementierungsklasse, die auch Behavior Pool genannt wird.

Der Behavior Pool ist eine globale Klasse, die allerdings keine öffentliche Methoden oder Eigenschaften hat. Alle Implementierungen werden in einer lokalen Klasse implementiert. Die notwendigen Klassen, Methoden und deren Signatur wird mit Quick-Fixes generiert.

Actions

Eine Action definiert eine Methode einer CDS-Entität, die Verarbeitungen innerhalb oder außerhalb des Geschäftsobjekts durchführen kann.

Deklaration der Action

{ ...
  // Einfache Aktion
  action someAction;

  // Aktion mit Parametern
  action someAction parameter zrap_parameters;
  ...}

Nach dem die Action in der BDL Datei hinzugefügt wurde, wird eine Warnung angezeigt, dass die Implementierung fehlt. Diese kann mit einem Quick-Fix in dem Behavior Pool angelegt werden.

Parameter der Action

Die Parameter der Aktion werden als Struktur angegeben. Diese ist eine abstrakte CDS Entität:

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

Actions auf der Oberfläche

Actions sind nur dann sichtbar, wenn sie auch im CDS annotiert sind. Je nach Position des Button wird die Action entweder bei unterschiedlichen Annotationen eingebunden:

• identification - Rechts oben
• lineItem - In der Tabelle
• fieldGroup - In der Feldgruppe

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

CDS & RAP Layer

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

• C_ Consumption Layer - Spezialisierung für eine einzelne App oder einen Service, Projektion des Reuse-Layers
• R_ Reuse Layer - RAP-spezifisch, Datenmodellierung des Business Objekt, Gesamtmenge aller Daten
• I_ Interface View (VDM) - Aufgaben dieser Schicht:
  • Umbenennung der Felder
  • Allgemeingültige Annotationen, z.B. Währungen, Semantics, ...
  • Datenelemente ersetzen
• Datenbanktabelle