You are viewing the documentation for Blueriq 14. Documentation for other versions is available in our documentation directory.

What is it for?

Data mappings are used to facilitate the exchange of data between modules with (potentially) differing domain models

A data mapping is used in case of the next situations:

  • Between a Process module and an Implementation module data has to be exchanged, for example to determine which tasks should be executed;
  • Between an - for example generated while importing a WSDL - Implementation module and another Implementation module, to create the input and read from output of the webservice.

When using mappings there are several different types of mappings possible. In this chapter we’ll take a look at the different types. Let’s presume we have these source and target models:

Source model

Target model

In this article

See also

How to model a data mapping

Step 1: Create

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:

Step 2: Match

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.

For example you want to map Person entities that have age >18. You can set 'Person' receives input from 'ALL Person'. You select Apply When and set expression Person.Age > 18.

Be careful though, the Instance handling screen (the last screen in the configure dialog) is still applied, also when the Apply When condition is FALSE. If you do not want to delete instances in the target module, you should set If the source has not matching "X" to Do nothing.

There is a difference between using (1) the Apply When condition and (2) using a COLLECT expression when selecting instances. For (1) all instances are mapped, and the instance handling settings apply to all instances. For (2) the instance handling settings only apply for the instances selected with the expression.

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

Step 3: Configure

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.

Step 4: Relations

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.

Step 5: Instance handling

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.
You can specify match conditions to check if there is a matching instance. By default, the setting is Match automatically using the instance's identifier. Each instance has a GUID that identifies it. By using this setting, the runtime checks whether an instance of that entity with the same GUID already exists in the target module, and if so that instance matches and is used for the mapping. When using Specify match conditions an own matching rule can be created that compares values from the source instance to values from the target instance. A good example is if a person exists with the same Social Security Number.

One-on-One mapping

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.

One-on-One instance mapping

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

One-on-One Value mapping

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

One-on-One Relation mapping

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.

Splitting Instances

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.

Splitting Values

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.

Joining Instances

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

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.

Mapping Justification Trees for attribute values 

Beside mapping the value of an attribute, it is also possible to map the justification tree which is attached to the source attribute. Mapping of the justification tree can be configured as follows : 

Click the "tree" button next to the expression editor for configuring the entity , attribute , depth and asset format of the justification tree : 


When the data mapping is executed, the value of the Justification Tree will be attached to the mapped attribute. 

6 Comments

  1. Can someone shed some light on when these mappings are activated?

    For instance when you have a mapping between an - for example generated while importing a WSDL - Implementation module and another Implementation module, to create the input and read from output of the webservice?
    You can fill in a mapping in the AQ_WebServiceClient, but will this instantly map the attributes or will it recieve the message in the SOAP service module first and then kick the mapping?

    There is no service for activating a mapping on demand?

    1. Unknown User (m.schadd)

      There is no service for executing a mapping on demand at the moment. It is always part of another action, such as sending a message to a webservice. When sending a message, the profile of the current module is first transformed using the datamapping to the profile of the other module. Then it is translated to a message. When receiving a message, it is first translated to the profile of the 'foreign' module, and then the datamapping is executed towards the own module.

      There are also other places in which a datamapping is used, such as between process module and implementation module.

  2. In the instance handling step, there is an automatic match functionality. It states: Match automatically using the instance's identifier.
    What does this mean? What is the instance's identifier when no match conditions are specified?

    1. Unknown User (m.schadd)

      I have added documentation to clarify this.

  3. Unknown User (g.jacobs)

    Are conditions on values evaluated in a lazy manner from top to bottom?

    In other words: if I set the first condition to 'booleanX'='true' and the second condition to 'TRUE', the second one functions as a default/else in case the first one does not match?