Table of Contents

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

...

BeispieleWith this standardized format, mappings can be configured consistently throughout primedocs.

Examples:

Code Block

language	xml

<Mapping>
  <Map Source="fname" Target="FornameFirst name" />
  <Map SourceValue="HansJane" Target="FornameFirstname" />
  <Map SourceValue="MusterDoe" Target="LastName" When="source('test') === 'someValue'" />
  <Map SourceExpression="25*78" Target="Calculator" When="target('LastName') === 'MusterDoe'" />

  <Map>
    <Map.Source>fname</Map.Source>
    <Map.Target>Forname<Target>First name</Map.Target>
  </Map>
  <Map>
    <Map.SourceValue>Hans<SourceValue>Jane</Map.SourceValue>
    <Map.Target>Forname<Target>Firstname</Map.Target>
  </Map>
  <Map>
    <Map.SourceValue>Muster<SourceValue>Doe</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 AttributYou can make a mapping with simple declarative statements or map a more complex logic via JavaScript. You can find a more detailed introduction on the JavaScript page.

...

Properties as elements or attributes

All of the following element properties can be set both as an attribute and as an element according to the following pattern.

As attribute:

Code Block

language	js

<Elementname Attributname="AttributinhaltAttributeContent">
  further weitererelement Elementinhaltcontent
</Elementname>

Als ElementAs element:

Code Block

language	js

<Elementname>
  <Elementname.Attributname>Attributinhalt<Attributename>AttributeContent</Elementname.Attributname>Attributename>
    weitererfurther element Elementinhaltcontent
</Elementname>

Beim If-Element mit Condition-Eigenschaft haben die folgenden beiden Konfigurationen genau dieselbe BedeutungFor the If element with Condition property, the following two configurations have exactly the same meaning:

Code Block

language	js

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

Code Block

language	js

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

...

Map

...

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

...

Eigenschaft

...

Beschreibung

...

Source

...

element

A map element represents a single mapping operation. Exactly one source property and the target must be set.

Property	Description
Source	In the default case: the name identifying the value, e.g. the column name of the database in the Generic SQL Provider. Bei For XML -Datenquelledata source: siehe see XML Wenn der Wert nicht gefunden wird, wird `null` weitergegebenIf the value is not found,`null`is passed.
SourceValueEin	konstante Wert, der verwendet werden sollA constant value to be used.
SourceExpression	Eine A primedocs -JavaScript-Expression, die ausgewertet wirdJavaScript expression that is evaluated.
TargetDie Zieleigenschaft für das Mapping. Die möglichen Zielfelder bei AddressProvidern sind unter Standard-Kontakt-Mapping dokumentiert	The target property for the mapping. The possible target fields in Address providers are documented in Standard contact mapping.
WhenEine	A 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

...

JavaScript expression that allows the mapping to be executed conditionally.
If the value evaluates to true, the mapping is executed.

...

If element

The If element allows the definition of conditions for whole blocks of mappings. If blocks can be combined and nested in any way.

Property	Description
Condition	JavaScript condition – result is checked for truthy value.

...

Conditions & Expressions

Escaping

In XML, certain characters like & or < have a special designation. Therefore, these cannot be used directly. Mask them: & can be written as &:

Code Block

language	xml

<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 werdenAlternatively, the same can be done using CDATA and element notation:

Code Block

language	xml

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

...

Source

Mittels Using the 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 API object, the source values can be accessed from JavaScript analogously to the source property of the map element. If the value is not available, undefined is returned. The following example takes the last available phone number:

Code Block

language	xml

<Mapping>
  <Map Source="ArbeitsplatzWorkplace" Target="Phone" When="source('ArbeitsplatzWorkplace') != 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 werdenFor compatibility, the source API object can also be accessed using oo or OO.

...

Target

Mittels Using the 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 API object, previously mapped values can be accessed from the JavaScript. If the value is not available, undefined is returned. The following example assembles an address:

Code Block

language	xml

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

Das ergibt folgendes ResultatThe result is as follows:

Code Block

language	none

Source
----------
street              TeststrasseTest hausnrstreet
houseNr             42
ZipPlace PLZUndOrt           4242424242 TesthausenTestburg

ResultatResult
----------
Street              Test Teststrassestreet 42
CompleteAddress     TeststrasseTest street 42
                    4242424242 TesthausenTestburg

...

Main

...

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

...

function

To execute more complex JavaScript methods, the function main() can be defined and then called.

The following example adapts a Swiss phone number to the international format:

Code Block

language	js

<Mapping>
  <Map Target="Phone">
    <Map.SourceExpression>
      function main()
      {
        // normalisiertnormalizes all allephone Telefonnummernnumbers
        // 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

...

function

Often in mappings you want to check if a text starts with certain characters, e.g. if the text in "ZIP_Code" (Postleitzahlpostal code) mit starts with "CH-" beginnt.

Leider gibt es die JavaScript-startsWith-Funktion in ES5 noch nicht.
Der Ausdruck Unfortunately, the JavaScript startsWith function does not yet exist in ES5.
The expression source('ZIP_Code').startsWith('CH-') kann somit nicht can thus not (!) ausgewertet werden be evaluated.

Funktionierende AlternativeWorking alternative:

Code Block

language	js

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

...

Notes

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 , conditions are checked for a truthy value. This means that non-boolean (true or false) values can also be evaluated. For example, positive numbers or non-empty strings are also evaluated as true.
JavaScript can distinguish between null and undefined. Note, that e.g., if a value is not available the source property of the map element returns null while the source API object returns undefined.
Comparisons: The == operator can also be used to compare different data types, e.g. '55' == 55 evaluates to true. Practical tip: since undefined == null also evaluates to true, source('name') == null can be used to check for both empty (null) and unavailable (undefined) values. For more on comparing with JavaScript, see here.

...

Mapping data source

Depending on the data source, the access to the data is different, i.e. how the source value is passed in the source attribute or in the JavaScript of the source() function. There are the following sources:

Default: key/value

Simple keys are specified – a direct mapping exists. Examples:

Column name for SQL Address provider
Column name or column number for CSV/XLSX Address Provider

XML

Bei XML-Quellen kann ein For XML sources, an 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:can be specified to identify the value.

The following returns are made:

Result of XPath	Returned value
Attribut	Value of the attribute
Element	Content/value of the element
Text	The text
CData	If the result is wrapped in CData, it will be returned without the CData tag.

Example

XML source file

Code Block

language	xml

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

Mapping:

Code Block

language	xml

<Mapping Type="XML">
  <Map Source="//PLZZip" Target="PostleitzahlZip" />
  <Map Source="/KontaktContact/AdresseAddress/City" Target="StadtCity" />
  <Map Source="//Street" Target="StrasseStreet" />
  <Map Target="KompletteAdresseCompleteAdresse">
    <Map.SourceExpression>
      source('//Company') + '\r\n' + source('//Street') + '\r\n' + source('//PLZ') + ' ' + source('//City')
    </Map.SourceExpression>
  </Map>
  <Map Source="//Contact/Option[@Type='Phone']" Target="TelefonPhone" />
</Mapping>

Resultat:Result

Postleitzahl:

Code Block

language	none

Zip:               8360
StadtCity:              Eschlikon
StrasseStreet:            Bahnhofstrasse 4
KompletteAdresseCompleteAdresse:   PrimeSoft AG
                    Bahnhofstrasse 4
                    8360 Eschlikon
TelefonPhone:             +41 71 511 0 500

...

Examples

If-Else

In der aktuellen Version gibt es keinen Else-Abschnitt. Für grössere Abschnitte kann die Bedingung negiert werdenthe current version there is no Else section. For larger sections the condition can be negated:

Code Block

language	xml

<Mapping>
  <If Condition="source('Typ') === 'GeschäftlichBusiness'">
    <!-- Map elements Elementefor Company füraddress Firmenadresse-->
  </If>
  <If Condition="!(source('Typ') === 'GeschäftlichBusiness')">
    <!-- MapMapMap Elementeelements fürfor Else case -Fall-->
  </If>
</Mapping>

Um einen Wert aus verfügbaren Elementen auszuwählen, können mehrere Map-Elemente mit dem gleichen Target verwendet werdenTo select a value from available elements, multiple map elements with the same target can be used:

Code Block

language	xml

<Mapping>
  <Map Source="PrivatPrivate" Target="Phone" />
  <Map Source="BüroOffice" 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 werdenNote the order: the map elements are evaluated in order, i.e. the last number present is used.

Alternatively, a JavaScript expression can be used:

Code Block

language	js

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

...

Versions Compared

Old Version 1

New Version Current

Key

JavaScript

Eigenschaften als Elemente oder Attribute

Properties as elements or attributes

Map

element

If-Element

Bedingungen & Ausdrücke

Escaping

If element

Conditions & Expressions

Escaping

Source

Target

Main

function

StartsWith

function

Notes

Mapping-Datenquelle

Standard: Schlüssel/Wert

Mapping data source

Default: key/value

XML

Examples

If-Else

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

JavaScript

Eigenschaften als Elemente oder Attribute

Properties as elements or attributes

Map

element

If-Element

Bedingungen & Ausdrücke

Escaping

If element

Conditions & Expressions

Escaping

Source

Target

Main

function

StartsWith

function

Notes

Mapping-Datenquelle

Standard: Schlüssel/Wert

Mapping data source

Default: key/value

XML

Examples

If-Else