SAP Value Mapping

Value mapping converts a code value from one system's vocabulary into the equivalent code in another system's vocabulary. Each system uses its own codes for countries, currencies, units of measure, customer categories, and payment terms. These codes rarely match between systems. Value mapping defines the translation table so the integration converts them automatically.

A practical example: your e-commerce platform stores the country "United States" as the code "US". SAP stores the same country as "US" in some fields but "USA" in others, and some partner systems use the numeric ISO code "840". Value mapping holds all these equivalents in one place and converts between them on demand.

Without Value Mapping

SOURCE SYSTEM           GAP               TARGET SYSTEM (SAP)
─────────────           ───               ────────────────────
Unit: "EACH"            ≠                 Unit: "EA"
Unit: "PIECE"           ≠                 Unit: "PC"
Unit: "KILOGRAM"        ≠                 Unit: "KG"
Currency: "EUR"         =                 Currency: "EUR"  ← matches
Currency: "DOLLARS"     ≠                 Currency: "USD"
Payment: "NET30"        ≠                 Payment Terms: "NT30"
Payment: "IMMEDIATE"    ≠                 Payment Terms: "0001"

Without value mapping: all non-matching codes reach SAP as invalid values,
causing BAPI errors or IDoc posting failures.

The Value Mapping Table in CPI

CPI stores value mapping tables in a dedicated Value Mapping artifact. Each artifact contains one or more groups of value mappings. Each group maps values between two or more agency-identifier pairs.

Agency and Identifier

In CPI value mapping, every participant has an agency (the system or standard) and an identifier (the code type within that agency):

Agency: "Shopify"       Identifier: "UnitOfMeasure"
Agency: "SAP"           Identifier: "MEINH"

Mapping group:
  Shopify/UnitOfMeasure  |  SAP/MEINH
  ─────────────────────  |  ──────────
  EACH                   |  EA
  PIECE                  |  PC
  KILOGRAM               |  KG
  GRAM                   |  G
  LITER                  |  L

Creating a Value Mapping Artifact

In CPI Design, open your integration package and add a new artifact of type Value Mapping. Inside the value mapping editor:

Click Add Group to create a mapping group
Name the group (e.g., "Units of Measure")
Click Add Agency and enter the first agency name and identifier
Add the second agency and identifier
Add row entries — one row per code pair
Save and deploy the Value Mapping artifact

After deploying the Value Mapping artifact, any iFlow in the same package can reference it. The value mapping is deployed separately from iFlows, which means you can update the mapping table (add new rows, correct wrong values) and redeploy it without redeploying the iFlow. This separation of configuration from logic is a major advantage.

Using Value Mapping in a Graphical Message Mapping

In the message mapping editor, connect the source field to the target field as usual. Then add the built-in Value Mapping function between them:

SOURCE FIELD ──→ [Value Mapping Function] ──→ TARGET FIELD

Function configuration:
  Source Agency:     Shopify
  Source Identifier: UnitOfMeasure
  Target Agency:     SAP
  Target Identifier: MEINH
  Default Value:     EA     ← returned when no mapping found

The function looks up the source value in the mapping table and returns the corresponding target value. If the source value is "EACH", the function returns "EA" automatically.

Using Value Mapping in Groovy Script

You can also call value mapping from a Groovy script when the mapping logic requires conditional or programmatic access:

import com.sap.it.api.mapping.ValueMappingApi

def Message processData(Message message) {

    def vmApi = ITApiFactory.getApi(ValueMappingApi.class, null)

    def sourceUnit = message.getProperty("SourceUnit") as String

    // Look up the mapped value
    def sapUnit = vmApi.getMappedValue(
        "Shopify",      // source agency
        "UnitOfMeasure",// source identifier
        sourceUnit,     // source value to look up
        "SAP",          // target agency
        "MEINH"         // target identifier
    )

    if (sapUnit == null) {
        sapUnit = "EA"  // default fallback
        message.setProperty("ValueMappingFallback", "true")
    }

    message.setProperty("SAPUnit", sapUnit)

    return message
}

Handling Missing Mappings

What happens when a value arrives that has no mapping entry? This is a common situation — a supplier sends a new unit code that your mapping table does not yet include. Plan for this explicitly:

Default value approach: Return a default value (like "EA" for unknown units) and log a warning. Processing continues but the operations team knows about the unmapped code.
Hard fail approach: Throw an exception if the value has no mapping. Processing stops and the message goes to error handling. Use this when an unmapped value would cause serious business problems downstream.
Alert and continue: Continue with a default value AND send an alert notification so the missing mapping gets added before the next occurrence.

Bulk Import of Value Mappings

When you have hundreds of code pairs — for example, a complete mapping of all customer account groups between Salesforce and SAP — entering them row by row in the CPI editor takes too long. CPI supports importing value mapping tables from a CSV file:

CSV file format:
SourceAgency,SourceIdentifier,SourceValue,TargetAgency,TargetIdentifier,TargetValue
Salesforce,AccountType,PARTNER,SAP,KTOKD,0001
Salesforce,AccountType,DIRECT,SAP,KTOKD,0002
Salesforce,AccountType,DISTRIBUTOR,SAP,KTOKD,0003

Use this import capability when migrating value mappings from an existing SAP PI/PO system or when receiving a mapping specification from a business analyst in spreadsheet form.

Value Mapping for Master Data Alignment

One of the most important uses of value mapping in enterprise SAP landscapes is translating object identifiers between systems. Every system assigns its own ID to the same real-world entity:

ENTITY: Customer "ACME Corporation"
  Salesforce ID:     001ABC12345
  SAP Customer:      0000100023
  Workday Org:       ORG-ACME-2024
  Billing Platform:  BIL-93847

VALUE MAPPING TABLE:
  SF/AccountID  |  SAP/Kunnr      |  WD/OrgID        |  BIL/CustomerRef
  001ABC12345   |  0000100023     |  ORG-ACME-2024   |  BIL-93847

This cross-reference table allows any integration to translate between system IDs automatically. When Salesforce sends a customer ID, CPI looks it up in the value mapping and substitutes the SAP customer number before posting to SAP. Maintaining this master data cross-reference in the Value Mapping artifact makes it available to every iFlow without any code duplication.

Previous lesson

Back to course

Next lesson