SAP Message Mapping

Message Mapping is the process of converting data from one structure and format into a different structure and format. The source system sends data organized one way. The target system expects data organized a different way. Message Mapping defines the transformation rules that bridge the gap.

Think of message mapping like translating a form from English to German while also changing the layout. The English form asks "First Name" then "Last Name" in separate fields. The German form expects "Vorname" and "Nachname" in the same order. The address section uses different field names and a different postal code format. Message mapping defines all these conversions in one place.

The Message Mapping Editor in CPI

CPI provides a graphical mapping editor. You import the source structure (as XSD or WSDL) and the target structure, then draw lines connecting source fields to target fields. Where the connection is not direct, you add functions that transform the value in between.

SOURCE STRUCTURE          MAPPING LINES          TARGET STRUCTURE
─────────────────         ─────────────          ────────────────
PurchaseOrder                                    ORDERS05
  OrderNumber ─────────────────────────────────→ E1EDK01/BELNR
  OrderDate ──────────[Date Formatter]──────────→ E1EDK03/DATUM
  Supplier ────────────[Lookup Table]───────────→ E1EDKA1/PARTN
  LineItems                                       E1EDP01
    Item (loop)─────────────────────────────────→   (loop)
      Material ─────────────────────────────────→   MATNR
      Quantity ─────────────────────────────────→   MENGE
      Unit ──────────────────────────────────────→   MENEI

Simple Field Mapping

The simplest mapping is a direct field-to-field connection. Drag a line from the source field to the target field. CPI copies the value exactly. Use this when both fields carry the same value in the same format.

Example: The source XML has <OrderID>PO-12345</OrderID>. The target IDoc segment has field BELNR. Drawing a line from OrderID to BELNR copies the value "PO-12345" into BELNR. Nothing more needed.

Mapping Functions

When a direct copy is not enough, you add functions between source and target. CPI includes dozens of built-in functions organized into categories:

String Functions

• ConcatenateWithSeparator – Joins two fields: "John" + " " + "Smith" = "John Smith"
• Substring – Extracts part of a string: "PO-12345" → "12345"
• toUpperCase / toLowerCase – Changes case
• replaceAll – Replaces characters: "PO/12345" → "PO-12345"

Date and Time Functions

• parseDate / formatDate – Converts date formats: "2024-05-01" → "01.05.2024"
• DateTrans – Transforms date with pattern: "yyyy-MM-dd" → "yyyyMMdd"

Numeric Functions

• add, subtract, multiply, divide – Basic arithmetic
• formatNumber – Controls decimal places and thousand separators

Boolean Functions

• If – Conditional: if order type = "Rush" then "X" else ""
• Equals, Contains, StartsWith – Comparison functions for conditions

Node Functions

• Constant – Always outputs the same fixed value regardless of input
• removeContexts – Collapses multiple values into one
• splitByValue – Splits one value into multiple target occurrences

Handling Repeating Elements (Loops)

A purchase order can have one header but many line items. The source structure contains a repeating <Item> element. The target structure has a repeating segment E1EDP01. Message mapping handles this with a loop:

SOURCE:                               TARGET:
<Items>                              E1EDP01 (occurrence 1)
  <Item><Mat>A</Mat><Qty>10</Qty> →   MATNR=A, MENGE=10
  <Item><Mat>B</Mat><Qty>5</Qty>  →  E1EDP01 (occurrence 2)
  <Item><Mat>C</Mat><Qty>8</Qty>  →    MATNR=B, MENGE=5
</Items>                             E1EDP01 (occurrence 3)
                                       MATNR=C, MENGE=8

You draw the mapping once for the repeating structure. CPI automatically repeats the mapping for every occurrence in the source. The target receives as many output occurrences as there are source elements.

Context in Message Mapping

Context is one of the most important — and most confusing — concepts in SAP message mapping. A context defines the scope within which values are grouped. The wrong context produces incorrect output, especially in complex multi-level structures.

Simple Context Example

Order Header: 1 occurrence
  Line Items: 3 occurrences

Mapping HeaderField to LineItemField (wrong context):
Result: HeaderField value appears 3 times (once per line item)

Mapping HeaderField to HeaderField (correct context):
Result: HeaderField value appears 1 time

Use the removeContexts function to collapse values. Use useOneAsMany to repeat a header value across child records. Context errors are among the most common bugs in SAP message mapping and the cause of mysterious duplicate or missing data in output.

User-Defined Functions (UDF)

When built-in functions cannot handle your logic, you write a User-Defined Function (UDF) in Java directly inside the mapping editor. A UDF accepts input values and returns an output value after applying your custom logic. Common use cases:

• Complex string manipulation that no built-in function handles
• Conditional logic with multiple conditions and outputs
• Calling a lookup table that maps codes between systems
• Generating a formatted document number by combining multiple fields

Testing a Message Mapping

The mapping editor includes a test panel. You paste a sample source XML message and click Test. The editor shows the output XML produced by the current mapping. Test your mapping with multiple input variations:

• A minimal message with only required fields
• A full message with all optional fields populated
• A message with edge cases — empty optional fields, maximum field lengths, special characters
• A message with multiple line items to verify loop behavior

Catching mapping errors in the test panel is far faster than catching them in a deployed iFlow processing real messages against a live SAP system.