ABAP CDS – EINE EINFÜHRUNG IN DAS THEMA „ANNOTATIONEN“

Einleitung

Dieser kurze Beitrag stellt ein paar grundlegende Informationen zu ABAP CDS Annotationen vor und soll den Aufbau, die Eigenschaften sowie die Wirkungsweise von Annotationen im Kontext von ABAP CDS anhand von Beispielen etwas verdeutlichen. Aufgrund der Vielzahl an Annotationen und deren Möglichkeiten, stellt der Beitrag natürlich nur einen kleinen Ausschnitt des gesamten Spektrums dar.

Was sind Annotationen und welche stellt SAP zur Verfügung?

Die von SAP spezifizierten Annotationen dienen dazu CDS Objekte um zusätzliche Daten anzureichern, mit denen verschiedene Einstellungen, Eigenschaften und funktionelle Erweiterungen definiert werden können. Prinzipiell können sie in zwei Kategorien unterteilt werden, ABAP Annotationen sowie Komponenten Annotationen, welche auch frameworkspezifische Annotationen genannt werden. Innerhalb dieser Gruppen sind Annotationen in unterschiedliche Domänen unterteilt:

  • ABAP Annotationen werden von der ABAP Laufzeitumgebung evaluiert
  • Komponenten-Annotationen werden vom Framework anderer Softwarekomponenten ausgewertet wie z.B. Analytics

Eine Liste aller im System verfügbaren Annotationen lässt sich zum Beispiel mit dem ABAP Programm ABAP_DOCU_CDS_ANNOS_OVERVIEW  auswerten:

Der Report gibt unter anderem folgende nützliche Informationen aus:

  • Name der Annotation
    • Geltungsbereich einer Annotation (z.B. VIEW wenn die Annotation die ganze View betrifft oder ELEMENT wenn nur ein Element bzw. Feld betroffen ist)
    • Datentyp des Annotationswertes
    • Mögliche Werte für die Annotation
    • Defaultwert der Annotation (sofern vorhanden)
    • Verfügbarkeit der Annotation in ABAP on Cloud
    • Typ der Annotation (ABAP oder Framework)

Informationen kann man ebenfalls direkt im Quellcode in der Viewdefinition aufrufen, indem man sich mit dem Cursor auf die jeweilige Annotation stellt und F1 drückt. Zusätzlich kann man Informationen natürlich auch direkt von den entsprechenden Help SAP Seiten beziehen.

Aufbau von Annotationen

Der Aufbau von Annotationen kann als hierarchisch betrachtet werden. Folgende Abbildung zeigt als Beispiel den strukturellen Aufbau der Domäne AccessControl deren Annotationen zu den ABAP Annotationen gehören:

Wie hier ersichtlich, kann eine Annotationsdomäne, welche als Elternknoten (blau) anzusehen ist, Unterknoten beinhalten und mehrere Ebenen tief sein. Die grünen Elemente stellen Unterknoten dar, die gelben sind Blattknoten denen letztendlich Werte zugeordnet werden. Die Anzahl der Blätter der Domäne entspricht damit auch gleich der Anzahl der Annotationen die diese Domäne zur Verfügung stellt.

Anhand dieser Domäne zeigen wir zwei Beispiele für Schreibweisen von Annotationen:

@AccessControl.personalData.blocking: #REQUIRED

@AccesControl.authorizationCheck: #CHECK

Die Syntax gibt vor, dass Annotationen immer mit dem Symbol @ eingeleitet werden und in der Bezeichnung die gesamte Struktur enthalten ist, wobei Knoten mit Punkten getrennt werden. Der Wert des Blattknotens (in unseren Beispielen #REQUIRED und #CHECK) wird nach dem Doppelpunkt angegeben. Ebenso ist unbedingt auf die Groß- und Kleinschreibung zu achten. Es können nur Werte mit dem für die jeweilige Annotation festgelegten Datentyp zugeordnet werden, wobei je nach Typ die Schreibweisen unterschiedlich sind. So werden variable Werte in Hochkommata geschrieben, festgelegte Konstanten mit einer Raute als Präfix. Werte vom Typ Boolean werden ohne zusätzliche Zeichen erfasst.  Wendet man mehrere Annotationen aus derselben Domäne auf ein- und dasselbe Element an, kann die Schreibweise auch in einer Zeile zusammengefasst werden (siehe Beispiel Annotation für zusätzliche Feldinformation).

Annotationen bei Anlage einer CDS-View

Wie bereits erwähnt, kann der Geltungsbereich einer Annotation die gesamte View betreffen oder auch nur ein einziges Element. Bei Anlage einer CDS View sind standardmäßig bereits einige Annotationen im Kopf enthalten welche die View betreffen. Diese werden nur kurz erläutert:

Bis auf die erste Annotation AbapCatalog.sqlViewName, welche zwingend einen Namen für die zu generierende SQL View verlangt, sind an dieser Stelle alle übrigen sichtbaren Annotationen optional (die Defaultwerte der Annotationen würden aber gültig bleiben, auch wenn diese entfernt werden).

Anwendungsbeispiele für Annotationen

Anwendung bei Definition eines DDIC Objekts

Im folgenden Beispiel wird eine Dictionary Tabelle namens ztposa im Eclipse mittels DDL in den Abap Development Tools definiert, welche unter anderem ein Betragsfeld value vom ABAP Typ CURR beinhaltet (Zeile 9). Das entsprechende Referenzfeld für den Währungsschlüssel cky vom ABAP Typ CUKY ist in Zeile 10 definiert:

Die Prüfung dieser Definition ergibt zunächst folgenden Fehler:

Das Referenzfeld für die Währung muss dem Betragsfeld value zuvor durch die semantische Annotation Semantics.amount.currencyCode entsprechend zugeordnet werden (Zeile 9):

Im Unterschied zu den Annotationen im Kopf, bezieht sich diese Annotation nicht auf die gesamte View sondern nur auf ein Element, das Feld value.

Annotationen in analytischen Anwendungen

Die nachfolgenden Beispiele bauen bereits auf Consumption Views auf, also analytischen Szenarien die im virtuellen Datenmodell relativ weit oben angesiedelt sind. Sie eignen sich aber sehr gut, um Funktion und Wirkungsweise von Annotationen zu veranschaulichen.

Annotationen in CDS Consumption View vom Typ CUBE

In folgendem Beispiel wird eine CDS View mittels der Annotation VDM.viewType (Zeile 7) als Consumption View definiert und dadurch für analytische Zwecke bereitgestellt. In Zeile 6 wird die Annotation Analytics.dataCategory mit Wert #CUBE verwendet um die View als klassischen multidimensionalen Infoprovider zu definieren:

In der Select Anweisung ist die Annotation DefaultAggregation mit dem Wert #SUM in Zeile 14 vor dem Betragsfeld _tb.value gesetzt. Der Geltungsbereich dieser Annotation bezieht sich auf das Feld _tb.value.

Bei dieser Annotation handelt es sich um eine Framework-spezifische Annotation. Sie bewirkt in diesem Fall, dass das Element _tb.value in der View als Kennzahl mit der Standardaggregation Summation definiert wird und Werte in analytischen Anwendungen bei Aggregation bzw. in Ergebnisfeldern summiert werden. Wir sehen uns das Ergebnis unseres CDS-Views in Analysis for Office an:

Mit zusätzlichen Feldern im Aufriss und Ergebniszeile auf Basis des Feldes pos:

Ohne der Annotation DefaultAggregation, würde der Betrag nicht aggregiert bzw. in unserem Fall nicht summiert werden. So sähe das Resultat aus:

Natürlich stehen für Standardaggregation auch die anderen gängigen Aggregationsarten zur Verfügung (MIN, MAX, etc.).

Annotationen im Kontext von Querydesign

Die folgende Abbildung zeigt erneut eine Consumption View, in diesem Fall vom Typ Query. Damit die View als Query interpretiert wird, wurde in Zeile 7 die Annotation Analytics.query mit dem Wert true gesetzt:

Durch die Annotation Analytics.Details.query.axis an den entsprechenden Stellen in der Select Anweisung und den Werten #ROWS bzw. #COLUMNS, wird definiert welches Feld sich im initialen Aufriss in den Zeilen und welches in den Spalten befindet. Die Annotation AnalyticsDetails.query.totals in Zeile 12 sorgt zudem dafür, dass standardmäßig eine Ergebniszeile auf Basis des Feldes doc gebildet wird. Mit der Annotation EndUserText.label welche zusätzlich vor jedes Feld in der Select Anweisung gesetzt wurde, wird die Bezeichnung der Feldnamen durch die in Hochkommata gesetzten Beschreibungen übersteuert.

So sieht der Initialaufriss der Query im Frontend gemäß der View Definition und Annotationen aus:

Wenn wir die Query nun beispielsweise durch eine Formel erweitern wollen, können wir dies ganz einfach machen in dem wir ein zusätzliches Feld im Select Statement aufnehmen (in diesem Fall valuex2) und mittels der davor gesetzten Annotation AnalyticsDetails.query.formula eine Formel definieren (hier value * 2). Wir führen hier also eine simple Multiplikation des Betrags mal zwei durch:

Wie auch in den vorherigen Beispielen verwenden wir die Annotation EndUserText.label um die Bezeichnung der Felder im Bericht zu übersteuern.

So sieht die View bei Ausführung in AFO aus:                                                            

Da die View als Query definiert ist, kann sie auch mittels RSRT oder im Fiori Launchpad im Query Browser ausgeführt werden:

Annotation für zusätzliche Feldinformation

Im letzten Beispiel konsumieren wir eine einfache CDS View mittels ABAP Report und geben sie als ALV Liste aus. Zu den bereits bekannten EndUserText.label Annotationen wird nun in Zeile 13 zusätzlich die Annotation EndUserText.quickInfo eingefügt, welche eine ergänzende Textinformation zum Feld doc beinhaltet.

Das Ergebnis der View mittels ABAP Report in ALV Format:

Wie zu sehen ist, sorgt die Annotation in Zeile 13 dafür, dass bei Bewegen der Maus über das Feld Beleg die zusätzliche Information (Quickinfo) angezeigt wird.

Wenn wir uns an den Anfang des Beitrags und den Aufbau von Annotationen zurückerinnern, kann eine Domäne verschiedene Annotationen beinhalten. Wir setzen in diesem Beispiel ebenfalls zwei unterschiedliche Annotationen (Zeile 12 und 13) aus derselben Domäne EndUserText für ein- und dasselbe Element ein. Die Elemente label und quickInfo stellen zwei Blattknoten der Domäne EnduserText dar. In solchen Fällen kann die Schreibweise für die Annotationen folgendermaßen in einer einzigen Zeile zusammengefasst werden:

@EndUserText:{label:’Beleg‘,quickInfo:’Belegnummer des Einkaufsbelegs‘}

Der Doppelpunkt folgt direkt nach der Domäne, die beiden Elemente bzw. Blattknoten label und quickInfo (inkl. deren Werten), werden in geschweifte Klammern gesetzt und mit Beistrichen getrennt.

Conclusio

Wie bereits dieser kurze Beitrag zeigt, reichen die Möglichkeiten von Annotationen im Kontext von ABAP CDS weit über Kommentar- bzw. Strukturierungsfunktionen des Codings hinaus und stellen ein mächtiges Werkzeug für die Definition sowie Modellierung von Daten aber auch die funktionelle Erweiterung von CDS View dar.