Mapping

Mit diesem standardisierten Format lassen sich Mappings durch primedocs hindurch einheitlich konfigurieren — z. B. um Quellfelder einer Datenquelle auf primedocs-Zielfelder abzubilden.

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.

Eigenschaften als Elemente oder Attribute

Alle nachfolgenden Element-Eigenschaften können 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 beiden folgenden Konfigurationen 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-Datenquellen siehe XML. Wird der Wert nicht gefunden, wird null weitergegeben.
SourceValue	Ein konstanter Wert, der verwendet werden soll.
SourceExpression	Eine primedocs-JavaScript-Expression, die ausgewertet wird.
Target	Die Zieleigenschaft für das Mapping.
When	Eine primedocs-JavaScript-Expression, die das Mapping bedingt ausführt. Wird sie auf wahr ausgewertet, 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 — das Resultat wird auf einen truthy-Wert geprüft.

Bedingungen & Ausdrücke

Escaping

In XML haben gewisse Zeichen wie & oder < eine besondere Bedeutung und können nicht direkt verwendet werden. Maskieren Sie diese, z. B. & als &:

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

Alternativ lässt sich dasselbe mit CDATA und Element-Schreibweise erreichen:

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

Ergebnis:

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 prüfen, ob ein Text mit gewissen Zeichen beginnt — z. B. ob der Text in ZIP_Code (Postleitzahl) mit CH- beginnt.

Die JavaScript-Funktion startsWith gibt es 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 geprüft. Auch nicht-boolesche Werte werden ausgewertet: positive Zahlen oder nicht leere Zeichenketten gelten als wahr.
• Mit JavaScript kann zwischen null und undefined unterschieden werden. Ist ein Wert nicht verfügbar, liefert die Source-Eigenschaft des Map-Elements null, während das source-API-Objekt undefined liefert.
• Vergleiche: Der ==-Operator vergleicht auch unterschiedliche Datentypen, z. B. wird '55' == 55 als wahr ausgewertet. Da undefined == null ebenfalls wahr ist, kann mittels source('Name') == null sowohl auf leere (null) als auch auf nicht verfügbare (undefined) Werte geprüft werden.

Mapping-Datenquelle

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

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 den CSV-/XLSX-Address-Provider

XML

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

Resultat des XPath	Zurückgegebener Wert
Attribut	Wert des Attributs
Element	Inhalt/Wert des Elements
Text	Der Text
CData	In CData gewrappte Resultate werden 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>

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>

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 den Else-Fall -->
  </If>
</Mapping>

Um einen Wert aus mehreren verfügbaren Elementen auszuwählen, können mehrere Map-Elemente mit demselben 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>

hinweis

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