Data mapping

Create a new data mapping in the Configuration module and specify which modules you want to map:

It is possible to let Blueriq generate an auto-mapping. See Generate Auto-mapping on how to do this and what this functionality entails.

Then configure the source domain model and target model:

Click on the pencil behind an entity in the target domain model to specify an instance mapping:

When specifying an instance mapping you have the following options:

• 'Apply': if you choose for “When”, you can specify an expression in terms of the source domain model that serves as a precondition for carrying out this' instance mapping:

• 'Receives input from': enter an expression in terms of the source domain model that results in a set of instances, where for each instance a new instance in the target domain model has to be created.
  • Beware that you cannot refer to an active instance in the source collection that for example has just been activated in a flow before running the data mapping. So, either singletons or collections can be mapped.
• 'Define additional contexts': when the target entity receives data from multiple entities (instances) in the source domain model, then additional contexts are used to specify these multiple instances.

Please note that any syntactically correct expression is allowed, but this expression must yield a unique instance in practice. Later on you can use this 'additional context' in the 'value / relation mappings.

Next, the 'Or' option defines a second instance mapping with the same functionality. Each of the instance mappings creates an instance of the entity in the target domain model. You can actually rather read it as 'And'..

When clicking on 'Configure' an input screen appears where you can specify how the attributes on an instance in the target domain model takes its values from the source.

When specifying a value mapping, you can specify expressions that provide the data for the attribute in the target domain model. The expressions must be formulated from one of the following contexts:

• 'Receives input from' entity;
• 'Additional context' entity;
• A singleton entity.

The expression must of course produce a value of the same type as the target attribute in the domain model. Optionally data conversion functions can be used (such as INTEGER (entity.attribute)). Also static value may be entered. By using preconditions, you can specify different values based for an attribute.

If, after specifying the “value mappings', 'Next' is pressed, an input for specifying the 'relation mappings' appears:

The expression must yield a set of instances in the source domain model, which are then created in the target model and put into the relationship. Also here preconditions can be used to be create relations based on different conditions.

Finally, specify what should happen if :

• there is no instance in the target domain model yet representing the instance of the source model;
• there is already an instance in the target domain model to represent the source instance;
• there are instances in the target model for which there are no matching instances in the source model.

The simplest and most direct is the one-on-one mapping. One instance, value or relation maps directly to a single instance, value or relation in the other domain.

In the mapping editor the first screen is simple. There is just one mapping which always applies.

As with instances, one-on-one mappings also occur between values. Most value mappings will be one-on-one, simply passing on the values without conditions or lengthy expressions. E.g.:

Relations can also be mapped. Given the nature of relations it is unlikely that they will be split or joined but conditions can be placed if relations are not always applicable.

With more complex domain models it is possible that instances do not match one-on-one. In some cases it might be needed to split an instance into different instances, should that be required in the domain model. In our example that happens between the Address in the source domain. In the target domain there are different entities for addresses in different countries, instead of the single Address. In the domain it will look like:

To achieve the split in instances two separate mappings are made. The first from Address to ForeignAddress, the second from Address to NLAddress. Because our model also uses the StrAddress to hold the street name and house number of Address, another split is made.

To split the instances a condition is set at which point the mapping is only used when the condition is met. The next two images show how the addresses are split.

To complete the split between Address and NLAddress a third mapping is created, connecting with StrAddress. The condition here is twofold, the first is to find the correct instances, the second to prevent the creation of empty instances in case of missing information.

As with instances, values can also be split. In order to do this one can use expressions instead of referring simply to a value. These expressions can be as complex as needed and can be used to transform the values, e.g. change the type of the value.

By using conditions it is also possible to set values. In such a case the value of the expression field for which the condition is true is used. In the following example the condition is “Address.country = ‘ES’” for the 34 value and “Address.country = ‘IT’” for the 39 value. Like this it is possible to translate different notations between domains.

The opposite of splitting instances is joining them. This means there are multiple instances that are combined to form a single instance.

Here there is only one mapping with two input entities, as the triggering instance will be used to determine which of the mapping. Note that the additional context to NLAddress is a link between the NLAddress and the related StrAddress. If this is not added then the mapping will use the active instances of NLAddress and StrAddress, which might not belong together.

Joining values can be done by using an expression. With the formula ribbon available during typing, any expression can be used as long as the type of the receiving attribute is respected. E.g. the value of Address.ZIP is concatenated from NLAddress.ZIPNumerals and NLAddress.ZIPCharacters. Concatenate results in a string so no additional typing is needed.