The Art of Mapping: Navigating SAP’s Base-Overlay Framework

In SAP Integration Suite’s Integration Advisor, a Mapping Guideline (MAG) defines how data is transformed between two message formats — a key step in achieving seamless SAP mapping and data integration. The Base-Overlay MAG framework introduces a smarter way to manage variations across multiple business partners using similar message formats. Instead of duplicating mappings for each partner, this approach allows you to maintain one Base MAG for shared structures while using Overlay MAGs to handle partner-specific differences such as date formats or item descriptions.

A Base MAG serves as the foundation, containing the mapping elements common to most partners, while each Overlay MAG references this base and inherits all elements by default. Within the Overlay, inherited mappings can be adjusted — deleted, edited, or extended — to meet unique partner requirements. This structure ensures efficiency, consistency, and flexibility in complex SAP integration landscapes, reducing maintenance effort and enabling scalable data transformation across your ecosystem.

Requirements

For the Base Mapping, you will need a source and target MIG (example below: MIG 1 and MIG 2).  For the Overlay Mapping(s), you will need a new MIG based on the content of the trading partner data (example below: MIG 3).

For this example, the Base Mapping consists of a source UN/EDIFACT D96A ORDERS message and a target IDoc ORDERS.ORDERS05 message. The Overlay Mappings will be the different source UN/EDIFACT D96A ORDERS messages from other trading partners (note that the same Base source MIG and Base target MIG can also be used for other trading partners). [MIG 1]

MIG 1 is based on the ex. UN/EDIFACT D96A ORDERS message (this is the Source MIG in the Base MAG  and can be selected as the Source MIG in the Overlay MAGs):

[MIG 2]

MIG 2 is based on the ex. IDOC ORDERS.ORDERS05 message (this is the Target MIG in the Base MAG and will be selected as the Target MIG in all Overlay MAGs):

[MIG 3]

 MIG 3 is based on the UN/EDIFACT D96A ORDERS message for ex. Trading Partner # 2 (as the different source MIG):

Creating the Base MAG

Go to the MAG Overview (via Design -> MAGs) and create a Standard MAG with your Source MIG 1 and Target MIG 2.

Give it a recognizable name, as this will be the Base MAG for all Overlay MAGs:

In Edit mode, add the basic mapping elements to your MAG (that will be used in other Overlay MAGs):

Save the Base MAG and simulate it with the test payload to see if the mapping is executed correctly.  Activate when complete. Creating a 1st Overlay MAG (Trading Partner #1)

Go back to the MAG Overview (via Design  MAGs) and create an Overlay MAG for Trading Partner #1:

In the 1st step of the Overlay Creation Wizard, select the Base MAG created in the previous steps (with MIG 1 and MIG 2):

In the next 2 steps, select the Source MIG and Target MIG (for Trading Partner # 1, we will use the Source MIG 1 and Target MIG 2 from the Base MAG). This will be the new MAG for Trading Partner # 1.

It will contain the mappings inherited from the Base MAG:

Now, suppose Trading Partner # 1 doesn't have the additional product Id (/Interchange/ORDERS/SG25/PIA[7143 = IN]) in his files. Thus, it will not be mapped in the target IDOC. Let’s say you want to remove this segment in your mapping.

In the Overlay MAG, switch to Edit mode, look for the corresponding element in the mapping list table, and exclude (i.e. remove) it from the Overlay MAG (in the Mapping List below via the ‘X’ or via the mapping line via right-click):

Save the Overlay MAG and simulate it with the test payload to see if the mapping is executed correctly.  Activate when complete.

After creating the Agreement with this Overlay MAG, you can do additional testing over the iFlows.

Creating a 2nd Overlay MAG (Trading Partner #2)

For Trading Partner # 2, the Source MIG (MIG 3) is a little different, since they send the NAD+ST instead of the NAD+DP for the delivery party.

You could still use MIG 1 and MIG 2 and map this different NAD segment as long as you qualify another partner segment “for the remaining values” in the Source and Target MIGs, however, for this example, I will create a new Source MIG.

The creation of the Overlay MAG is nearly the same like the first one – the Base MAG and the Target MIG (MIG 2) are selected - the only difference is that we need to select our different Source MIG (MIG 3) in the MAG Creation Wizard via Compatible MIG:

This will be the new MAG for Trading Partner # 2.

The other steps will remain the same. Again, the mapping elements of the Base MAG are automatically added to the Overlay MAG, but with 1 exception: This D96A ORDERS message doesn’t contain NAD+DP, but NAD+ST. Because the Base Mapping is expecting the NAD+DP, and the corresponding mapping elements are thus not valid for this overlay MAG, there will be an error initially:

To fix this error, we will Edit, and exclude (i.e. remove) the mapping with the error (in the Mapping List below via the ‘X’ or via the mapping line via right-click) and add a new mapping element NAD+ST to the Overlay MAG from the source MIG (MIG 3):

Save the Overlay MAG and simulate it with the test payload to see if the mapping is executed correctly.  Activate when complete.

After creating the Agreement with this Overlay MAG, you can do additional testing over the iFlows. Creating a 3rd Overlay MAG (Trading Partner #3)

As a final example of an Overlay MAG, we have a Trading Partner # 3 that sends the net price (PRI+AAA) in the UN/EDIFACT D96A ORDERS (that isn’t mapped in the Base MAG).

The creation of the Overlay MAG is nearly the same – the same Base MAG and the same Source MIG (MIG 1) and Target MIG (MIG 2) from the Base MAG are used.  This will be the new MAG for Trading Partner # 3.

We then switch to Edit mode and add the additional mapping element:

Save the Overlay MAG and simulate it with the test payload to see if the mapping is executed correctly. Activate when complete. 

After creating the Agreement with this Overlay MAG, you can do additional testing over the iFlows. Summary

As you can see, we now have 1 Base Mapping that is being used as the “skeleton” and 3 new UN/EDIFACT D96A ORDERS mappings for 3 different trading partners, created in really a fraction of the time it might take to set up 3 individual mappings. We were also able to add, edit, and remove segments in our new Overlay mappings.

Base-Overlay MAGs can be used to help define how messages are mapped between different formats. Instead of creating separate mappings for each business partner, SAP Integration Suite allows you to:

• Create a Base MAG with common mapping rules.

• Extend it with Overlay MAGs to customize mappings for multiple Trading Partners or scenarios.
  

This approach improves reusability, consistency, and maintenance efficiency, especially when dealing with multiple Trading Partners who use similar message structures, but have slight variations.

Want to know more? Feel free to contact us

Cover designed by Freepik