Code List Mapping: Manual Mapping Best Practices For High Quality Results

[Felix_Wyskocil]

When you want to integrate SAP Sales Cloud or SAP Service Cloud (formerly known as SAP Cloud for Customer "C4C", in the following referred to as "cloud") with other systems like SAP S/4HANA or SAP ERP, etc. you have to take care about code list mapping.

There are already good blogs that describe code list mapping in general or the automatic code list mapping feature. In this blog I want to share my personal approach and point out some important facts, that I sometimes felt lost in the background noise. Small pitfalls that can drastically influence the result! In addition to that, I provide an Excel workbook (containing macros!) that can help you with the typical tasks.

My approach will lead to higher quality mapping entries (in comparison to the "automatic" approach with the code list mapping report), that makes maintenance and error resolving for failed messages easier later on.

 

Essential Understanding: Code List ... and Mapping

To make sure everyone has the same view on the topic, let's first clarify again what code list mapping actually is. The most important aspect to mention is, that when we talk about code list mapping, we should have the two different steps in mind: code list and mapping. Because this is exactly what I sometimes felt missing. It's not only about mappings.

Code Lists

A code list is -from an end user perspective- a drop down somewhere on the UI where you can choose a value from a predefined list. This list can usually be translated in all relevant logon languages and can be context sensitive, i.e. the value you can choose actually depends on the value of another field. A good example for that is the RegionCode which depends on the selected CountryCode.

Code lists are maintained by key users (administrators) in finetuning (workcenter Business Configuration, view Overview or Implementation Projects -> Activity List) and consist of a technical code (language independent) and a description, that is usually language dependent.

Finetuning activity for Academic Titles

As long as you run a system standalone, you just need to brainstorm what values you need and you might find it handy that SAP Sales Cloud/SAP Service Cloud gets delivered with a nice set of default values for nearly everything and you could jump start right away.

This changes completely when you want to integrate SAP Sales Cloud/SAP Service Cloud with another system which is usually already in place. Then SAP Sales/Service Cloud needs to adapt to the existing system. Now you might say: "That's the point where code list mapping comes into the game!" That's not wrong, however, it's only half the story...

Mapping

Code list mapping adds an "external perspective" to the so far "internal" considered code list values. Each internal code list value (code) can get external codes assigned that are used when communicating with external systems. I'm writing that in plural, because each internal code can have different external codes, e.g. for different systems...

Code List Mapping with Equal Values for Academic Titles

(Groups)

To be more exact: Actually a code list mapping always belongs to a code list mapping group.
(When you define a communication arrangement that handles communication for a specific scenario with a specific system, you assign a code list mapping group (or choose no code list mapping). The most prominent group is SAP On Premise Integration and has a code on its own: 03)

Code List Mapping Groups

 

Overall Aim

As mentioned earlier, it's not just about the mapping. The most important question is:

What to do with codes, that are pre-delivered by SAP Sales/Service Cloud and have no equivalent in the external system?

The existing system will usually be the leading system. It has run for years and it's configuration is usually fixed. SAP Sales/Service Cloud, as the new system, has to stick to it. That does not only mean, to map entries with the same meaning/description. That also means, that we need to get rid of default values, that are gratefully delivered, but in integration scenarios prevent us from creating parity with the existing system. This is the essential aspect, that I feel missing in most guides about code list mapping:

Remove default entries in SAP Sales/Service Cloud, that are not available in the leading system.

 

Sample Scenario

Let's assume we have the following situation: A customer wants to integrate SAP Sales Cloud with their existing SAP S/4HANA On-Prem system. The following graphic shows the initial situation for Academic Titles in SAP Sales Cloud on the left hand side and SAP S/4 HANA on the right hand side.

The green lines between them show the mappings that would be needed, the green arrow shows a value (B.A. - Bachelor of Arts), that only exists in S/4 and the short red lines show values (MBA - Master of Business Administration, do not mix with B.A.), that are pre-delivered by SAP Sales Cloud, but they are not available in S/4 and hence should be removed.

Initial Situation

In order to solve this problem, let's find out where the automatic and the manual approach lead us.

 

Automated Code List Mapping with the Report

Downloading a zip file from SAP Sales/Service Cloud, executing the code list mapping report (CODD_CODE_LIST_MAPPING) in the on-prem system (e.g. SAP S/4HANA) and finally uploading the resulting zip file back to SAP Sales/Service Cloud...

Sounds easy, right?

Report Output

Let's have a look at the produced result for our sample values of academic titles. Cloud on the left and on-prem on the right hand side.

Result of the Automatic Code List Mapping Report for sample Academic Titles

Did you expect that?

Well, we can see three problems here. Four if we include the quality/complexity of the mapping.
What can we observe? Let's start from good to bad:

• 😀 The report has successfully mapped 3 entries (green and blue lines) for "Prof. Dr.", "Dr." and "B.A.", where one entry has been added on cloud side.


• 🤔 What about "Prof."? Why do we have two entries now? (yellow line)
  Did you notice that in S/4 there is no dot (.) at the end? That makes two different descriptions and hence completely different entries for the report.


• 😯 Counting "Prof" we will end up with three entries (red lines) in SAP Sales and Service Cloud that are not mapped, because there is no equivalent in S/4. They must be removed. However, deleting existing entries is not supported by the feature!
  If you do not delete them, end users can select them and the integration will break. (As long as we don't want to go an extra mile with tons of pointless Code List Restrictions)


• 🥴 The fourth problem is more an aesthetic attitude. The result is a mapping of
  02 -> 0003
  03 -> 0001
  Z2 -> 0004
  Looks confusing at a first glance, right? In my humble opinion it is, which makes troubleshooting later on (resolving failed messages) more complex, because you always have to look up each and every code mapping. Wouldn't it be nice if all entries would have the same numbers? (And prefixes wherever needed)

 

Limitations of the Report

Let's quickly recap the limitations of the automatic code list mapping feature (this spans across cloud upload and on-prem report). It's not possible to:

• Delete existing entries in SAP Sales/Service Cloud


• Update descriptions of already maintained languages in SAP Sales/Service Cloud
  (You can upload descriptions of existing entries that are not maintained in a certain language)


• "Replicate" any configuration data
  (There is no connection between the systems. Everything is exchanged via csv/zip files.)

 

Manual Best Practices

Desired Result

The desired result covers, different aspects: First of all, cleaning up the pre-delivered codes on cloud side if they do not completely match the on-prem side. And furthermore, mapping entries with more intuitive code pairs.

The desired result could look like this:

Desired Code List Mapping Result

All codes have the same relevant digit like in the on-prem solution. They only have a Z prefix, which is a technical prerequisite in SAP Sales/Service Cloud. (Prefix and max code length depends on the code list)

 

Procedure In General And In Short

As a preparation: Create a list of all relevant code lists for your scenarios and execute the following steps per code list or per subset of code lists. (The less code lists you "process" at once, the easier  you can keep the overview and do not run into danger of leaving a step out.)

1. In SAP Sales/Service Cloud: Open the fine tuning activity for the code list you want to "process" and find out the following:
   Can remove all existing codes easily or are there any dependencies?
   What is the maximum length for custom codes?
   What prefix is required (e.g. "Z")?


2. Get all relevant codes in all relevant languages from on-prem system (e.g. via table transaction SE16(n)). At this step, you can compare the cloud and on-prem values. Some codes may be equal from the beginning and do not need any action at all (rare case).
   Otherwise delete default codes on cloud side and go ahead.


3. Put the on-prem codes and descriptions into the code list and mapping templates. The challenge is:
   That you need to put all codes and descriptions for all languages into the code list template., where you still have to adapt the codes for the cloud system -> include prefix.
   The mapping template needs the adapted codes as well along with the matching on-prem codes and we have to remove duplicate code-mapping entries in case we have copied values for multiple languages. (This is where the Code List Mapping Helper helps you the most)


4. Upload the file to SAP Sales/Service Cloud and check the log -> No error; only warnings usually means success.

 

Procedure In Detail - Using the Code List Mapping Helper

In this chapter I'll explain the procedure in more detail using the help of the Code List Mapping Helper.

First of all, say "Bye, bye!" to the idea, that everything is done with a single click. But don't worry! After getting familiar with the procedure, it won't take too much time. Furthermore, this approach will help you getting to know the involved systems better.

When you use the Code List Mapping Helper, the visual representation of the procedure for each code list will look like this:

Procedure in Pictures: From Copy and Paste to Codelist and Mapping

 

Preparation: Download the Code List Mapping Helper Excel (containing macros, further details below) or prepare an excel file with the right structure for code lists and mappings on your own.
(If you use your own file, you have to download the file with the overview on code lists per scenario in addition.)
Having a list of relevant code lists where the according fine tuning activities, on-premise tables and IMG paths are listed is vital for the following steps.

Identify the relevant code lists for your integration scenarios and repeat the following procedure per code list (or for a small subset of code lists in each run). Processing multiple code lists at a time increases the possibility of losing overview, forgetting steps and it makes troubleshooting harder. So the clear recommendation is, that you go code list by code list.

Chose a code list and do the following:

1. Open the respective finetuning activity on the cloud side.The overall aim is to delete all existing codes and upload all codes from the external system as "Z"-codes.
   (If the cloud codes are not equal to the on-prem codes straight from the beginning.)If it's a simple code list with just some codes and descriptions, you can usually delete all entries and go ahead.
   Examples: Distribution Channels, Divisions, Professions, Industries, ...If additional data can be maintained, it depends on the code list, if you really need it.
   Example: time spans for Payment Terms (CashDiscountTerms) can be omitted, as there is no logic in SAP Sales Cloud that makes use of them.Some code lists have dependencies to other code lists or business logic. They cannot be deleted. But they can maybe be deactivated and new values can be added.
   Most prominent example: Countries and RegionsSome code lists might be used internally, where the pure technical aspect is not enough to tell you which ones are really in use or can be chosen by end users (e.g. because it depends on business logic). Then you can probable not delete existing entries, but can add additional ones and map existing ones to the equivalents of the external system.
   Examples: Party Roles, Relationships, Units of Measure, ...Finally: Don't hesitate to involve a functional consultant or the customer's key user(s) to clarify if certain values are needed. Code list mapping is not a pure technical task!
   Business Partner Roles are good examples for that. An existing on-premise system will usually have many, many Business Partner roles in the respective table. However, for SAP Sales/Service Cloud only a very small subset will be used (e.g. only FLCU01 in the easiest case).
   


2. Extract the codes and descriptions in all relevant languages from the external system.
   As mentioned above: Make sure to only grab relevant values (e.g. do not download ALL business partner roles, where 90% are irrelevant for a connected CRM system)👉 For on premise systems a handy approach is to open the respective table with a table display transaction e.g. SE16n or SE16. SE16n has the advantage, that it shows you the respective text table where you can grab multiple languages at once. (e.g. TSAD2T instead of TSAD2).


3. In the Code List Mapping Helper, paste the extracted codes, descriptions and the language codes into the desired table on the red Copy And Paste worksheet (with the unchanged external code). Pay attention to the right table columns and do not change the worksheet columns. Use the Temp worksheet for preparing the on-prem values.


4. Check what prefix is needed for the respective code list and what the maximum length for new codes is (you may add a new code in finetuning manually to find that out).
   Generate valid codes for the cloud by adapting the formula for the column C4C Codes (or in the worst case, enter codes manually).


5. Maintain the header entries: Code List, Main Language and Mapping Group.
   The Main Language defines which entries will be used to create the mapping entries. In case the on-prem system has some languages, where not all codes are mentioned, it is important, that you pick the language, that has all codes maintained or you have to add mappings manually after the next step.


6. Select the CLM Helper ribbon tab and execute Generate Codes and Mappings.
   This copies the codes, descriptions and language information to the blue Code List worksheet and the codes and mappings of the main language to the blue Code Mapping worksheet.
   In case you are not using the CLM Helper, you have to do this mapping and preparing the code and mapping worksheet on your own.


7. In the CLM Helper tab, select the Save Zip action to save the data from the two blue worksheets to a ready-to-upload zip file.
   In case you are not using the CLM Helper, you have to save the two worksheets as CSV UTF-8 (pay attention to UTF-8!) with the corresponding names (CodeList.csv and CodeMapping.csv) and put them into a zip file.


8. Finally upload the ZIP file to SAP Sales/Service Cloud and check the logs after a while.
   Warnings may occur, for instance if you try to upload descriptions for already maintained codes/languages. The log will also contain warnings about missing entries of other code lists. That's the typical behavior and can be ignored. At this point "No error"/warnings usually means success.

Repeat those steps for each code list until you have maintained all relevant code lists. After running through the procedure once or twice, you will get familiar with the steps and will speed up. Finally this approach helps you getting to know the systems and the background of all the settings.

 

Code List Mapping Helper

Code List Mapping Helper Excel

The Code List Mapping Helper Excel is an Excel workbook (with macros) that contains prepared worksheets for working with code lists and mappings and provides some automation for the most common todos in form of a new ribbon tab ("CLM Helper" - Code List Mapping Helper) to help you with steps like importing and exporting the zipped csv files in the proper format and generating the mappings.

• The blue CodeList and CodeMapping worksheets are for exporting to zip files and should contain the code and mapping data that you want to upload to the cloud.


• The red Copy and Paste worksheet is the place where you can enter codes extracted from an external system and prepare the code for the cloud side. It is the source for the Generate Codes and Mappings action.


• The grey Temp sheet is for preparing data, that does not match the Copy And Paste table structure or needs other preparation steps.


• The green Code Lists and Scenarios worksheet provides an overview on relevant code lists per scenarios and has been extended to also include the prefixes per code list (always double check with the current system status, as the list might be outdated!)


• The yellow Sample Templates worksheet contains the column definition for the CodeList and CodeMapping worksheets, in case you need it with some sample values.


• White CodeList and CodeMapping worksheets will be added when you open zip files with the CLM Helper.

Further details can be found on the Intro worksheet.

Summary

To conclude this topic, we can say that manual code list mapping has the following advantages:

• Better overview on relevant code lists -> you have a look at each code list in fine tuning


• Better control on used codes -> makes troubleshooting easier later on


• Certainty, that irrelevant codes have been removed from finetuning

Even when using the automatic code list mapping feature, you would still have to double-check and visit each codelist/finetuning activity. Why not taking a little more effort to reach a much better quality and control them? And with the help of such tools like the Code List Mapping Helper, the manual process can be run through much faster, so that it doesn't take too much time.

Hope this article was helpful! Feedback is always welcome! 🙂