/
Mapping

Mapping

Owned by Daniela Zimmermann
Last updated: Jun 16, 2023 by Dinah Bolli (Unlicensed)
5 min read

Mit diesem standardisierten Format lassen sich Mappings durch primedocs hindurch einheitlich konfigurieren.

Beispiele:

<Mapping> <Map Source="fname" Target="Forname" /> <Map SourceValue="Hanna" Target="Forname" /> <Map SourceValue="Muster" Target="LastName" When="source('test') === 'someValue'" /> <Map SourceExpression="25*78" Target="Calculator" When="target('LastName') === 'Muster'" /> <Map> <Map.Source>fname</Map.Source> <Map.Target>Vorname</Map.Target> </Map> <Map> <Map.SourceValue>Hanna</Map.SourceValue> <Map.Target>Firstname</Map.Target> </Map> <Map> <Map.SourceValue>Muster</Map.SourceValue> <Map.Target>LastName</Map.Target> <Map.When><![CDATA[source('test') < 12]]></Map.When> </Map> <If Condition="source('test') === 'someValue'"> <Map> <Map.SourceExpression>25*78</Map.SourceExpression> <Map.Target>Calculator</Map.Target> </Map> </If> </Mapping>

JavaScript

Im Mapping kann man mit einfachen deklarativen Anweisungen ein Mapping vornehmen oder über JavaScript eine komplexere Logik abbilden. Auf der JavaScript-Seite befindet sich eine detailliertere Einführung.

Eigenschaften als Elemente oder Attribute

Alle nachfolgenden Element-Eigenschaften können gemäss nachfolgendem Muster sowohl als Attribut als auch als Element gesetzt werden.

Als Attribut:

<Elementname Attributname="Attributinhalt"> weiterer Elementinhalt </Elementname>

Als Element:

<Elementname> <Elementname.Attributname>Attributinhalt</Elementname.Attributname> weiterer Elementinhalt </Elementname>

Beim If-Element mit Condition-Eigenschaft haben die folgenden beiden Konfigurationen genau dieselbe Bedeutung:

<If Condition="source('LastName') === 'Muster'"> ... </If>
<If> <If.Condition>source('LastName') === 'Muster'</If.Condition> ... </If>

Map-Element

Ein Map-Element stellt eine einzelne Zuordnungsoperation dar. Es muss genau eine Source-Eigenschaft und das Target gesetzt sein.

Eigenschaft

Beschreibung

Eigenschaft

Beschreibung

Source

  • Im Standardfall: Der Name, der den Wert identifiziert, z. B der Spaltenname der Datenbank im Generic SQL Provider.

  • Bei XML-Datenquelle: siehe XML

Wenn der Wert nicht gefunden wird, wird null weitergegeben.

SourceValue

Ein konstante Wert, der verwendet werden soll.

SourceExpression

Eine primedocs-JavaScript-Expression, die ausgewertet wird.

Target

Die Zieleigenschaft für das Mapping. Die möglichen Zielfelder bei AddressProvidern sind unter Standard-Kontakt-Mapping dokumentiert.

When

Eine primedocs-JavaScript-Expression, die es erlaubt, das Mapping bedingt auszuführen.
Wenn der Wert auf wahr ausgewertet wird, wird das Mapping ausgeführt.

If-Element

Das If-Element erlaubt es, Bedingungen für ganze Blöcke von Mappings zu definieren. If-Blöcke können beliebig kombiniert und verschachtelt werden.

Eigenschaft

Beschreibung

Eigenschaft

Beschreibung

Condition

JavaScript-Bedingung – Resultat wird auf truthy-Wert geprüft.

Bedingungen & Ausdrücke

Escaping

In XML haben gewisse Zeichen wie & oder < eine besondere Bezeichnung. Diese können daher nicht direkt verwendet werden. Maskieren Sie diese: & kann als &amp; geschrieben werden:

<Mapping> <Map Source="Value" Target="Target" When="source('val1') === 'test1' &amp;&amp; source('val2') === 'test2'" /> </Mapping>

Alternativ kann dasselbe mittels CDATA und Element-Schreibweise gemacht werden:

<Mapping> <Map Source="Value" Target="Target"> <Map.When><![CDATA[source('val1') === 'test1' && source('val2') === 'test2']]></Map.When> </Map> </Mapping>

Source

Mittels source-API-Objekt kann vom JavaScript aus analog der Source-Eigenschaft des Map-Elements auf die Quellwerte zugegriffen werden. Ist der Wert nicht verfügbar, wird undefined zurückgegeben. Folgendes Beispiel nimmt die letzte verfügbare Telefonnummer:

<Mapping> <Map Source="Arbeitsplatz" Target="Phone" When="source('Arbeitsplatz') != null" /> <Map Source="Mobile" Target="Phone" When="source('Mobile') != null" /> </Mapping>

Aus Kompatibilitätsgründen kann auch mittels oo oder OO auf das source-API-Objekt zugegriffen werden.

Target

Mittels target-API-Objekt kann vom JavaScript aus auf zuvor gemappte Werte zugegriffen werden. Ist der Wert nicht verfügbar, wird undefined zurückgegeben. Folgendes Beispiel setzt eine Adresse zusammen:

<Mapping> <Map SourceExpression="source('street')+' ' +source('hausnr')" Target="Street" /> <Map SourceExpression="target('street') + '\r\n' + source('PLZUndOrt')" Target="CompleteAddress" /> </Mapping>

Das ergibt folgendes Resultat:

Source ---------- street Teststrasse hausnr 42 PLZUndOrt 4242 Testhausen Resultat ---------- Street Teststrasse 42 CompleteAddress Teststrasse 42 4242 Testhausen

Main-Funktion

Um komplexere JavaScript-Methoden auszuführen, kann die Funktion main() definiert werden, die dann aufgerufen wird.

Folgendes Beispiel passt eine Schweizer Telefonnummer an das internationale Format an:

<Mapping> <Map Target="Phone"> <Map.SourceExpression> function main() { // normalisiert alle Telefonnummern // 0715110500 => +41 71 511 05 00 // +41 71 511 05 00 => +41 71 511 05 00 var input = source('phonenumber').replace(/ /g, ''); var patt = /((\+|00)41|0)([0-9]+)/; var matchArray = patt.exec(input); var number = matchArray[3]; return "+41 " + number.substring(0,2) + " " + number.substring(2,5) + " " + number.substring(5,7)+ " " + number.substring(7,9); } </Map.SourceExpression> </Map> </Mapping>

StartsWith-Funktion

Häufig möchte man bei Mappings überprüfen, ob ein Text mit gewissen Zeichen beginnt, also z. B. ob der Text in "ZIP_Code" (Postleitzahl) mit "CH-" beginnt.

Leider gibt es die JavaScript-startsWith-Funktion in ES5 noch nicht.
Der Ausdruck source('ZIP_Code').startsWith('CH-') kann somit nicht (!) ausgewertet werden.

Funktionierende Alternative:

source('ZIP_Code').indexOf('CH-') === 0

Hinweise

  • In JavaScript werden Bedingungen auf einen truthy-Wert überprüft. Das heisst, es können auch nicht-boolesche (wahre oder falsche) Werte ausgewertet werden. So werden positive Zahlen oder nicht leere Zeichenketten auch als wahr ausgewertet.

  • Mit JavaScript kann zwischen null und undefined unterschieden werden. Zu beachten ist z. B., dass wenn ein Wert nicht verfügbar ist die Source-Eigenschaft vom Map-Element null liefert während das source-API-Objekt undefined liefert.

  • Vergleiche: Der == Operator kann auch verwendet werden, um verschiedene Datentypen zu vergleichen, z. B. wird '55' == 55 als wahr ausgewertet. Praktischer Tipp: da undefined == null auch als wahr ausgewertet wird, kann mittels source('Name') == null sowohl auf leere (null) als auch auf nicht verfügbare (undefined) Werte überprüft werden. Mehr zum Vergleichen mit JavaScript finden Sie hier.

Mapping-Datenquelle

Je nach Datenquelle ist der Zugriff auf die Daten anders, d. h. wie der Quellwert im Source-Attribut oder im JavaScript der source()-Funktion übergeben wird. Es gibt folgende Quellen:

Standard: Schlüssel/Wert

Es werden einfache Schlüssel angegeben – es existiert eine direkte Zuordnung. Beispiele:

  • Spaltenname für den SQL Address Provider

  • Spaltenname oder Spaltennummer für CSV/XLSX Address Provider

XML

Bei XML-Quellen kann ein XPath (1.0) angegeben werden, um den Wert zu identifizieren.

Dabei werden folgende Rückgaben gemacht:

Resultat des XPath

Zurückgegebener Wert

Resultat des XPath

Zurückgegebener Wert

Attribut

Wert des Attributs

Element

Inhalt/Wert des Elements

Text

Der Text

CData

Ist das Resultat in CData gewrappt, wird dieses ohne das CData-Tag zurückgegeben.

Beispiel

XML-Quelldatei

<Kontakt> <Company>PrimeSoft AG</Company> <Adresse> <PLZ>8360</PLZ> <City>Eschlikon</City> <Street>Bahnhofstrasse 4</Street> </Adresse> <Contact> <Option Type="Phone">+41 71 511 0 500</Option> <Option Type="Mail">info@primesoft-group.com</Option> </Contact> </Kontakt>

Mapping

<Mapping Type="XML"> <Map Source="//PLZ" Target="Postleitzahl" /> <Map Source="/Kontakt/Adresse/City" Target="Stadt" /> <Map Source="//Street" Target="Strasse" /> <Map Target="KompletteAdresse"> <Map.SourceExpression> source('//Company') + '\r\n' + source('//Street') + '\r\n' + source('//PLZ') + ' ' + source('//City') </Map.SourceExpression> </Map> <Map Source="//Contact/Option[@Type='Phone']" Target="Telefon" /> </Mapping>

Resultat

Postleitzahl: 8360 Stadt: Eschlikon Strasse: Bahnhofstrasse 4 KompletteAdresse: PrimeSoft AG Bahnhofstrasse 4 8360 Eschlikon Telefon: +41 71 511 0 500

Beispiele

If-Else

In der aktuellen Version gibt es keinen Else-Abschnitt. Für grössere Abschnitte kann die Bedingung negiert werden:

<Mapping> <If Condition="source('Typ') === 'Geschäftlich'"> <!-- Map Elemente für Firmenadresse--> </If> <If Condition="!(source('Typ') === 'Geschäftlich')"> <!-- Map Elemente für Else-Fall--> </If> </Mapping>

Um einen Wert aus verfügbaren Elementen auszuwählen, können mehrere Map-Elemente mit dem gleichen Target verwendet werden:

<Mapping> <Map Source="Privat" Target="Phone" /> <Map Source="Büro" Target="Phone" When="target('Phone') != null" /> <Map Source="Mobile" Target="Phone" When="target('Phone') != null" /> </Mapping>

Beachten Sie die Reihenfolge: Die Map-Elemente werden der Reihenfolge nach ausgewertet, d. h., dass die letzte vorhandene Nummer verwendet wird.

Alternativ kann eine JavaScript-Expression benutzt werden:

<Mapping> <Map Target="Phone"> <Map.SourceExpression> function main() { if (source('Mobile') != null) { return source('Mobile'); } else if (source('Büro') != null) { return source('Mobile'); } else { return source('Privat'); } } </Map.SourceExpression> </Map> </Mapping>

 

PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland