Add expressions to a mapping
Learn how to extend a mapping with logic by using expressions
Now that we have created a basic mapping in the previous tutorial, we'll explore how to use expressions to model business logic.
Start from the prepared workspace
You do not have to have done the previous tutorial. Clone the starting point straight from
the welcome page: Tutorials & Examples → tutorials → mapping → with-expression.
It already contains the mapping built in Mapping Fundamentals.
To see the finished result instead, clone examples → mapping → with-expression. See
Getting the workspace for a tutorial.
Create a simple expression
We'll use the mapping from the previous tutorial and extend it with an expression on the name field. Open the mapping canvas and notice that we have created two mappings on the Name field of the target Customer entity.
Starting from the prepared workspace
The prepared workspace maps ID and DateOfBirth but leaves Name unmapped. Before you go on, select Create Mapping in the toolbox and draw FirstName to Name and LastName to Name, so the canvas looks like the one below. An expression can only reference the source attributes that are mapped to its target, so without these two lines the next steps have nothing to work with.
Now make sure the toolbox action Select is active and click on the Name field in the target Customer entity. Now open the properties panel on the right (tip: you can close the explorer panel on the left to keep more room for the mapping canvas).
Expand the expression panel and type the following expression. Notice that when you type {{ you can select any of the source attributes that are mapped to the target attribute.
CONCAT_WS(' ',{{CustomerSourceObject.FirstName}},{{CustomerSourceObject.LastName}})
Use the name your source object has
CrossModel names a source object after its entity: drop JuiceERP's Customer on a mapping and
it becomes CustomerSourceObject, which is what the expression above uses. The prepared
workspace was written by hand and calls it CustomerSource, so if you cloned it, write
{{CustomerSource.FirstName}} and {{CustomerSource.LastName}}. You do not have to
remember which: type {{ and pick from the list, which only offers names that exist.
Note :
when referencing source attributes in an expression, make sure to enclose them in double brackets so CrossModel can evaluate them properly.
Notice that both input fields are set under sources in the property panel. Also notice that in the mapping canvas, target attributes that are mapped with an expression are marked with fx
Qualify the attribute with the object it belongs to
As of v1.16.0 every expression references an attribute as Object.Attribute, and the
object depends on where the expression sits:
| The expression is on | Write | Not |
|---|---|---|
| A source object | {{DebtorSource.Credit_limit}} |
{{Credit_limit}} |
| The mapping | {{CustomerSource.EmailAddress}} |
{{EmailAddress}} |
| The target object | {{Customer.Email}} |
{{Email}} |
An unqualified attribute is accepted by the editor and then reported in Problems, so the
expression looks finished until you notice the count in the corner. A target expression can
also only reference attributes that something maps into: {{Customer.Country}} is rejected
while nothing fills Country.
Reading an expression
An expression that is already in the model shows each referenced attribute as a chip rather than as raw text, so you can see at a glance which attributes it draws on. This one is from the multi-source mapping of the next tutorial:
The expression you just typed may stay as text
As of v1.19.4, an expression you have just typed keeps showing as plain text, even after
you save and select the attribute again. Nothing is wrong with it: the fx on the target
attribute shows it was saved, and an expression that was already in the file shows its chips.
A few details worth knowing about the expression editor:
- Chips are clipped from the left, not the right, so the part you actually need - the attribute name after the dot - always stays visible even in a narrow properties panel. Hover a chip to see the full qualified name.
- The ⊗ on a chip removes that reference from the expression.
- Typing
{{opens the suggestion list of source attributes mapped to this target attribute. The list is positioned to stay on screen, so it is not clipped when the panel is narrow or the editor sits inside a dialog. - The Sources grid above lists every attribute the expression uses. It updates as you edit the expression, so it is a quick way to check that the expression references what you intended.
Filtering rows with an expression
The expression above decides what a single target attribute contains. Since v1.13.0 a mapping can also carry an expression that decides which rows it produces at all: a filter.
There are two of them, and where you put one says when it is applied.
| Expression on | What it filters | What {{ offers |
|---|---|---|
| The mapping | The rows coming out of the sources, before anything is written | Every attribute of every source object, qualified with its source: CustomerSource.Country |
| The target | The rows about to be written to the target entity | The target entity's own attributes |
To reach the mapping's own filter, open the mapping and switch to the Form Editor. Between
Sources and Target there is now an Expression section. Type {{ in it and the
source attributes are offered:
So a mapping that should only load Dutch customers gets:
{{CustomerSource.Country}} = 'NL'
The target's own filter sits on the target object. Press Edit Target on the mapping form and the target opens in a dialog with its attribute mappings and its own Expression section:
Both are checked as you write them: a reference to an attribute that does not exist is reported in the Problems view rather than silently generating something that will fail later.
The property panel now shows the mapping itself
Click empty canvas on a mapping diagram and the Properties panel shows the mapping's own form - its id, sources, filter expression and target - instead of the placeholder it used to show (v1.13.0). It is the quickest way to read or set a filter without leaving the canvas. The panel header also names what you selected, for example CustomerSource (Source Object), where every selection used to read as the mapping.
CrossModel does not run your expression
A filter expression is passed through to code generation exactly as you wrote it, in the dialect your templates target. CrossModel checks the attribute references, not the SQL.
In the next tutorial we'll see how to add multiple source objects to a mapping, making it possible to model mappings that contain integration logic.





