Value mapping artifacts

A Value Mapping artifact is a bidirectional lookup table that sits in an integration package next to your flows. SAP describes the purpose simply: the same object is identified differently across systems, and the value mapping translates between the representations during processing. Because it is a separate artifact, the business can change a code without anyone touching a mapping or a flow.

Agencies and identifiers

Every value in a value mapping is described by two names. The agency says who issues the code: a system, a partner or a standards body. The identifier (PI called it the scheme) says which code list it is. A bi-directional mapping pairs a source agency and identifier with a target agency and identifier, and holds the value pairs between them. Agree a naming convention before the first table, because every mapping that calls the table has to use exactly these strings.

Creating and editing a value mapping

1. Open the integration package in edit mode and choose Artifacts > Add > Value Mapping.
2. Choose Create and enter a name such as CMC_UNIT_CODES, or Upload an existing value mapping artifact from your computer.
3. Open the artifact in edit mode. In the Bi-Directional mapping section choose Add and enter the source and target agency and identifier.
4. In the Value mappings for section choose Add and enter each value pair, or Import a CSV file (lesson 3).
5. Save, use Save as version to keep a copy, then Deploy. Only deployed content is used at runtime.

Both directions, and the default values tab

The same table works both ways. Outbound, Contoso translates CMC_S4 / UNIT value PCE to X12 / UNIT value EA. Inbound, Lakeside's 810 invoice with EA is translated back to PCE with the same entries. The catch is ambiguity: if two source values point to the same target (say both PCE and ST map to EA), the reverse lookup has two candidates. SAP handles this with generated default values that you can change on the Default Values tab, where you choose which value the reverse direction returns.

Calling a value mapping

In a message mapping, use the Value Mapping function from the Conversions category. Its parameters name the source agency and identifier and the target agency and identifier, exactly as entered in the artifact. It also asks what to do when no entry is found. The options are to pass the key through unchanged, to use a default value, or to throw an exception, and the choice is a business decision (lesson 5). In a Groovy script, SAP's example reads the same table through the script API: def api = ITApiFactory.getService(ValueMappingApi.class, null)
def x12Unit = api.getMappedValue('CMC_S4', 'UNIT', 'PCE', 'X12', 'UNIT')
with imports com.sap.it.api.ITApiFactory and com.sap.it.api.mapping.ValueMappingApi.

Common mistakes

• Agency or identifier typos in the calling mapping: the lookup never matches, and with pass-through nobody notices.
• Two artifacts for one code list: two deployed copies of the same agency and identifier pairs, which SAP advises against.
• Saved but not deployed: the editor shows the new value, the runtime still uses the old one.
• Ambiguous reverse lookups: several source values for one target, with the Default Values tab left unchecked.
• Business rules disguised as codes: a table that decides routing or pricing belongs in a design discussion, not in a lookup.

Describe the table where people will look

A value mapping is read by people as often as by flows: the business owner checking a code, a tester designing cases, the support team at 03:00. Use the artifact's description for the essentials: what the table translates, its business owner, the not-found behavior that calling mappings use, and any tenant-specific configured values. Contoso also keeps the agency and identifier strings in the description, because a typo in a calling mapping is the most common defect with value mappings and the description is where developers copy them from.

Value mappings in the landscape

A value mapping is transported like any other package artifact. Contoso builds and edits tables in CMC_DEV, and they move with the package through CMC_TEST to CMC_PROD on the BTP transport path. Priya forwards from CMC_TEST only after the translation tests pass, and CMC_PROD imports in the approved release window. Because the table travels on its own, it can move without the flows that read it, which is the point: a new unit code can go live in a week, without touching a mapping. It also means a table change needs its own test and its own release note.