Value mapping lookups in SAP Integration Suite Groovy scripts (ValueMappingApi)

Value mappings in SAP Integration Suite translate a value from one system's vocabulary to another's, for example a country code from S/4HANA to SuccessFactors. Besides the message mapping functions, a Groovy script can read them directly with ValueMappingApi. This guide shows the API, the usual pitfalls, and how to test lookups without a tenant.

The API

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

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

// one value (or null when there is no mapping)
String target = vm.getMappedValue(sourceAgency, sourceIdentifier, sourceValue, targetAgency, targetIdentifier)

// all values mapped to the source value
List<String> targets = vm.getMappedValues(sourceAgency, sourceIdentifier, sourceValue, targetAgency, targetIdentifier)

The five parameters mirror a value mapping entry: agency (the system, e.g. S4) and identifier (the scheme, e.g. Country) on each side, plus the value to translate.

Complete example

import com.sap.gateway.ip.core.customdev.util.Message
import com.sap.it.api.ITApiFactory
import com.sap.it.api.mapping.ValueMappingApi

def Message processData(Message message) {
    def order = new XmlSlurper().parseText(message.getBody(String))
    def source = order.Customer.Country.text()

    def vm = ITApiFactory.getApi(ValueMappingApi.class, null)
    def target = vm.getMappedValue('S4', 'Country', source, 'SF', 'Country')

    // decide explicitly what happens without a mapping
    message.setHeader('SF_Country', target ?: source)
    message.setProperty('CountryMapped', target != null)
    return message
}

Common pitfalls

• No mapping returns null, not an exception. Handle it: use a default value, or throw an exception to fail the message on purpose.
• Agencies and identifiers must match what is defined in the value mapping artifact: a typo simply finds nothing.
• Direction: swapping source and target agency/identifier reads the same entry the other way round.
• Deployment: on the tenant the value mapping artifact must be deployed, otherwise lookups find nothing.
• Many lookups: get the API once per script run and reuse it in loops.

Test lookups without a tenant

1. Open the GrooveBox playground and paste the script.
2. In the Value Mapping tab add the entries (source agency, identifier, value, target agency, identifier, value), or import them from a CSV file or from the value_mapping.xml contained in an exported value mapping artifact.
3. Run the script. The API output tab lists every getMappedValue call with its arguments and result, so you can see immediately which lookup found nothing.
4. Try a value without a mapping to check how the script behaves in that case.

More on testing: How to test SAP Integration Suite Groovy scripts without deploying an iFlow.