Mapping

---

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
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
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 & 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
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

JSON

Bei JSON-Quellen kann ein JSONPath angegeben werden, um den Wert zu identifizieren.

Beispiel

JSON-Quelldatei

{
  "Kontakt": {
    "Company": "PrimeSoft AG",
    "Adresse": {
      "PLZ": "8360",
      "City": "Eschlikon",
      "Street": "Bahnhofstrasse 4"
    }
  }
}

Mapping

<Mapping Type="JSON">
  <Map Source="$.Kontakt.Adresse.PLZ" Target="Postleitzahl" />
  <Map Source="$.Kontakt.Adresse.City" Target="Stadt" />
  <Map Source="$.Kontakt.Adresse.Street" Target="Strasse" />
</Mapping>

Resultat

Postleitzahl:       8360
Stadt:              Eschlikon
Strasse:            Bahnhofstrasse 4

---

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>