Mapping
With this standardized format, mappings can be configured consistently throughout primedocs.
Examples:
<Mapping>
<Map Source="fname" Target="First name" />
<Map SourceValue="Jane" Target="Firstname" />
<Map SourceValue="Doe" Target="LastName" When="source('test') === 'someValue'" />
<Map SourceExpression="25*78" Target="Calculator" When="target('LastName') === 'Doe'" />
<Map>
<Map.Source>fname</Map.Source>
<Map.Target>First name</Map.Target>
</Map>
<Map>
<Map.SourceValue>Jane</Map.SourceValue>
<Map.Target>Firstname</Map.Target>
</Map>
<Map>
<Map.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
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="AttributeContent">
further element content
</Elementname>
As element:
<Elementname>
<Elementname.Attributename>AttributeContent</Elementname.Attributename>
further element content
</Elementname>
For the If
element with Condition
property, the following two configurations have exactly the same meaning:
Map element
A map element represents a single mapping operation. Exactly one source property and the target must be set.
Property | Description |
---|---|
Source |
If the value is not found, |
SourceValue | A constant value to be used. |
SourceExpression | A primedocs 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 primedocs JavaScript expression that allows the mapping to be executed conditionally. |
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 &
:
Alternatively, the same can be done using CDATA
and element notation:
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:
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:
The result is as follows:
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:
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:
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
andundefined
. Note, that e.g., if a value is not available thesource
property of themap
element returnsnull
while thesource
API object returnsundefined
.Comparisons: The
==
operator can also be used to compare different data types, e.g.'55' == 55
evaluates to true. Practical tip: sinceundefined == 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 |
---|---|
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
Mapping
Result
Examples
If-Else
In the current version there is no Else section. For larger sections the condition can be negated:
To select a value from available elements, multiple map elements with the same target can be used:
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:
Â
PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland