ETL Property Mapping (etl-map)

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

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:

Brandbox\EtlMap\Input\MapOriginSelect\Lib\Event\OnPopulateEnumerationElements

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:

\Brandbox\EtlMap\Etl\Map\Lib\Event\OnPopulateMapValue

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

\Brandbox\EtlMap\Etl\Map\Lib\Event\OnPopulateIsMapPropertyValid

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:

• Datensatzpflege
• Auswahl einer Tabelle und eines Datensatzes
• Datei
• Dateiauswahl
• Ordner
• Auswahl eines Datensatzes in einer Fremdtabelle

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
}

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.

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:

"crud": {
  "1": {
    "name": "Artikelname 1"
  },
  "2": {
    "name": "Artikelname 2"
   },
  "3": {
    "name": "Artikelname 3"
  }
}

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

"crud": "Artikelname 1"

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.