Das Mapping-Tag besitzt keine eigenen Attribute und übernimmt Quell- und Zieltypen von der Mapping-Sammlung, in der es sich befindet. Es dient der Zuordnung eines einzelnen Wertes.
Das einfache Mapping-Tag kann die folgenden weiteren Tags beinhalten…
<From type=“text | formula | jsonpath | enum“>
<From> beschreibt, auf welche Art und Weise der Wert, der weiterverarbeitet werden soll, ermittelt wird. Der ganze Wert ist über die Attributangabe xsi:nil="true" nullbar, was tendenziell nur bei Mappings des Typs „text“ Sinn macht; in diesem Fall wird dann versucht die Zieleigenschaft null zu setzen (anstatt Leerstring).
Es folgen die möglichen Attributwerte des type-Attributs und deren jeweilige Funktion:
Attributwert: text
Der Text, wie er im Tag-Wert angegeben ist, wird zur weiteren Verarbeitung verwendet.
Attributwert: formula
Der Text, der im Tag-Wert angegeben ist, wird als Formel gegen den Quelltypen des Mappings validiert und zur Ermittlung des Wertes für die weitere Verarbeitung gegen das Quellobjekt ausgeführt.
Attributwert: jsonpath
Funktioniert nur auf Quellobjekten des Typs Newtonsoft.Json.Linq.JToken; die JSON-Rückgabe eines aufgerufenen Webservice ist immer von diesem Typ. Der Text, der im Tag-Wert angegeben ist, wird als JSONPath-Abfrage gegen das JToken ausgeführt. Weitere Informationen zu zur Verfügung stehenden Ausdrücken und Syntax finden Sie unter: https://www.newtonsoft.com/json/help/html/QueryJsonSelectToken.htm.
Hinweis: Das Ergebnis eines JsonPath-Mappings ist immer ein string, auch, wenn in der Quell-Json-Struktur ein anderer Typ verwendet wurde. Um den Zieltyp zu variieren, verwenden Sie bitte eine Transformation (siehe unten).
Attributwert: enum
Kann nur auf Quellobjekte vom Basistyp OrmBABase verwendet werden (bei programmierter Verwendung der Schnittstelle sind auch andere Typen verwendbar), der Tag-Wert gibt einen Quellpfad zu einer Datensatzeigenschaft an.
Da die Verwendungsmöglichkeiten sehr vielfältig sind, hier einige Beispiele anhand verschiedener Auswahllisten in einem Firmendatensatz und dessen Teildatensätzen:
<From type="enum">Industry</From>
Liefert die Guid des aktuell gewählen Auswahllistenwertes der Branche zurück.
<From type="enum">Industry.Language_de</From>
Liefert die deutsche Übersetzung des ausgewählen Auswahllistenwertes zurück. Dies funktioniert auch mit allen anderen zusätzlichen Werten, die in Auswahllistenwerten existieren können (zum Beispiel auch mit
„Country.IsoCode“)
<From type="enum">Addresses[0].Country</From>
Liefert die Guid des in der technisch ersten Anschrift gewählten Landes zurück (Index beginnt bei 0!).
<From type="enum">Addresses[EB7852EF-9BA5-47F6-AB68-82FB891A2943].Country</From>
Liefert die Guid des Landes der Hauptanschrift zurück (die abgebildete Guid ist die Guid des Auswahllistenwertes „MainAddress“). Wenn eine Guid als Index verwendet wird, muss das Teildatensatzfeld einen einzigartigen Schlüssel besitzen und diese Guid muss Teil der zugehörigen Auswahlliste sein.
<From type="enum">Addresses[…].Country.IsoCode</From>
Liefert den ISO-Code des gewählten Landes der entsprechenden Anschrift zurück.
Das Ergebnis eines JsonPath-Mappings ist immer ein string, auch, wenn in der Quell-Json-Struktur ein anderer Typ verwendet wurde. Um den Zieltyp zu variieren, verwenden Sie bitte eine Transformation (siehe unten).
<To>
Das <To>-Tag beschreibt, wohin der verarbeitete Wert im Zielobjekt geschrieben werden soll und kann einen mit Punkten getrennten Pfad beinhalten.
Für bestimmte Anwendungen kann der <To>-Wert über die Attributangabe xsi:nil="true" genullt werden (s. Spezialfälle). Wenn das Zielobjekt ein Datensatz ist, funktioniert der Zugriff auf Teildatensätze wie oben beim <From>-Tag für den Typen „enum“ beschrieben, das heißt, als Index von Teildatensätzen sind Zahlen oder Guids verwendbar. Ist das Ziel des Pfades eine Auswahlliste, gelten einige Besonderheiten (Beispiele):
<To>Industry</To>, From ist eine Guid
Es wird versucht, dem Feld „Industry“ den Auswahllistenwert mit der angegebenen Guid zuzuweisen. Ist dies nicht möglich, ist „Industry“ nach der Verarbeitung „null“.
<To>Industry</To>, From ist „Dienstleistung IT“
Die Übersetzungen der in der zum Feld „Industry“ gehörenden Auswahllistenwerte werden nach dem gegebenen Wert durchsucht. Ist die Suche erfolgreich, wird der entsprechende Auswahllistenwert für das Feld ausgewählt, wird kein passender Auswahllistenwert gefunden, wird ein neuer mit dem gegebenen Wert in allen Übersetzungen angelegt und dieser entsprechend gesetzt.
<To>Addresses[0].Country.IsoCode</To>, From ist „de“
Natürlich kann keine Eigenschaft des aktuell gewählten Auswahllistenwerts verändert werden. In diesem Fall wird der zusätzliche Wert „IsoCode“ der Auswahlliste der Länder nach dem in<From>ermittelten Wert durchsucht und der entsprechend passende Auswahllistenwert gesetzt, das heißt, in dem obigen Beispiel würde das Land der ersten Anschrift des Datensatzes auf „Deutschland“ gesetzt werden.
<Transform>
Dieses Tag ist optional und kann eine Formel beinhalten, die den durch ermittelten Wert nochmals verändert. Das von <Transform> gelieferte Ergebnis ist dann der Wert, der von <To> weiterverarbeitet wird. Die Verwendung dieses Tags ist nützlich, um beispielsweise Typumwandlungen oder Nullchecks durchzuführen. Auf den von <From> gelieferten Wert wird in dieser Formel per „[This]“ zugegriffen.