Mappings

Mappings are relativistic in several ways. Mappings will react to changes in source values, triggering re-evaluation of mappings as needed. In the above example, the mapping will be re-evaluated if either of the sources change (givenName or familyName), or in case that full recompute is requested (e.g. in case of full reconciliation). In case that neither of the sources have changed there is no need to re-evaluate that mapping.

However, midPoint assumes that re-evaluation of mapping is usually cheap, assuming we have all the input data ready. Therefore, midPoint may re-evaluate the mapping even in case that neither of the sources have changed, as it helps to make sure that the data are still consistent.

Smart reaction to changes is one of the reasons for requiring explicit definition of sources in the mappings. Without such definitions it is not (realistically) possible to reliably determine how and when the expression should be re-evaluated.

The sources themselves are delta-aware. The source does not specify the value only, it also specifies previous value, and the way how the value changed (delta). This allows mapping to be smart, re-computing only some values. Even more importantly, source deltas are taken into consideration when mapping is evaluated. Therefore, mapping can figure out how target value have changed, and apply the changes in a smart way (see Mapping Relativity).

Mappings can have several sources, each of the sources can have many values. All the values of all the sources are taken into consideration when a mapping is evaluated.

Mapping sources are specified using item path, which may be quite long and complex. Yet, almost all the scripting languages require simple strings to denote variables, parameters and inputs. Therefore, each source has assigned a simple name. The name is derived from the last segment of item path of the source. Hence a source with path of $focus/activation/administrativeStatus will be accessible as administrativeStatus in the scripts. The two sources in the above example are passed to the expression as a variables with names givenName and familyName respectively.

Automatic derivation of source name usually works well. However, there is administrativeStatus in $focus/activation/administrativeStatus, but also on $focus/assignment/activation/administrativeStatus. If both of them are used as two sources of one mapping, one of them has to be renamed.

For that purpose, source definition has one additional element: a name. The name element explicitly specifies the name that the source will take when used as an expression variable:

This source will be accessible under the name lastName in the mapping expression.

In some cases, the primary input to an expression is accessible under name input. This approach is applied in cases when there is only a single source for a mapping (by definition), such as inbound mappings applied to a single attribute. Similar approach is applied to stand-alone expression, where there is no obvious name for expression input.

The domain of a mapping (in a mathematical sense) is a set of values that are valid inputs of the mapping. The mapping will operate only on the values that belong to its domain. Other values will be ignored. By default, the mapping has unlimited domain: all possible values are processed by the mapping. The mapping domain can be specified by using a set declaration in its source:

The above mapping will only operate on input values that starts with AUTO-. Other values will be ignored by the mapping.

The domain definition is a very practical mechanism if there are several mappings that work on the same source and/or target, each of the mappings using a different expression. In this case mapping domains can be set in such a way that they do not overlap, making sure only one of the mapping is processing any particular value. Domain is also useful if we want to provide output values only for some input values. This cannot be easily achieved by using mapping condition, as the condition will activate or deactivate entire mapping, it applies to all the values processed by a mapping. The condition does not work for individual values.

The domain is very useful especially for automatic assignment expressions in object template.

The range of a mapping (in a mathematical sense) is a set of values that are considered to be valid outputs of the mapping. Definition of mapping range is not important for evaluation of mapping expression. However, it is important for application of mapping outputs.

The mapping is considered to be authoritative for all values in its range. If the target item contains values that belong to the mapping range, it is assumed that the values were created by the mapping. I.e. if the mapping contains any values that belong to the mapping range, and the mapping does not produce such values as its output, the values are removed.

The range defines what are the possible outputs of the mapping. The projector can use this information to determine what values to remove when the mapping is authoritative.

The range definition does not influence mapping inputs or expression. The range is used when the mapping outputs are processed.

Default range (if no explicit range is specified) are only values emitted by this mapping (as identified by provenance metadata).

Please see Mapping Range for detailed explanation of mapping range concepts.

Constraints limit the use of a mapping only to certain situations. In a situation specified by the constraint the mapping is applied as usual. In other situations the mapping will be ignored, the system will pretend that the mapping is not there.

Channel constraint limits application of a mapping to a specific channel. If the evaluation is done in the context of that channel, the mapping will be applied. If the channel is different, the system will ignore the mapping. This constraint is usually used in inbound mappings to limit them to the import channel and therefore use them only for initial import.

There are two items that control the channel constraint:

The presence of a time constraint limits the applicability of a mapping to a specific time. There are two time constraints: timeFrom and timeTo. These limits the applicability of the mapping to a specified time interval. If the current time is in the interval, the mapping will be applied normally. If the time is outside the interval then the mapping will not be applied.

The mapping below will be applied only in time interval that starts 10 day after the disableTimestamp and ends 3 months after disableTimestamp.

The time constraint has two parts:

Any combination of timeFrom and timeTo can be present in a mapping (none of them, any of them, both of them).

The mapping time constraint are slightly more that just mapping evaluation constraints. The presence of a time constraint does not only limit the evaluation of a mapping, it also makes sure that the mapping will be re-evaluated at the right time. MidPoint is using a system of triggers to make sure the mappings for re-evaluation are located quickly and efficiently. Therefore, it is much better to use a time constraint instead of simple mapping condition.

Mapping condition is a mechanism for easy implementation of mappings that provide conditional values. This means a value that is present when certain condition is true, while it is not present if the condition is false. The idea is that mapping expression provides the value, while the condition controls when the value is applied and when it is not. The condition can be used to set conditional property values, automatically assign roles and so on.

For example a condition may be used in the mapping to apply the mapping only if the input value is non-empty:

The processing of a condition fully supports the relative change model. Therefore, midPoint considers changes in condition (true-to-false or false-to-true), and will reflect that in a mapping result. E.g. if a value is generated by a mapping that used to have true condition, but the condition changed to false, midPoint will remove such value. Therefore, such conditional mapping is an ideal mechanism to automatically add and remove target values.

The mapping above adds the assignment when hrJobCode is 1234 and removes the assignment when the code is changed or removed. This is a very useful behavior, implemented by a simple condition. On the other hand, conditions can be quite subtle, and there are often misunderstandings as to the working of conditions and their purpose.

Please see Mapping Condition page for more details on mapping conditions.

Authoritative flag controls the way how mapping is used to remove values. It does not influence adding of values. If mapping is authoritative then it will add value and also remove the value. If mapping is not authoritative it will only add the value.

Non-authoritative mappings are used if there are several possible sources for a particular value. E.g. the value may be added by the mapping and also added directly on the resource by system administrator. In this case midPoint cannot remove the value when the assignment (or role) containing the mapping is removed because the value might have been added manually. Other settings, such as tolerance may apply on attribute level.

The default value for authoritative flag is true.

Enabled flag specifies if the mapping is evaluated or not. Each specified mapping is by default evaluated. To skip mapping evaluation, enabled flag has to be set to false.

Default value is true.

Lifecycle state of the mapping. Can be used to disable a mapping or during simulations.

Default value is active.

Check Object Lifecycle for details.

Exclusive mapping may be applied only as a single mapping for a particular target property. If an exclusive mapping is applied together with any other mapping it results in an error.

The default value for exclusive flag is false.

It is possible to define several mappings that affect single attribute. For example, one mapping can be defined as inbound mapping in schemaHandling of specific resource and another one can be defined separately in object template. In similar cases, mappings are evaluated in this order:

inbound mappings ⇒ objectTemplate ⇒ activation ⇒ assignments + roles + outbound mappings ⇒ reconciliation

Which mappings will be applied to specific parameter during mapping evaluation can be easily modified using mapping strength options and mapping conditions.

The mapping mechanism is designed to be easy to use both for single-value properties and multi-value properties as sources. The single-value case is quite straightforward: the (single) value is passed to mapping as an input. If there is no value then null is passed. The mapping is supposed to produce (single) value. That value is stored to target item. If no value or null is produced, then it is assumed that the target should have no value. That is all simple and easy.

However, it all gets much more complex when multiple values are used. Luckily, most of the complexity is hidden inside midPoint. The mappings are deliberately designed in such a way that the mapping expression will be invoked for each input value individually. Therefore, if the input has three values, then the expression will be invoked three times: once for each input value. The expression is supposed to produce output value - or even more than one output value. All the output values are collected together. The collection of output values will be applied to the mapping target.

Therefore, mapping expression still works with single-value input and output - even in the case of multi-value properties. MidPoint will execute the expression as many times as needed, and process each individual value. The responsibility of the expression is simply to transform one specific value at a time.

One-to-one value mapping is the usual case both in single-value and multi-value cases. One input value usually translates to one output value. No input value usually translates to no output value. That are the usual cases. However, midPoint mappings can also handle the unusual cases:

This is all easy to do when expression is evaluated separately for each input value.

However, there is one special case when multiple values have to be transformed to single value or a different number of values. The usual evaluate-per-input-value approach will not work here. The absolute evaluation mode can be used in this case. The absolute evaluation mode means that that list of all values is passed to the expression as input. In this case the expression is supposed to produce a list of all output values.

Evaluation of each value separately is a very convenient from a configuration and customization point of view. However, there is even a much deeper reason for this approach. Evaluation of each value individually supports midPoint’s relativity principle. This is best explained using an example. Let’s have a mapping that transforms all input values to upper case:

Let’s assume that both invar and outvar are multi-valued. This is the case when the relativity mechanism is most interesting.

It is all very simple when a new object is created (we have add). Everything is new at that point, we know complete state of all the objects and everything is simple. Therefore, if the input is [ a, b, c ], then the output will be [ A, B, C ].

The things get more interesting when the object is modified (we have modify). Let us suppose that value c is removed from the input and values d and e are added to the input. The mapping still transforms all the values individually. Therefore the expression will be invoked five times: for both the old and new values. However, when the expressions are evaluated, midPoint remembers whether the input value was added, removed or whether it stayed the same. MidPoint then applies the same operation to the value which is the output of an expression. Therefore:

This may seem obvious when we know complete state of all objects, and we are absolutely sure about it. Unfortunately, that is not always the case. MidPoint often works with resources that do not support transactions or any kind of locking. Therefore, what we know for sure is what has been changed (delta). However, we are not that sure about the values that are present in target resource when we are about to apply the change (which may be several days later, due to approval process). The good news is that this algorithm works also in these cases. What the algorithm does is that it transforms the input delta of [-c, +d, +e] to output delta [-C, +D, +E]. This output delta can be applied even to a changed target value. Let’s suppose that there was a change on the target and the target value is now [X, B, C] instead of [A, B, C]. Yet, when the [-C, +D, +E] is applied to the [X, B, C] value, we still get the correct result of [X, B, D, E].

Sometimes there is a multi-value property with a large number of values that are changed quite often and where change happens by several asynchronous semi-independent channels. You may think that a situation like this does not happen very often. But it does. In identity management we have a lot of properties that behave exactly like this: groups, privileges, projects, tags, …​

Again, the description above mostly applies to script expressions. Expressions such as asIs have natural way how to deal with deltas and no value-by-value transformation is needed. But again, non-script expressions such as assignmentTargetSearch will follow the same relativity principle: the search will get executed even for the removed valued so midPoint will know which assignment has to be removed.

Please see Mapping Relativity page for more details.

The short answer is: because of relativity. The long answer is indeed quite long, and it is perhaps best explained using an example. Let’s have the same mapping as above that transforms lowercase characters to uppercase. Now consider a situation when invar was changed from a to b. Simple thinking would suggest that we need to execute the expression for the input of b, which will give us B and that’s it. But in the language of relativity a change from a to b actually means: remove value a and add value b. We can denote that as delta [ -a, +b ]. Therefore, the expression is invoked twice. First invocation transforms value a, so we know that we have to remove A from the output. Second invocation transforms value b, so we know that we have to add value B to output. The result is delta [ -A, +B ]. This mechanism is designed to work well with multi-value properties (see above), and it often can be optimized for single-value properties. Some of these optimizations are already implemented in midPoint, some are not (please consider a subscription to make those optimizations complete). Therefore, midPoint may sometimes evaluate a value just to discard it moments later. Anyway, the final result should be correct in any case.

Relativity is the reason for multiple execution of expressions, which is perhaps not that difficult to understand. What often comes as a surprise is that mapping conditions are executed several times too. There is also a good reason for that, and it is also based in relativity. Once again it is best to explain using an example. Let us complicate our mapping a bit by adding a condition:

Now, the mapping is not supposed to produce any value if property gate does not have value open. Simple thinking would suggest that midPoint will evaluate the condition once, and if the result is false then the mapping is ignored. That would not work well in all cases. E.g. if this is an outbound mapping to a tolerant resource attribute. During the previous operation the inputs were invar=[ b, c ], gate=open and the target property already contained value [ A ]. After that operation, the target property has values [ A, B, C ]. Now, what happens if we change gate from open to closed? If the mapping would be simply ignored then nothing would change on the resource. The mapping would behave as if it is not there, therefore there is no output, therefore there is no output delta. As the target property is tolerant, that would meant that nothing is removed. However, that is not what we want. The gate is closed. The target should not have the values B and C, should it?

Fortunately, midPoint is smarter than that. As everything in the midPoint, even mapping conditions are relativistic. MidPoint knows that the value of gate changed from open to closed. Therefore, midPoint executes the condition twice. The condition is executed once for the old value of the gate variable which results in true value. Then the condition is executed for new value of gate variable, which results in false value. Therefore, midPoint knows that the condition has just changed from true to false. Which means that any values that the expression produces are in fact to be removed from the target. In case that the value of invar is still [ b, c ], the output of the mapping is delta [ -B, -C ]. Once that delta is applied to the target property value [ A, B, C ] the result is correct value [ A ].

Thanks to the relativity mapping conditions can be used to conditionally add values, but they work equally well for removing values. This may seem overly complicated at the first sight. Yet, it has enormous benefits. For example, this approach allows easy automatic assignment of roles in object template. In that case the role assignment is the expression, and the condition tells when the role should be assigned. When that condition becomes false then the role is unassigned. No special mechanism was needed to implement this. It is all given by the relativistic behavior of mappings.

Please see Mapping Relativity page for a detailed explanation of the relativity mechanism.

In fact, this description is a bit simplified. The real complexity is unleashed when there is a change in both source variables. So now we have two deltas on the input side of the mapping that are supposed to produce single output delta. Now imagine that there may be any number of input variables and that midPoint does not really know which of them are used in expression or condition. We will not confuse the reader with a detailed explanation of the algorithm, and we will refer extremely curious readers to midPoint source code. The source code is the most precise documentation anyway.

Sometimes, a mapping may need to be renamed, e.g., when the original name no longer reflects the nature of the mapping. Or, when a new naming schema for mappings is introduced.

Normally, all that needs to be done is simply changing the name of the mapping. However, if the (default) mapping range based on the provenance metadata is used, we must be more careful, because the mapping name is used to "mark" the values provided by the mapping in their provenance metadata. The renamed mapping would no longer recognize values it created in the past as its own, resulting in keeping them untouched, even in situations when they need to be removed.

So, if the mapping was in real use, and if there are (or may be) values produced by it, an extra action is required. A mapping can be instructed to recognize values produced by its original name by specifying mappingAlias property, containing mapping’s original name or names.

The mapping alias will make sure, that also old values will be visible in range for the renamed mapping.

The approach described above applies when only the mapping name changes.

However, there are other situations when an analogous action has to be taken:

The reason is that all this information, along with the mapping name, is present in the provenance metadata for mapping output values:

If the only changed item is the mapping name, the mappingAlias described above can be used to deal with the different provenance metadata. For all other configuration changes (object, object type, association type), the original mapping specification or specifications have to be provided in the target/set/additionalMappingSpecification item. For example, let’s assume that the above mentioned mapping was moved to a different resource, or that the object type intent was renamed from default to person, and/or that the association type was renamed from userDocumentAccess to documentAccess. The original metadata need to be specified as additionalMappingSpecification in the mapping, like this: