Mappingprofile

Was sind Mappingprofile?

Über Mappingprofile werden die Felder einer Tabelle definiert, die eine REST-Page verarbeiten kann. Dies dient einerseits zur Verschleierung der nicht notwendigen Felder nach außen, als auch zur Erhaltung der Kompatibilität bei Feld-Änderungen durch ein brandbox-Update.
Datenbezogene REST-Pages können nicht ohne Mapping funktionieren.

Legen Sie einen Datensatz in Datenbankfelder (Mapping) an, um ein Mappingprofil zu definieren

Feld	Beschreibung

Feld	Beschreibung
Name	Der Name der Map
Typ	Die Tabelle, aus der Daten gemapped werden sollen

Es kann notwendig sein, für unterschiedliche Http-Request-Methoden unterschiedliche Mapping-Profile zu verwenden. Bspw. möchte man beim Auslesen einer Datensatzliste den Inhalt von 10 bestimmten Feldern zurückgeben, für das Schreiben eines Datensatzes aber nur 5 dieser Felder erlauben. Durch die Definition zweier unterschiedlicher Mapping-Profile für die Request-Typen GET und DELETE lässt sich dies konfigurieren.

Map befüllen

Um nicht für jede Map alle gewünschten Felder immer wieder manuell anlegen zu müssen, steht eine Funktion bereit, die diese Aufgabe übernimmt. Es werden automatische alle Felder der gewählten Tabelle mit dem Feld-Identifier als Label angelegt und zur Map verknüpft. Nicht gewünschte Felder können dann manuell entfernt werden.

Legen Sie eine Map in an und speichern Sie
Klicken Sie in der Toolbar auf Map befüllen
Bestätigen Sie

Die Felder der gewählten Tabelle werden automatisch als Map-Datensätze angelegt und an die Map verknüpft. Auf Wunsch können natürlich in der Tabelle Map-Datensätze manuell angelegt und verknüpft werden.

Eigene Datenstrukturen anbinden

Im Feld Datenbankfeld der Tabelle Datenbankfelder (Mapping) lassen sich standardmäßig alle Felder aller Tabellen (außer Versionstabellen) mappen. Um eigene Datenquellen zu ergänzen, steht ein Event zur Verfügung:

Event-Klasse	Beschreibung

Event-Klasse	Beschreibung
^{Brandbox\EtlMap\Input\MapOriginSelect\Lib\Event\OnPopulateEnumerationElements}	Wird beim Laden des Auswahlfelds "Datenbankfeld" ausgelöst und enthält alle Einträge für das Auswahlfeld

Da sich solche Datenquellen nicht immer als Property einer Tabelle abbilden lassen, steht ein Event zur Verfügung, um den gemappten Wert für eine gewählte Datenquelle zu ermitteln:

Event-Klasse	Beschreibung

Event-Klasse

Beschreibung

^{\Brandbox\EtlMap\Etl\Map\Lib\Event\OnPopulateMapValue}

Wird beim Ermitteln des zu mappenden Werts ausgelöst. Der Standard Subscriber liefert den Inhalt eines Properties eines Datensatzes zurück

\Brandbox\Framework\Brandbox\Dbal\Definition\EntityInterface $entity: enthält das zu mappende Entity
bool $hasTranslationValue: gibt an, ob der zu mappende Wert übersetzbar ist
bool $isTranslation: gibt an, ob gerade ein Übersetzungswert aus dem Knoten (translations) gemappt wird
\Brandbox\EtlMap\Etl\Map\Lib\Entity\EtlMapProperty$property: enthält den Mapping-Datensatz vom Typ Datenbankfelder (Mapping)
mixed $value: enthält den gemappt Ergebniswert

Über ein weiteres Event kann validiert werden, ob ein Map-Datensatz gültig ist:

Event-Klasse	Beschreibung

Event-Klasse

Beschreibung

^{\Brandbox\EtlMap\Etl\Map\Lib\Event\OnPopulateIsMapPropertyValid}

Wird beim Validieren des zu mappenden Werts ausgelöst. Der Standard Subscriber prüft, ob die gewählte Spalte in der Tabelle verfügbar ist

array $columnIdentifiers: enthält alle Spalten-Identifikatoren der Tabelle
bool $isValid: gibt an, ob die Property (noch) verfügbar ist. Dieser Wert muss vom Subscriber ermittelt werden
\Brandbox\EtlMap\Etl\Map\Lib\Entity\EtlMapProfile $profile: enthält das Mappingprofil
\Brandbox\EtlMap\Etl\Map\Lib\Entity\EtlMapProperty $property: enthält den Mapping-Datensatz vom Typ Datenbankfelder (Mapping)

Transformationen und Callbacks

Auf einzelne Datenbankfelder (Mapping) können Transformationen angewendet werden, um die Werte zu verändern. Damit können bspw. String-Operationen wie Währungsformatierungen auf gemappte Werte angewendet werden, aber auch komplexere Operationen wie das Auflösen von Fremdschlüsseln.

Auflösung von Fremdschlüsseln (ResolveForeignKeys)

Werden Felder gemappt, die auf eine Fremdtabelle verweisen (Foreign Key), ist es möglich, direkt Daten aus dem referenzierten Datensatz zu beziehen. Dazu muss eine Transformation angewendet werden, die den Callback Resolve Foreign Keys enthält.
Dies funktioniert für folgende Feldtypen:

Damit Werte aus der verknüpften Fremdtabelle ermittelt werden können, müssen diese zusätzlich gemappt werden.
Dies geschieht, indem ein Datenbankfelder (Mapping)-Datensatz für die Fremdtabelle definiert und als Kind-Datensatz an den Datenbankfelder (Mapping)-Datensatz, der das Foreign-Key-Feld mappt, verknüpft wird.

Ohne Anwendung der Transformation und Spezifikation der Kind-Datensätze werden bei Foreign-Key-Feldern die Werte aus der Datenbank ausgegeben, also die ID(s) der referenzierten Datensätze.

Beim Auflösen von Fremdschlüsseln werden Unter-Arrays gebildet, deren Keys eine einfache Liste repräsentieren, d.h. die Array-Indizes werden von 0 beginnend hochgezählt.

Optional ist es möglich die ID des referenzierten Datensatz als Key zu verwenden. Hierfür muss bei der Transformation die Konfiguration wie folgt definiert werden:

{
    "UseIdAsKey": true
}

Weiterhin kann der Meta-Knoten, der für alle Datensätze aus aufgelösten Fremdschlüsseln ergänzt wird, optional versteckt werden:

{
    "HideMeta": true
}

Für Menschen lesbare Darstellung (HumanReadable)

Durch diese Transformation können Fremdschlüssel direkt anhand eines vordefinierten Mechanismus in einem für Menschen lesbaren Format dargestellt werden. Dabei wird der Fremdschlüssel so aufgelöst, dass die für den Ziel-Datensatz als Identifikatoren definierten Felder für die Darstellung des Werts verwendet werden.
Bei der Verwendung dieser Transformation ist kein weiteres Mapping notwendig.

Event	Beschreibung

Event	Beschreibung
`Brandbox\EtlCore\InputEtl\Abstract\Lib\Event\OnPopulateHumanReadable`	Ermittelt das Entity, anhand dessen Widget der HumanReadable-Wert gebildet wird.
`Brandbox\EtlCore\InputEtl\Abstract\Lib\Event\OnPopulateHumanReadableValue`	Ermittelt den HumanReadable-Wert. Kann für Datenstrukturen verwendet werden, die nicht auf dem Widget eines Entity basieren.

Array Strukturen verflachen (FirstValueFromSubArray)

Beim Auflösen von Fremdschlüsseln werden Unter-Arrays gebildet. Um einen Wert aus einem Foreign-Key-Feld direkt auszugeben, kann der Callback Retrieve first value from all sub arrays angewendet werden. Dieser holt den ersten Wert aus dem Unter-Array.

Beispiel:

Es wird der Wert eines Feldes vom Typ Datensatzpflege gemappt, dass auf die Tabelle Artikel verweist, das Label wird "crud" gepflegt. Standardmäßig würde der Datenbankwert gemappt, in diesem Fall ein Array aus IDs der Fremdtabelle:

"crud": [
  "1",
  "2",
  "3"
]

Würde man nun eine Transformation zuordnen, die ein Callback vom Typ Resolve Foreign Keys enthält und den Artikelnamen als Kind-Mapping (mit Label "name") anhängen, würde folgendes ausgegeben:

Nach zusätzlicher Anwendung des Callbacks Retrieve first value from all sub arrays wäre das Ergebnis:

Die Anwendung des Callbacks ist sinnvoller für Foreign-Key-Felder, die auf einen Datensatz verweisen. Wie hier im Beispiel deutlich wird, nimmt der Callback bei Foreign-Key-Feldern mit mehreren Datensätzen den allerersten Wert aus dem Unter-Array.
Dies gilt auch, wenn aus der Fremdtabelle mehrere Felder gemappt werden.