Generic Mapping

The generic mapping capability enables you to map keys to values, with the mapping stored in a high-performance in memory data store that is independent from the database. This supports large datasets, with high performance for lookup.

An example of using this feature is to map SKUs from a backend system to Salesforce B2C Commerce SKUs on-the-fly in B2C Commerce script, so that interaction with the backend system is transparent and doesn't require adding B2C Commerce SKUs to the third party system.

By using generic mapping, Commerce Cloud customers can access in-memory key/value pairs that complement product data in the database.

Steps to Use Generic Mapping

Generally, you follow these steps in using Generic Mapping:

  1. Create the mapping.
  2. Create a pipeline to call the com.demandware.pipelet.impex.ImportKeyValueMapping pipelet.
  3. Import the mapping to the B2C Commerce server.
  4. Use DS script to read values from the mapping.

Create the Mapping

To be able to use Generic Mapping, you create a CSV (comma separated value) file to store the mapping. Creating the .csv file properly is essential. When creating the .csv file, follow these guidelines:

The format for each line of the .csv file is:


The first row of the .csv file defines the property names for the key/value entries. The key/value entires start in row 2. The generic mapping contains one fewer entry than the number of rows in the .csv file. When you call MappingMgr.get(mapping, key), you get a new map with the property names as keys.

If malformed records are encountered, the import fails with an exception that is logged.

Before being able to import a mapping, upload it to a place accessible by the app server, for example by using a Business Manager upload page or FTP. Mappings must be explicitly imported on each instance. Mappings are global (not just site-specific).

Mapping files are limited to 20MB, which is approximately equivalent to 1M records of 20 bytes and a maximum of 20 mappings.

Create a Pipeline

To be able to import the mapping, you create a pipeline that calls the com.demandware.pipelet.impex.ImportKeyValueMapping pipelet. The pipelet transforms .csv files into in-memory key-value mapping, and notifies all app servers in a cluster that there is a new mapping. This pipelet supports the REPLACE, DELETE, and MERGE import modes.

Upload the Mapping

Uploading the mapping makes it accessible.

To upload the .csv file using Business Manager:

  1. Select Administration > Site Development > Import & Export.
  2. Under Import & Export Files, click Upload and select the CSV file.

Alternatively, you can upload the .csv file to thepImpex directory by using WebDAV or httpClient.

Run a Job to Call the Pipeline (Optional)

If you need to automate generic mapping imports, you can create a job to call the pipeline just as you do any other job.

Read Values from the Mapping

To use the mapping, you use B2C Commerce script.

The dw.util.MappingMgr class, with the following methods, enables you to access mapping data.

See the API documentation for details.