- SAP Managed Tags
In this blog post, I'd like to discuss a rather special topic for Integration Advisor (as part of SAP Integration Suite). This blog post might be of interest to you if you use our Base/Overlay Mappings and have previously defined duplicate target nodes in your Overlay Mapping Guideline (MAG). In such a case it might be required to check if the mapping still works as expected.
Target Node Duplicates in Overlay MAGs
Our Base/Overlay mapping is a very powerful feature that allows you to define many business-partner specific MAGs (overlay) based on a common template MAG (base). For more details on the general concept see this blog post (Link)
With our release 2601 (from March 2026) we have improved the handling of duplicate target nodes in Base and Overlay MAGs. Originally, target node duplicates from the Base MAG weren’t visible in the Overlay MAG. While you could duplicate target nodes in the Overlay MAG, they weren’t linked with existing duplicates in the Base MAG and could therefore lead to conflicts.
Now, target node duplicates from the Base MAG are visible in the Overlay MAG. The target node duplicates defined in an Overlay MAG are also explicitly stored as overlay duplicates to allow side-by-side duplicates from Base MAG and Overlay MAG.
Migration of previously defined duplicate target nodes in Overlay MAG
With release 2601, all Overlay MAGs with previously defined duplicates are migrated once you access them. The finished migration is indicated by a warning icon in the Status column in the MAG editor for the relevant nodes.
In most cases, the previous mapping is still valid, but in some edge cases, the mapping behavior can have changed. Therefore, it’s advised that you check if your mapping still produces the same mapping output as before.
When designing the migration strategy, we strived for two goals: the migration rules shall be straight-forward and intuitive & the mapping behavior shall remain as before for the majority of situations.
If you have previously (before March 2026) defined duplicate target nodes in your Overlay MAG, then the new feature together with the automatic migration has the following effects:
Duplicate target nodes from the Base MAG are now visible in the Overlay MAG.
Base mapping elements pointing to the base duplicate nodes are now valid in the Overlay MAG and can be used.
If you previously disabled such base mapping elements because they were invalid, they remain disabled. But you can now enable them again and use them in future.
Earlier defined duplicate target nodes from Overlay MAGs are automatically migrated to become the new overlay duplicates.
Earlier defined overlay mapping elements by default now point to the overlay duplicates.
Uncritical Mapping Situations
In the majority of situations, the mappings runtime behavior will be the same as before the migration. This includes the following situations:
- All cases where you have disabled the base mapping elements associated with a base duplicate (see Example 1 below).
- Situation where you have defined overlay duplicates unrelated to base duplicates (see Example 2 below).
- All mappings where you defined overlay duplicates as replacement for the non-visible base duplicates and implemented the required mappings as overlay mappings with the base mappings disabled (see Example 3 below).
- Special situation where you defined overlay duplicates such that the base mappings "accidentally" remained valid AND where you have reused the base mappings as-is (see Example 4a below) or maybe added overlay mappings only to additional overlay duplicates (see Example 4b below).
In the appendix we have collected many mapping examples to explain these situations in more detail.
Critical Mapping Situations
There are, however, a few corner cases where the mappings runtime behavior might change due to the new feature and the migration. This includes these situations:
- You have defined the overlay duplicates in such a way that the base mappings "accidentally" remained valid AND you mixed base elements and overlay elements in a way that they pointed to the same duplicate target node group (see Example 5 below).
- You started an Overlay MAG but have not finished it because the base mapping elements related to the base duplicates were invalid (because the base duplicates were unknown in the Overlay MAG). As a result, the Overlay MAG might now be valid.
- Such mappings couldn't be used in the runtime because the Overlay MAG was invalid. Therefore we don't discuss this case in more detail.
If you have a situation like the one in Example 5, you need to fix the mapping before using it in the runtime.
When will this change be applied?
The change takes effect once you open the previously defined Overlay MAG in MAG Editor. You will now see the base duplicate target nodes and can make use of them in Simulation.
This change has no immediate effect on your productively running scenarios in Cloud Integration.
However, if you update your runtime scenario by either Exporting Runtime Artifacts into your Integration Flow or by activating your TPM agreement, then the new behavior will be applied.
Conclusion
This blog post explains some details of our new feature to use base duplicates nodes in Overlay MAGs and which consequences this has for previously defined overlay duplicates. It is advised that you check and retest your Overlay MAGs if you have previously defined overlay duplicates, particularly in case of the critical situation explained above. Afterwards, enjoy the new feature!
Further reading
Appendix with Mapping Examples
Example: Base Mapping
Let us first have a look at the following Base MAG:
The source message (on the left side) distinguishes between two different types of Address (Delivery Address and Invoice Address) - this is modeled using the powerful Qualification concept in Message Implementation Guideline (MIG) editor.
The target structure (on the right side) has originally only one Address node. We need to duplicate the Address node in order to map both source address variants into the target structure. In the target structure you can see the duplicates Address [1] and Address [2] (depicted by blue box in screenshot). Moreover, the source node Address[DLVY] and its child nodes are mapped to target node Address [1] and its child nodes. Similarly, the source node Address[INVC] is mapped to target node Address [2]. (In our example, we have only mapped to the duplicates of Address but it would have also been possible to map to the original node Address itself.)
All later Overlay MAG examples will be based on this Base MAG.
Overlay Example 1: Disable Mapping Elements for Base Duplicate Nodes
Our first example covers the following business use case: The business partner for this Overlay MAG does not need the Address nodes at all. Therefore, all according mapping elements shall be disabled in the Overlay MAG.
On the left hand of the next screenshot you see the situation as it has been before our feature extension (before the migration):
- Base Node Duplicates for Address were not visible in Overlay MAG.
- All Base Mapping Elements for both Address subtrees were invalid (because the Base Node Duplicates were unknown).
- The user has disabled these Base Mapping Elements because they are invalid and anyway not needed for this Overlay MAG. In the lower part of the left hand (of next screenshot) you see the 5 invalid mapping elements as part of the "Excluded Base Mappings".
- The Overlay MAG is valid and can be executed (because the invalid base mapping were disabled).
On the right hand of the screenshot you see the situation as it will be after our feature extension (after the migration):
- Base Node Duplicates for Address are now visible in the Overlay MAG (depicted by blue box in screenshot).
- There are no active mapping elements for these Address duplicates because they were previously disabled.
- These 5 disabled Base Mapping Elements can still be found as part of the "Excluded Base Mappings" - see lower part of the right hand. (Please note that these disabled base mappings are now valid because the base duplicates nodes are now known in the Overlay MAG.)
- The mapping result of the Overlay MAG is identical to the situation before the migration.
If at a later time the base mapping elements for Address were needed for this Overlay MAG, the user could easily enable them to become active again.
Overlay Example 2: Overlay Duplicate Nodes Unrelated to Base Node Duplicates
In our second example we look at the following business use case: The business partner for this Overlay MAG has a special requirement for Name for which the Name node needs to be duplicated in the Overlay MAG. Please note that the Name node is completely independent from the Address node duplicated in the Base MAG (Name and Address are sibling nodes). And for simplicity let us assume this Overlay MAG does also not need the Address nodes at all (same as in previous Overlay Example 1).
On the left hand of the next screenshot you see the situation as it has been before our feature extension (before the migration):
- The user has created a duplicate node Name [1] in the Overlay MAG (depicted by green box in screenshot).
- The base mapping element towards the original node Name is kept in the Overlay. Moreover, the user has defined an Overlay mapping element towards the duplicate Name [1] node.
- The handling of Address node is same as in Example 1: Base Node Duplicates for Address were not visible in Overlay MAG and all Base Mapping Elements for Address were disabled.
- The Overlay MAG is valid and can be executed (because the invalid base mapping were disabled).
On the right hand of the screenshot you see the situation as it will be after our feature extension (after the migration):
- Nothing changes for the overlay-specific duplication of Name (because this duplication is completely independent from the base node duplication of Address 😞 The overlay duplicate node Name [1] is shown (depicted by green box in screenshot) and the overlay mapping element towards Name [1] remains as-is.
- And the handling of Address node is again the same as in Example 1: Base Node Duplicates for Address are now visible in Overlay MAG and all Base Mapping Elements for Address are valid but stay disabled.
- The mapping result of the Overlay MAG is identical to the situation before the migration.
Overlay Example 3: Copy Base Node Duplicates
The next examples will become more interesting as they cover situations where the Address node was duplicated in the Overlay MAG too. In our third example we look at the following business use case: The business partner for this Overlay MAG needs the Address subtrees and has no special requirements for them, that is, the same mapping as in the Base MAG shall be applied. As discussed in the beginning, this situation was unfortunately not covered before our feature extension: the base duplicate nodes were not visible in the Overlay MAG and the related base mapping elements were invalid (compare also Example 1 above).
Users could overcome this limitation by simply creating a copy of the base node duplicate in the Overlay MAG and by creating overlay-specific copies of the missing base mapping elements. We assume that this is the most frequent situation why overlay node duplicates have been defined.
On the left hand of the next screenshot you see the situation as it has been before our feature extension (before the migration):
- The handling of the base node duplicates for Address node is same as in Example 1: base node duplicates for Address were not visible in Overlay MAG and all Base Mapping Elements for Address needed to be disabled.
- As a replacement for the missing base node duplicates, the user defined an overlay duplication rule to have the duplicate nodes Address [1] and Address [2] (depicted by green box in screenshot).
- Additionally the user defined overlay mapping elements for the overlay duplicate nodes as a replacement for the missing base mapping elements.
- The Overlay MAG is valid and can be executed (because the invalid base mapping were disabled). The mapping result is the same as it would have been with the base mapping elements.
On the right hand of the screenshot you see the situation as it will be after our feature extension (after the migration):
- Base Node Duplicates for Address are now visible in the Overlay MAG (depicted by blue box in screenshot).
- There are no active mapping elements for these base node duplicates because they were previously disabled. Note that, as before, these 5 disabled Base Mapping Elements are visible in the list of "Excluded Base Mappings" and are now valid mapping elements (see lower part of the right hand of screenshot).
- Previously defined overlay node duplicates for Address continue to be visible in the Overlay MAG (depicted by green box in screenshot). Here you can nicely see how the duplication rules from Base MAG and Overlay MAG are merged and shown side-by-side.
- Please note that MAG Editor dynamically gives numbers to the duplicates - therefore the overlay duplicates are now depicted as Address [3] and Address [4]. But this is a UI-specific display with no consequences for the runtime.
- Moreover, the overlay-specific mapping elements remain valid and continue to point to the overlay node duplicates of Address.
- The mapping result of the Overlay MAG is identical to the situation before the migration. (Please note in this context that no payload node instances for the base node duplicates are created because there are no active mapping elements.)
As we have seen, the mapping works as before and therefore there is no need for immediate action. However, it would be recommended to remove the overlay copies and return to the base mappings (as the intention of this use case is to reuse the base mappings as-is):
- Enable the previously disabled base mapping elements. After done so, they should point to the base duplicate nodes Address [1] and Address [2] .
- Delete all overlay mapping elements pointing to the overlay duplicate nodes (Address [3] and Address [4]).
- Delete the overlay-specific duplication rule for the Address node.
After having done so, the mapping of the Address subtrees should look the same as in the Base MAG (as would be expected).
Overlay Example 4a: "Re-create" Base Node Duplicates and Reuse Base Mappings
The business use case of our fourth example is the same as in Example 3: The business partner for this Overlay MAG needs the Address subtrees without any special requirements, that is, the same mapping as in the Base MAG shall be applied.
As before, the user created node duplicates for Address in the Overlay MAG. But in this very specific example, the overlay duplicates were defined in a way that the base mappings became "accidentally" valid. (This situation could happen if the node duplicates in Overlay MAG were defined in exactly the same order as the node duplicates in the Base MAG and as result would have the same internal identifier.)
On the left hand of the next screenshot you see the situation as it has been before our feature extension (before the migration):
- Base node duplicates for Address were not visible in Overlay MAG.
- As a replacement for the missing base node duplicates, the user defined an overlay duplication rule to have the duplicate nodes Address [1] and Address [2] (depicted by green box in screenshot).
- For this special situation, the Base Mapping Elements remained valid and were automatically connected with the newly defined overlay duplicate nodes for Address.
- In the screenshot you can see this by the blue icon color of mapping elements and by the fact that the list of "Excluded Base Mappings" is empty.
- There was no need to define overlay mapping elements as replacement because base mapping elements worked out-of-the-box.
- The Overlay MAG is valid and can be executed (nothing needed to be disabled). The mapping result is the same as in Base MAG because the base mapping elements can be directly reused.
On the right hand of the screenshot you see the situation as it will be after our feature extension (after the migration):
- Base Node Duplicates for Address are now visible in the Overlay MAG (depicted by blue box in screenshot).
- Previously defined overlay node duplicates for Address continue to be visible (as Address [3] and Address [4]) in the Overlay MAG (depicted by green box in screenshot).
- Base Mapping Elements now point to the base node duplicates (Address [1] and Address [2]) according to our migration strategy (see general migration rules above).
- There are no mapping elements pointing to the overlay node duplicates (Address [3] and Address [4]) because there were no overlay-specific mapping elements defined.
- The mapping result of the Overlay MAG is identical to the situation before the migration.
Again, the mapping works as before and there is no need for immediate action. If desired, you could delete the overlay-specific duplication rule for the Address node because it is no longer required. But this is a mere cosmetic change without any influence on the mapping itself.
Overlay Example 4b: Extend "Re-created" Base Node Duplicates
Our next business use case is an extension of the one in Example 4a: The business partner for this Overlay MAG needs the Address subtrees without any special requirements and additionally needs a third Address instance in its payload.
In this case the user created 3 node duplicates for Address in the Overlay MAG in the special way that the first 2 duplicates are "recognized" by the base mapping elements.
On the left hand of the next screenshot you see the situation as it has been before our feature extension (before the migration):
- Base node duplicates for Address were not visible in Overlay MAG.
- The user defined an overlay duplication rule to have 3 duplicate nodes of Address (depicted by green box in screenshot). Here Address [1] and Address [2] serve again as replacement for the missing base node duplicates and Address [3] is the overlay-specific extension.
- As in Example 4a, the Base Mapping Elements remained valid and were automatically connected with the newly defined overlay duplicate nodes Address [1] and Address [2].
- Additionally the user defined two overlay-specific mapping elements for Address [3].
- In this example, the Overlay MAG produces three payload instances for the Address node.
On the right hand of the screenshot you see the situation as it will be after our feature extension (after the migration):
- Base Node Duplicates for Address are now visible in the Overlay MAG (depicted by blue box in screenshot).
- Base Mapping Elements now point to the base node duplicates (shown as Address [1] and Address [2]) according to our migration strategy.
- Previously defined overlay node duplicates for Address continue to be visible (now shown as Address [3] and Address [4] and Address [5]) in the Overlay MAG (depicted by green box in screenshot).
- The two overlay-specific mapping elements continue to point to the third overlay duplicate (now depicted as Address [5] on UI).
- The mapping result of the Overlay MAG is identical to the situation before the migration.
Once more, the mapping works as before and there is no need for immediate action. If desired, one could delete the two unused overlay-specific duplications (cosmetic change).
(Problematic) Overlay Example 5: Modify Mappings for "Re-created" Base Node Duplicates
Our last example shows a corner case situation which is indeed problematic and might produce a different / unwanted mapping result.
The business use case for this example is an extension of the one in Example 4a: The business partner for this Overlay MAG needs the Address subtrees, however, requires some modifications to the base mapping elements / duplicates.
In this case the user created 2 node duplicates for Address in the Overlay MAG in the special way that these 2 duplicates are "recognized" by the base mapping elements (as in Example 4a).
On the left hand of the next screenshot you see the situation as it has been before our feature extension (before the migration):
- Base node duplicates for Address were not visible in Overlay MAG.
- The user defined an overlay duplication rule to have 2 duplicate nodes of Address (depicted by green box in screenshot). Here Address [1] and Address [2] serve again as replacement for the missing base node duplicates.
- As in Example 4a, the Base Mapping Elements remained valid and were automatically connected with the newly defined overlay duplicate nodes Address [1] and Address [2].
- For the first duplicate Address [1], the user kept the base mapping element for AddressTypeCode unchanged, added a new overlay-specific mapping element for CountryCode (unmapped before) and modified the mapping element for City (overlay-specific copy of the base mapping).
- The special situation of this example is that "reused" base mapping elements and overlay mapping elements are connected to the same duplicates.
On the right hand of the screenshot you see the situation as it will be after our feature extension (after the migration):
- Base Node Duplicates for Address are now visible in the Overlay MAG (depicted by blue box in screenshot).
- Base Mapping Elements (like the one for node AddressTypeCode) now point to the base node duplicates (shown as Address [1] and Address [2]) according to our migration strategy.
- Previously defined overlay node duplicates for Address continue to be visible (now shown as Address [3] and Address [4] ) in the Overlay MAG (depicted by green box in screenshot).
- The two overlay-specific mapping elements (for nodes City and CountryCode) still point to the first overlay duplicate (now depicted as Address [3] on UI).
- As a result, the base mapping elements (like for node AddressTypeCode) and the overlay mapping elements (for nodes City and CountryCode) point to different duplicates of Address. Therefore, the mapping result of the Overlay MAG is NOT identical to the situation before the migration.
The difference in the mapping behavior can also be observed when using the simulation (see next screenshot):
- On the left side you see the Overlay MAG before the migration: the first duplicate node Address [1] has the expected child nodes AddressTypeCode, City and CountryCode.
- In difference to this, the right side depicts the situation after the migration: now two separate instances of Address are created - the first address has the child node AddressTypeCode, while the other address (shown as Address [3]) has the child nodes City and CountryCode.
In such a case, you need to fix your Overlay MAG to make the mapping run again as expected:
- Create new overlay-specific mapping elements for the target nodes City and CountryCode of the base duplicate node Address [1].
- Delete the previously defined overlay-specific mapping elements for the target nodes City and CountryCode of the overlay duplicate node Address [3].
Via this approach, the base mapping for AddressTypeCode and the overlay mappings for City and CountryCode will again work nicely together.
Bluesky| User | Count |
|---|---|
| 34 | |
| 9 | |
| 9 | |
| 5 | |
| 5 | |
| 4 | |
| 4 | |
| 4 | |
| 3 | |
| 3 |
