Inbound Mapping

Last modified 17 Oct 2024 16:10 +02:00

Table of Contents

Introduction
Input
Associations
Range Of Inbound Mappings
Limitations
See Also

Introduction

Inbound mapping is a mapping that transforms data from a projection (e.g. an account) on the resource side to a focal object (e.g. a user) on the midPoint side. Therefore it maps data in the direction which points into midPoint. Hence inbound mapping. Inbound mappings are usually used to copy and transform data from authoritative sources to midPoint. E.g. inbound mappings are often used to populate new user object with data from HR system.

Please see the Synchronization page for a generic description of the synchronization process and the specific place where inbound mappings are used.

Input

Value constructions are sometimes used in situations where an input of the construction is quite obvious. In such cases the input is placed into a variable named input for easier use. This is common practice e.g. in inbound expressions or in expressions describing synchronization of account activation and password.

Expression constructor using input variable

<script>
  <code>'The Mighty Pirate ' + input</code>
</script>

Associations

Inbound mappings for associations are described in a separate document.

Range Of Inbound Mappings

Inbound mappings have their range - as all the mappings have. Range is a set of possible values that a mapping can produce. This is an important tool to control which values are to be replaced by the mapping - or better to say, which values should be replaced. See Mappings page for the details.

The default range of inbound mappings depend on the target item:

Mapping target is Default range Which means …

Mapping target is	Default range	Which means …
single-value	`all`	The target value will be replaced. This is nice and intuitive behavior for single-value items. This is also known as non-tolerant behavior.
multi-value	`none` for unnamed mappings	Target values will not be replaced. This is safe behavior for multi-value items as the chance to delete something is lower. This is also consistent with other mappings, where the default range is empty. This is mostly intuitive for many multi-valued items, such as assignments - even though it may not be a natural fit everywhere. But it is consistent behavior, therefore it was chosen as a default. This is also known as tolerant behavior.
`matchingProvenance` for named mappings	Only the target values that were previously provided by this mapping are replaced by it.

single-value

all

The target value will be replaced. This is nice and intuitive behavior for single-value items. This is also known as non-tolerant behavior.

multi-value

none for unnamed mappings

Target values will not be replaced. This is safe behavior for multi-value items as the chance to delete something is lower. This is also consistent with other mappings, where the default range is empty. This is mostly intuitive for many multi-valued items, such as assignments - even though it may not be a natural fit everywhere. But it is consistent behavior, therefore it was chosen as a default.

This is also known as tolerant behavior.

matchingProvenance for named mappings

Only the target values that were previously provided by this mapping are replaced by it.

The default behavior can be overridden by explicit definition of mapping range, as you can see on a following example.

<inbound>
    ... sources, expression, etc.
    <target>
        <path>organization</path>
        <set>
            <predefined>all</predefined>
        </set>
    </target>
</inbound>

See Mapping Range page for a detailed discussion of mapping ranges.

Motivation

The concept of range is not needed that often in other mappings. But it makes a lot of issues in inbound mappings. The reason for that is that inbound mappings are somehow different. They are not completely relativistic.

Typical midPoint mapping is working with a deltas. The mapping knows what was changed and the mapping takes a full advantage of that. Therefore it will normally not change the things that should not be changed. Therefore the definition of mapping range is not that important in such case. However, in inbound mappings we do not usually have a delta. We just have the state of the resource object (e.g. account) as it is now. We do not know what was changed. Therefore we have to recompute all the values. But the real difficulty here is to know which values to remove. E.g. if mapping target is an assignment, how do we know which assignments are given by this mapping and which are assigned automatically? The mapping should remove those that are given by the mapping, but it should not touch other assignments. This is exactly what range definition does.

Fortunately, provenance-based range definition, which is the default for multi-valued targets and named mappings, provides a good solution here.

Limitations

When an account is deleted, or unlinked from the user, the inbound mappings are not executed. (An exception is an explicit and direct deletion of an account requested by the user.) This means that the values provided by the mapping previously are not removed when the account is gone. This is going to be resolved in the future.