Enterprise Resource Planning Blogs by SAP
Get insights and updates about cloud ERP and RISE with SAP, SAP S/4HANA and SAP S/4HANA Cloud, and more enterprise management capabilities with SAP blog posts.
cancel
Showing results for 
Search instead for 
Did you mean: 
victordiehl
Associate
Associate
12,197

Introduction

In the context of Business Partner integration via Web Service (SOAP), the replication process creates Business Partners and their associated objects, such as Customers, Vendors, Addresses, etc., using number ranges defined in the target system. It's important to note that these objects may not necessarily be created with the same number ranges as those specified in the source system. To enable this flexibility, the interface utilizes a functionality known as Key Mapping, which is crucial to ensure that each object is correctly identified across the system landscape.Given the high dependency on the Key Mapping, the interface becomes susceptible to disruptions when there are issues with it. Unsurprisingly, the majority of cases reported in this integration scenario arise from incorrectly maintained Key Mapping. However, due to the complexity involved in the replication process, identifying such issues and fixing them demands a specific level of technical expertise on the subject.

In this blog, I aim to provide a comprehensive understanding of Key Mapping within this integration scenario. I will guide you through the process of identifying problems in the Key Mapping for specific objects and how to correct them.

Target audience: team members responsible for the Web Service administration.

Relevant systems: MDG-based and S/4HANA.

 

Common Issues

In the following table, you can see some of the most common error messages returned during the inbound processing when there are key mapping issues in the payload:

 

Message textTechnical number
Object Identifier type 888 still exists for ID value006(BS_SOA_COMMON)
Object identifier type 927 still exists for ID value006(BS_SOA_COMMON)
External Address ID  already used for Business Partner Guid &009(BP_DATAREPL_FND)
Address doesn't exist010(AM)
Business partner &1 already exists286(R1)
Address is still being used and may not be deleted455(R1)
BP role &1 does not exist for partner &2657(R11)
Task insert is not supported for existing customer007(CVI_EI)
Task insert is not supported for existing vendor042(CVI_EI)


Not always an error will be raised. Sometimes, wrong key mapping will just cause unexpected behaviors:

  • Partner Functions not created or updated
  • A Business Partner appears multiple times in the same payload

What is Key Mapping

In simple terms, Key Mapping is a mapping table used to get the corresponding numbers of a specific object in the connected systems. In this mapping table, each Business Partner and its linked objects will be assigned to a unique mapping group, all the numbers associated with that Business Partner must be under the same mapping group. Check out this simple example:

 

Mapping GroupObject ID (No.)Business SystemObject TypeObject Type IDValue
10001SYSTEM_ABusiness PartnerNumber1000082741
10001SYSTEM_ABusiness PartnerUUID0d17a4a2-b86d-4038-a709-118d3203c779
10002SYSTEM_BBusiness PartnerNumber9999921374
10002SYSTEM_BBusiness PartnerUUIDa5b13f62-4948-4053-a57a-d209cf9ce87f


When system A tries to replicate BP 1000082741 to system B, it checks the Key Mapping table to determine what is the corresponding number in the target system. To find the key mapping, the source system starts the search with four values:

  1. Own Business System: SYSTEM_A
  2. Own Business Partner Number: 1000082741
  3. Own Business Partner UUID: 0d17a4a2-b86d-4038-a709-118d3203c779
  4. Target Business System: SYSTEM_B

With the own Business System, Business Partner Number and UUID, it finds the Mapping Group 1000. Then, it checks if there is a corresponding number for the target Business System under this same Mapping Group. In this example, the following entries would be found:

  1. Target Business Partner Number: 9999921374
  2. Target Business Partner UUID: a5b13f62-4948-4053-a57a-d209cf9ce87f

Pay Attention to the Object ID (No.) column

An object can have multiple identifiers, which is the case of Business Partners, where they can be identified by a 10-digits number and a UUID (Universal Unique Identifiers). Since both identifiers point to the same object in a single system, they must have the same Object ID. That is why the Object ID repeats itself for the Number and UUID.

How is the Key Mapping used?

At the time the payload is being generated, the source system uses the Key Mapping, if it exists, to set the target object numbers in the XML file. These numbers will be placed in tags whose name starts with "Receiver", for example:

<BusinessPartner actionCode="04" ...>

    <!-- Source system BP UUID: -->

    <UUID>0d17a4a2-b86d-4038-a709-118d3203c779</UUID> 

    <!-- Source system BP Number: -->

    <InternalID>1000082741</InternalID> 

    <!-- Target system BP UUID: -->

    <ReceiverUUID>a5b13f62-4948-4053-a57a-d209cf9ce87f</ReceiverUUID> 

    <!-- Target system BP Number: -->

    <ReceiverInternalID>9999921374</ReceiverInternalID> 

    ...

</BusinessPartner>


If the Key Mapping does not exist, the payload will be created without the receiver tags:

<BusinessPartner actionCode="04" ...>

    <!-- Source system BP UUID: -->

    <UUID>0d17a4a2-b86d-4038-a709-118d3203c779</UUID> 

    <!-- Source system BP Number: -->

    <InternalID>1000082741</InternalID> 

    ...

</BusinessPartner>


The target system process the payload and uses the receiver tags to determine whether the objects must be created or updated:

  • If receiver tags are available, their values will be used to find the objects and update them.
  • If receiver tags are not available, the target system will try to create the corresponding objects.

Special case

When receiver tags are not available for the Business Partner, the target system will use the source system's BP UUID to find out if a corresponding BP exists already. If the target system finds a Business Partner with same UUID from the source, then this Business Partner gets updated. Otherwise, a new Business Partner will be created.

It is important to emphasize that Key Mapping applies solely to the specific object it represents. The presence of Key Mapping for one object does not imply the automatic identification of associated objects. For instance, if a Business Partner has Key Mapping, but the linked Customer does not, only the Business Partner will be updated. In the absence of Key Mapping for the Customer, the target system will attempt to create it. If the Customer already exists in the target system, error message "Task insert is not supported for an existing customer" will be returned.

When is the Key Mapping created?

Ideally, the Key Mapping should be created automatically when the objects are being created in the target system by the replication process. The Business Partner integration via Web Service works with 4 services for Business Partners and 4 services for Relationships:

Services of Business Partner integration via Web Service

For each Business Partner, there will be a confirmation message containing the numbers of the objects created in the target system. In the source system, the Key Mapping is automatically created when the confirmation messages are processed:

  • BusinessPartnerSUITEBulkReplicateConfirmation_In
  • BusinessPartnerRelationshipSUITEBulkReplicateConfirmation_In

In the target system, the Key Mapping should also be created. That happens after the Business Partners getting successfully processed by the request messages:

  • BusinessPartnerSUITEBulkReplicateRequest_In
  • BusinessPartnerRelationshipSUITEBulkReplicateRequest_In

Here it is very important to notice that when the confirmation messages are not configured properly, the Key Mapping will never be created in the source system, resulting in at least one of the issues aforementioned. If this is not identified quickly before running the integration, thousands of Business Partners may be replicated without the generation of Key Mapping. Next time the same Business Partners get replicated, the source system will not be able to tell the target system which Business Partners should be updated. As consequence, the target system will try create the same objects again.

Where to maintain the Key Mapping?

For some reasons, it might become necessary to manually adjust the Key Mapping. Say for example that you have created the same Business Partner in two different systems using BP transaction and now you want to replicate it from one system to another using this integration via Web Service. Since the Business Partner was not initially created by the replication process, the Key Mapping will not be available. This way, it is necessary to create the Key Mapping manually.

There are two transactions relevant in this case:

  • MDG_ANALYSE_IDM
  • MDG_KM_MAINTAIN

MDG_ANALYSE_IDM can be used to search and display the Key Mapping. This option is ideal if you just want to check the Key Mapping, considering it has a flexible search criteria.

MDG_KM_MAINTAIN, on the other hand, is a Web GUI based transaction that offers the possibility to display, change and create Key Mapping. However, all search fields must be populated to find a Key Mapping, making it not so good for searching purposes.

 

Objects Relevant to Key Mapping

This integration scenario not only replicates Business Partners but also encompasses other associated objects, including Customers, Vendors, Contact Persons, and Relationships. These objects have their own number range and, therefore, are subject to Key Mapping.

 

Business Object TypeObject ID Type
147 - Business Partner888 - Business Partner Number
 889 - Business Partner UUID
1405 - Business Partner Relationship926 - Business Partner Relationship Category Key
 927 - Customer Contact Partner ID
 939 - Supplier Contact Partner ID
159 - Customer918 - ERP Customer Number
266 - Supplier888 - ERP Vendor Number


Next, I will show how the Key Mapping should be maintained for each of these objects in this integration using some examples. The following systems will be used:

  • Source system: QKJ-002 - SAP S/4HANA 2020 (screenshots in blue)
  • Target system: QKK-002 - SAP S/4HANA 2021 (screenshots in red)

Key Mapping for Business Partners

In the source system, I am using BP transaction to create a Business Partner. This Business Partner in QKJ-002 was created with number 37897 based on internal number assignment.

Business Partner created in source system

Now, in the target system, again I am using BP transaction to create the same Business Partner. This time, in QKK-002, it was created with number 400000251.

Business Partner created in target system

As this Business Partner was manually created in both systems, no Key Mapping is available. If I try to replicate this Business Partner now, the target system will receive the payload with no receiver tags, resulting in the creation of a new Business Partner instead of updating Business Partner 400000251.

To maintain the Key Mapping, I am going to use MDG_KM_MAINTAIN transaction in the source system. First, I search to make sure no Key Mapping exists for Business Partner 37897:

MDG_KM_MAINTAIN - No Key Mapping available for Business Partner 37897 in source system

After confirming no Key Mapping exists, I can now maintain the Key Mapping. In this case, four mappings will be necessary:

  1. Business Partner Number in source system
  2. Business Partner UUID in source system
  3. Business Partner Number in target system
  4. Business Partner UUID in target system

Where do I get the Business Partner UUID?

Business Partners are stored in BUT000 table. In this table, PARTNER_GUID field holds the Business Partner GUID. By applying a simple format to the GUID, the UUID can be obtained.

Screenshot from SE16N showing the PARTNER_GUID field of Business Partner 37897

  • GUID format: 42010AEF4CF51EEE9FE4708BEF9B42AD
  • UUID format: 42010aef-4cf5-1eee-9fe4-708bef9b42ad

To create new Key Mapping, I click on "Add Row" and add four new lines:

MDG_KM_MAINTAIN - Key Mapping maintained for Business Partner 37897 in source system

Observe that the first column, "No.", must have the same value for the Business Partner Number and Business Partner UUID.

You may also observe there is no "Mapping Group" column displayed here. Indeed MDG_KM_MAINTAIN does not display this column. However, you must assume that all lines displayed on the screen belong to the same mapping group. When you search for an object using MDG_KM_MAINTAIN, it will bring all the entries found for that object under the same mapping group. To see the mapping group, we can use MDG_ANALYSE_IDM transaction.

MDG_ANALYSE_IDM - Initial screen

Compared to MDG_KM_MAINTAIN, the only field I have to fill here is the "Bus. Obj. Type", where I enter the object I am looking for. However, it will bring all the Key Mapping available in the system for that object, which can be time consuming, and that is not what I want. Thus, I combine it with "ID Value" field where I enter the number of the object I am trying to find. It is not mandatory, but I could enter the "Object ID Type" as 888, which is the type for Business Partner Number, and "Business System" as QKJ_002 to narrow down the result list.

MDG_ANALYSE_IDM - Key Mapping search result for Business Partner 37897

In "Selected Objects" section, system displays the objects found based on the search criteria. In that list, it is possible to see the "Mapping Group ID" column. All the Key Mappings representing that entity will be under that same mapping group. To see all the Key Mapping maintained for that mapping group, double-click on that line.

MDG_ANALYSE_IDM - All Key Mapping for Business Partner 37897

In "Mapping Groups of an Object" section, the four Key Mapping maintained earlier using MDG_KM_MAINTAIN can be seen. All of them have the same mapping group, i.e. 42010AEF4CF51EEEA083DF375FBF62AE.

Another column that is shown here but not in MDG_KM_MAINTAIN is the "Object ID", which represents the "No." column. Just like MDG_KM_MAINTAIN, the value is repeated for the identifiers pointing to the same object, e.g. Business Partner Number and Business Partner UUID. To make it more user friendly, MDG_KM_MAINTAIN translates the huge number from "Object ID" to a smaller integer.

 

No. column (MDG_KM_MAINTAIN)Object ID column (MDG_ANALYSE_IDM)
142010AEF4CF51EEEA083DF375FBE42AE
142010AEF4CF51EEEA083DF375FBE42AE
242010AEF4CF51EEEA083DF375FBEE2AE
242010AEF4CF51EEEA083DF375FBEE2AE


Now that the Key Mapping is perfectly maintained for the Business Partner, the replication should work. When I trigger the replication for this Business Partner, the receivers tags are placed in the payload:

<BusinessPartner ...>

    <UUID>42010aef-4cf5-1eee-9fe4-708bef9b42ad</UUID>

    <InternalID>37897</InternalID>

    <ReceiverUUID>42010aef-4d95-1ede-a083-689b6b435d33</ReceiverUUID>

    <ReceiverInternalID>400000251</ReceiverInternalID>

    ...

</BusinessPartner>

Key Mapping for Customers

For this same Business Partner, I am going to extend it to a Customer, by adding a Customer role in both systems using BP transaction.

In the source system, the Customer was created with number 4453.

Customer created in the source system

In the target system, the Customer was created with number 400000060.

Customer created in the target system

Again, no Key Mapping exists since the Customer was not created by the replication process. Hence, in the source system, I go back to MDG_KM_MAINTAIN, and add two new lines:

  1. Customer number in the source system
  2. Customer number in the target system

MDG_KM_MAINTAIN - Key Mapping maintained for Customer 4453 in source system

After replicating the Business Partner, the receiver tags for the Customer are there in the payload.

<BusinessPartner ...>

    <UUID>42010aef-4cf5-1eee-9fe4-708bef9b42ad</UUID>

    <InternalID>37897</InternalID>

    <ReceiverUUID>42010aef-4d95-1ede-a083-689b6b435d33</ReceiverUUID>

    <ReceiverInternalID>400000251</ReceiverInternalID>

    ...

    <Customer ...>

        <InternalID>4453</InternalID>

        <ReceiverInternalID>400000060</ReceiverInternalID>

    </Customer>

</BusinessPartner>


In MDG_ANALYSE_IDM, the Key Mapping also shows correctly:

MDG_ANALYSE_IDM - Key Mapping for Business Partner 37897

Key Mapping for Suppliers (formerly known as Vendors)

To create a Supplier, I am going to take the same steps as I did for Customers. In BP transaction, I add a Supplier role in both systems.

In the source system, the Supplier was created with number 105780,

Supplier created in source system

In the target system it was created with number 400000065.

Supplier created in target system

In MDG_KM_MAINTAIN, I add two new lines:

  1. Supplier number in the source system
  2. Supplier number in the target system

MDG_KM_MAINTAIN - Key Mapping maintained for Supplier 105780 in source system

Key Mapping for Customer Contact Persons

To add a contact person to a Customer or a Vendor in BP transaction, first it is necessary to create a Business Parter of type Person.

In the source system, this Business Partner Person was created with number 37915.

Business Partner Person created in the source system

This time, I let the replication process create this Business Partner in the target system and it was created with number 500011140.

Business Partner Person created in the target system

As this Business Partner was created via replication, the Key Mapping was maintained automatically.

MDG_KM_MAINTAIN - Key Mapping for Business Partner Person in the source system

We may observe here that the UUID of this Business Partner is the same in both system. When the Business Partner is created via replication, the UUID sent by the source system will be used to create the Business Partner in the target system.

With this Business Partner Person created, I can now create a Business Partner Relationship of type Contact Person.

Contact Person Relationship created between Business Partners 37897 and 37915 in the source system

In the target system, I create the same relationship with the corresponding Business Partner numbers.

Contact Person Relationship created between Business Partners 400000251 and 500011140 in the source system

Since the main Business Partner has a Customer assigned, once I create a relationship of type Contact Person, system automatically creates a Customer Contact Person in KNVK table. Searching in KNVK table using the Customer number, I can find the number of the Customer Contact Person.

In the source system, the Customer Contact Person was created with number 23805.

Customer Contact Person number in KNVK table in the source system

In the source system, the Customer Contact Person was created with number 25108.

Customer Contact Person number in KNVK table in the target system

At the end, this is what I have:

SystemMain Business PartnerBusiness Partner PersonCustomer Contact Person
Source - QKJ-002378973791523805
Target - QKK-00240000025150001114025108


To maintain the Key Mapping, in MDG_KM_MAINTAIN, I select the Business Object Type "1405 - Business Partner Relationship" and Object ID Type "926 - Business Partner Relationship Category Key (ERP)".

MDG_KM_MAINTAIN - Selection for Business Partner Relationship maintenance

Next I enter the Business Partner numbers with the Relationship Category BUR001 - Contact Person.

MDG_KM_MAINTAIN - Pop-up to enter Business Partner Relationship details

After clicking on Show button, no Key Mapping is found, which is expected as I did not create it yet.

MDG_KM_MAINTAIN - No Key Mapping found the Business Partner Relationship between 37897 and 37915 in the source system

Here I have to add four lines:

  1. Numbers of the Business Partners in a Contact Person Relationship in source system
  2. Customer Contact Person number in source system
  3. Numbers of the Business Partners in a Contact Person Relationship in target system
  4. Customer Contact Person number in target system

It is important to add the Customer Contact Person number with leading zeros. Also, notice that values in the "No." column must be the same as they point to the same object in the same.

MDG_KM_MAINTAIN - Key Mapping maintained for Customer Contact Person in source system

Key Mapping for Vendor Contact Persons

Since the main Business Partner also had a Vendor assigned at the moment the relationship was made with that Business Partner Person, the system also created a Contact Person for the Vendor. The Vendor Contact Person number can also be found in KNVK table using the Vendor number.

In the source system, the Vendor Contact Person was created with number 23806.

Vendor Contact Person number in KNVK table in the source system

In the target system, the Vendor Contact Person was created with number 25109.

Vendor Contact Person number in KNVK table in the target system

Putting all together, this is what I have:

SystemMain Business PartnerBusiness Partner PersonVendor Contact Person
Source - QKJ-002378973791523806
Target - QKK-00240000025150001114025109


Since, I already maintained the Key Mapping for the relationship between the Business Partners, I just have to add the Key Mapping for Vendor Contact Person numbers by adding two new lines:

  1. Vendor Contact Person number in source system
  2. Vendor Contact Person number in target system

Conclusion

Hope I was able to help you somehow to understand how the Key Mapping is maintained for each of the objects involved in the integration of Business Partners and its importance. Please remember:

  • Key Mappings are automatically created when the objects are created by the replication process. If an object was not created via replication, it is necessary to maintain the Key Mapping manually.
  • Do not forget to setup the confirmation messages as Key Mappings are created when they are are processed.
7 Comments