Inhalt anzeigen / ausblenden

    Mapping

    With this standardized format, mappings can be configured consistently throughout OneOffixx.

    Examples:

    <Mapping>
      <Map Source="fname" Target="Forname" />
      <Map SourceValue="Hans" 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>Forname</Map.Target>
      </Map>
      <Map>
        <Map.SourceValue>Hans</Map.SourceValue>
        <Map.Target>Forname</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

    You 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:

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

    As element:

    <Elementname>
      <Elementname.Attributname>Attribute content</Elementname.Attributname>
      further element contemt
    </Elementname>
    

    For the If element with Condition property, the following two configurations have exactly the same meaning:

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

    Map 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.
    • For XML data source: see XML
    If the value is not found, null is passed.
    SourceValue A constant value to be used.
    SourceExpression A OneOffixx JavaScript expression that is evaluated.
    Target The target property for the mapping. The possible target fields in Address providers are documented in Standard contact mapping.
    When A OneOffixx 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 &amp;:

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

    Alternatively, the same can be done using CDATA and element notation:

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

    Source

    Using the source 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:

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

    For compatibility, the source API object can also be accessed using oo or OO.

    Target

    Using the target 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:

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

    The result is as follows:

    Source
    ----------
    street              Test street
    houseNr             42
    ZipPlace            424242 Testburg
    
    Result
    ----------
    Street              Test street 42
    CompleteAddress     Test street 42
                        424242 Testburg
    

    Main 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:

    <Mapping>
      <Map Target="Phone">
        <Map.SourceExpression>
          function main()
          {
            // normalizes all phone numbers
            // 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" (postal code) starts with "CH-".

    Unfortunately, the JavaScript startsWith function does not yet exist in ES5.
    The expression source('ZIP_Code').startsWith('CH-') can thus not (!) be evaluated.

    Working alternative:

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

    Notes

    • In JavaScript, 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

    For XML sources, an XPath (1.0) can be specified to identify the value.

    The following returns are made:

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

    Example:

    XML source file:

    <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="/Contact/Address/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
    

    Examples

    If-Else

    In the current version there is no Else section. For larger sections the condition can be negated:

    <Mapping>
      <If Condition="source('Typ') === 'Business'">
        <!-- Map elements for Company address -->
      </If>
      <If Condition="!(source('Typ') === 'Business')">
        <!-- Map elements for Else case -->
      </If>
    </Mapping>
    

    To select a value from available elements, multiple map elements with the same target can be used:

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

    Note the order: the map elements are evaluated in order, i.e. the last number present is used.

    Alternatively, a JavaScript expression can be used:

    <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>
    
    Back to top | Deutsch | English PrimeSoft AG   I   Bahnhofstrasse 4   I   8360 Eschlikon   I   Switzerland   I   Privacy   I   Legal notice