1 JavaScript
2 Eigenschaften als Elemente oder Attribute
3 Map-Element
4 If-Element
5 Bedingungen & Ausdrücke
- 5.1 Escaping
- 5.2 Source
- 5.3 Target
- 5.4 Main-Funktion
- 5.5 StartsWith-Funktion
- 5.6 Hinweise
6 Mapping-Datenquelle
- 6.1 Standard: Schlüssel/Wert
- 6.2 XML
7 Beispiele
- 7.1 If-Else

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:

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 & geschrieben werden:

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

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:

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:

Das ergibt folgendes Resultat:

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:

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:

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

Mapping

Resultat

Beispiele

If-Else

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

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

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: