Blog > SAP CPI Value Mapping Maintenance

SAP CPI Value Mapping Maintenance

Tomasz Maćkowski SAP Solution Architect & Full-Stack Developer
icon__calendar 2020-05-12

Value Mapping artifacts in SAP Cloud Platform Integration

In this blog I will summarize existing options for maintenance of Value Mapping artifacts in SAP Cloud Platform Integration and describe additional possibilities available with recent release (04-2020).

You will learn:

  • What is a Value Mapping artifact in SAP Cloud Platform Integration
  • How to upload it from CSV and zip files
  • How to automate maintenance of Value Mapping with available APIs

Value Mapping artifact is used in SAP Cloud Platform Integration to map values between different representations or formats. Example use cases for Value Mapping are:

  • Mapping language codes, units of measures which are represented differently in source and target system
  • Mapping product codes, order types, reason codes.


Value Mapping artifacts are created and configured in SAP CPI Web UI:

Value mapping maintenance screen

Value Mapping maintenance screen


Working with large Value Mapping datasets in Web UI can be challenging in terms of manual creation and ongoing maintenance effort. 


Recently SAP released an OData API to access Value Mappings:


CPI release notes



Source CPI Release Notes


I decided to review it and check if it brings any significant changes in this area.

Below I will summarize existing options which can be used to automate the Value Mapping maintenance process and describe the new possibilities which come with API addition.


1. Upload of Value Mapping pairs from CSV

It is possible to upload value mapping mairs from CSV files.

See the blog: from Deepak Govardhanrao Deshpande for details.

This approach doesn’t work very well in case of one to many mappings where you upload multiple target values for the same source value. This issue and workaround is described in SAP Support Note 2866537( Unable to import CSV file while configuring value mapping on CPI tenant ) . The workaround involves manipulation of source file and manual update of target values in CPI web UI after the upload which is not very practical if you have hundreds of values to be mapped.


2. Download artifact as zip and update enclosed value_mapping.xml

The option to download Value Mapping artifact and upload of updated value_mapping.xml was described in blog from Martin Pankraz .

Dominic Beckbauer further developed this idea to wrap the process in an iflow and described it in

This approach is a big improvement but requires manual download and upload of artifacts and working with zip files.

3. (NEW) Use Value Mapping OData V2 API


Value Mapping OData V2 API is available as of 2020-04-11

Following operations are supported by the API:

  • Query All Value Mappings in the tenant

GET https://<account>$format=json

Example response for this package:


Int4 Value Mapping examples




Filtering by package is not supported.

Following query:

https://<account>$filter=PackageId eq ‘TMint4ValueMappingExamples’


Returns Not Implemented Error:


It is however possible to navigate to Value Mappings from Integration Package entity:



Returns Value Mappings in selected ‘TMint4ValueMappingExamples’ package.


  • Read details of single Value Mapping


GET https://<account>’ValueMapping1′,Version=’1.0.0′)?$format=json

This request provides only basic metadata information about the mapping:


  • Download Value Mapping


GET https://<account>’ValueMapping1′,Version=’1.0.0′)/$value 

This request downloads Value mapping artifact as zip file. It is the same format as provided by download option in Web UI:


Download Value Mapping



  • Upload Value Mapping


This request uploads Value Mapping artifact. Zip content has to be base64 encoded and provided in ArtifactContent property. X-CSRF-Token has to be provided in request header.

POST /ValueMappingDesigntimeArtifacts:



Int4 Value Mapping Examples 2


Unfortunately there is no option to update or overwrite existing mapping with this API.

Sending the request again for the same Value Mapping results in:


Adding Overwrite=true url parameter which is available for  IntegrationPackages entity set results in:

  • Deploy Value Mapping

POST https://<account>’ValueMapping1.1’&Version=’1.0.0′ with empty body deploys the Value Mapping:


Overview Manage Integration Content

Summary: New OData V2 API for Value Mapping enables automation of mapping maintenance and could be used to further enhance already described methods of  value_mapping.xml update.


I see two biggest limitations of this APi:

  • Lack of direct access to mapping values – you still have to work with zip files
  • No support of updating/overwriting existing mapping. Only new mappings can be uploaded.

Official API documentation


  • (BONUS) Unofficial API for Value Mappings


OData V2 API for Value Mapping is a step in the right direction but it still lacks some important pieces to provide a way to conveniently manipulate large Value Mapping data sets.


I decided to explore other options and look under the hood of CPI Web UI.

CPI Web UI uses workspace services available under:

  1. https://<account> 
  2. https://<account> urls.


Workspace service provides convenient access to Value Mapping data sets and an easy way to update them.


Let’s take following mapping as an example:


Value Mapping Int4



First we use OData service to get the package and value mapping Id

GET https://<account>‘TMint4ValueMappingExamples’)?$format=json


Returns details about the package including internal ID which will be used later.






Return list of all artifacts in the package including Value Mappings.



Then we switch to the second REST API to read the actual mapping:


https://<account><package id>/artifacts/<mapping id>/entities/<mapping id>/valuemappings/<mapping id>



Returns Value Mapping entries:



Same endpoint can be used to update the value mapping. You can add new entries to the JSON file with the same parent id and new GUID as id.

JSON file same parent



https://<account> with modified JSON as body will update the mapping.


There are two important steps for this update to work:

  1. X-CSRF-Token header has to be provided or you will get 403 Forbidden error
  2. Value mapping has to first locked for editing in current session or you will get 500 Resource not locked error

Value mapping can be locked with:



Value Mapping


Workspace API is not officially released but it provides very convenient methods to read and update Value Mappings. It enables you to fully automate maintenance of large mapping data sets. Direct access to mapping values and update of existing sets including one to many scenarios is supported.

Value Mapping JSON format required for the update request is straightforward and payload can be generated for example using Groovy script:




Tomasz Maćkowski SAP Solution Architect & Full-Stack Developer
Working with SAP technologies since 2004. Tomasz has extensive experience in architecting and developing SAP product enhancements as well as custom solutions built on the SAP technology stack. Big fan and practitioner of automation in all aspects of the software development lifecycle.