Skip to content

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.

mapping-with-attribute-mappings

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

attribute-mapping-detauls

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.

attribute-mapping-with-expression

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:

An attribute mapping with its sources and a chip-based expression

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:

The mapping's Expression section with the suggestion list open

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:

The target object's 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.