---
title: "SFCC Integration Transformations Reference"
slug: "technical-documentation-template-2"
updated: 2025-11-21T12:47:42Z
published: 2025-11-21T12:47:42Z
canonical: "docs.newstore.com/technical-documentation-template-2"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SFCC Integration Transformations Reference

All available transformations in the [Ditto transformer system](https://www.npmjs.com/package/json-ditto) used for catalog data transformation are described in this section. The Ditto transformer uses a JSON-based mapping configuration with plugin functions to transform Salesforce Commerce Cloud ([SFCC](/v1/docs/sfcc-integration)) catalog data into NewStore format.

## **Syntax overview**

Transformations in Ditto use a special syntax where:

- `@functionName` - Calls a transformation function
- `>>value` - Hardcoded/literal value
- `>>%value` - Hardcoded value with type casting (e.g., `>>%true` for boolean)
- `!path` - Reference to a previously extracted value in the result object
- `path1||path2` - Fallback: use `path1` if available, otherwise `path2`
- `path??condition#comparator#value` - Conditional transformation
- `@function(param1|param2|param3)` - Function with multiple parameters separated by `|`
  - Please note: Nested functions require the ‘,’ (comma) separator, for example:

`@functionA(param1|@functionB(param2,param3))`

## **Before you begin**

- All transformation functions are case-sensitive
- Function parameters are separated by a `|` (pipe character)
- Hardcoded values must be prefixed with `>>`
- Boolean literals use `>>%true` or `>>%false`
- The `!` prefix references previously mapped values in the result object
- You can create fallback chains with `||` or `@defOr()`
- Array mappings require an `output` property specifying the output type (such as `[]` for arrays)
- The `innerDocument: "!"` syntax uses the entire document as the source for an array iteration
- `required` fields in array mappings cause the entire object to be excluded if **any** required field is missing

## **Path syntax**

### **Direct Path Access**

Accesses the `display-name` property from the `master` object.

```plaintext
"property": "master.display-name"
```

### **Hardcoded Values**

Sets the property to the literal string `"kg"`.

```plaintext
"property": ">>kg"
```

### **Boolean Casting**

Sets the property to the boolean `true` (not the string).

```plaintext
"property": ">>%true"
```

### **Fallback Values**

Uses `path1` if it exists, otherwise falls back to `path2`.

```plaintext
"property": "path1||path2"
```

### **Result Object Reference**

References a value from a previously mapped property in the result object.

```plaintext
"property": "!previousProperty"
```

### **Conditional Transformation**

Applies `targetValue` only if the condition is met. Supports operators: `===`, `==`, `!==`, `!=`.

```plaintext
"property": "source??targetValue#comparator#condition"
```

## **Default Plugins**

These plugins are available from the base Ditto library in `lib/plugins/`.

### **String Manipulation**

#### `@base64Encode(input)`

Base64 encodes a text string.

**Example:**

```plaintext
"encoded": "@base64Encode(master.product-id)"
```

#### `@cleanString(source)`

Cleans a string from special characters, HTML tags, and trailing dots and commas.

**Example:**

```plaintext
"clean": "@cleanString(master.display-name)"
```

#### `@cleanEmail(source)`

Normalizes an email by converting it to lowercase.

**Example:**

```plaintext
"email": "@cleanEmail(contact.email)"
```

#### `@cleanURI(source)`

Cleans a URI from special characters, HTML tags, and trailing dots and commas.

**Example:**

```plaintext
"url": "@cleanURI(master.link)"
```

#### `@normalizeString(source)`

Normalizes a string from special characters, HTML tags, trailing dots and commas, and converts to lowercase.

**Example:**

```plaintext
"normalized": "@normalizeString(master.display-name)"
```

#### `@parseString(source)`

Converts a value into a string by concatenating it with an empty space. Note: may lose double precision when converting numbers.

**Example:**

```plaintext
"string_value": "@parseString(master.price)"
```

### **String Concatenation**

#### `@concatName(...values)`

Concatenates one or more strings separated by a space.

**Example:**

```plaintext
"full_name": "@concatName(contact.firstName|contact.lastName)"
```

#### `@concatString(...values)`

Concatenates one or more strings without any separator.

**Example:**

```plaintext
"combined": "@concatString(prefix|master.product-id)"
```

#### `@concatWithComma(...values)`

Concatenates one or more strings joined with comma and space.

**Example:**

```plaintext
"tags": "@concatWithComma(tag1|tag2|tag3)"
```

### **Date Operations**

#### `@formatDate(date, [format], [isUtc])`

Formats a date according to parameters.

**Parameters:**

- `date` - Date object or string
- `format` (optional) - Format string
- `isUtc` (optional, default: `true`) - Whether to use UTC timezone

**Example:**

```plaintext
"formatted_date": "@formatDate(master.creation-date|YYYY-MM-DD|true)"
```

#### `@parseDate(date, [month], [day])`

Accepts a string or Date object, validates it, and returns a Date object or null.

**Example:**

```plaintext
"parsed_date": "@parseDate(master.creation-date)"
```

### **ID Generation**

#### `@generateId(...values)`

Creates an MD5 hash based on concatenating passed string values. Takes multiple arguments.

**Example:**

```plaintext
"id": "@generateId(master.product-id|variant.product-id)"
```

#### `@generateCleanId(...values)`

Creates an MD5 hash based on concatenating cleaned string values. Takes multiple arguments.

**Example:**

```plaintext
"clean_id": "@generateCleanId(master.display-name|variant.color)"
```

#### `@generateIdForLinks(source)`

Creates an MD5 hash for links. The function cleans the URIs before creating the MD5 hash.

**Example:**

```plaintext
"link_id": "@generateIdForLinks(master.link)"
```

#### `@generateIdFromLanguageCode(languageCode)`

Generates an ID from a language ISO code by doing a lookup first on the language value, then generating the ID from that.

**Example:**

```plaintext
"lang_id": "@generateIdFromLanguageCode(master.language)"
```

#### `@generateUUID()`

Creates a random UUID value.

**Example:**

```plaintext
"uuid": "@generateUUID()"
```

### **Language and Country**

#### `@getLanguageCode(source)`

Gets the language code and normalizes it, as well as the displayName of the language.

**Returns:** ISO language code

**Example:**

```plaintext
"lang_code": "@getLanguageCode(master.language)"
```

#### `@getLanguageFromCode(source)`

Gets the language displayName from a language code.

**Example:**

```plaintext
"lang_name": "@getLanguageFromCode(master.language-code)"
```

#### `@getCountryCode(countryCode, [country])`

Gets the ISO3 country code from an ISO2 country code and optional country name.

**Returns:** ISO3 country code

**Example:**

```plaintext
"country_code": "@getCountryCode(master.country-code|master.country-name)"
```

#### `@getCountryName(countryCode)`

Gets the country name given an ISO3 country code.

**Example:**

```plaintext
"country_name": "@getCountryName(master.country-code)"
```

### **Link Operations**

#### `@getLinkType(source)`

Identifies if the link is for a social website.

**Example:**

```plaintext
"link_type": "@getLinkType(master.social-link)"
```

#### `@getLinkService(source, service)`

Identifies the service provider of the link.

**Example:**

```plaintext
"service": "@getLinkService(master.link|facebook)"
```

#### `@createURL(url, source)`

Creates a URL from passed parameters.

**Example:**

```plaintext
"full_url": "@createURL(>>https://example.com|master.path)"
```

#### `@generateFacebookImageLink(facebookId)`

Generates a link for the Facebook profile photo based on the Facebook ID.

**Example:**

```plaintext
"fb_image": "@generateFacebookImageLink(contact.facebook-id)"
```

### **Array Operations**

#### `@splitList(input)`

Splits a list of items into an array.

**Example:**

```plaintext
"tags": "@splitList(master.tags)"
```

#### `@uniqueArray(target)`

Ensures array elements are unique.

**Example:**

```plaintext
"unique_tags": "@uniqueArray(master.tags)"
```

#### `@minBy(array, [path])`

Returns the minimum value (numerical or by character code) in an array. If only array is passed, assumes array is of numbers or strings. If path is passed, assumes array is of objects and uses the value that path resolves to.

**Example:**

```plaintext
"min_price": "@minBy(master.prices|value)"
```

### **Utility Functions**

#### `@getValueAtPath(object, path)`

Simple wrapper for lodash `get`. Returns the value at the specified path or undefined.

**Example:**

```plaintext
"nested_value": "@getValueAtPath(master|custom-attributes.0.value)"
```

#### `@extractName(fullName, position)`

Extracts a name component from a full name. Position can be `firstName`, `lastName`, or `middleName`.

**Returns:** String for firstName/lastName, Array for middleName

**Example:**

```plaintext
"first_name": "@extractName(contact.fullName|firstName)"
```

## **Custom Catalog Plugins**

These plugins are specific to the SFCC catalog transformation and are not specific to the Ditto library.

### **Language and Localization**

#### `@langTextVal(values)`

Extracts a localized text value based on the configured language priority. Takes an array of localized strings with `xml:lang` attributes.

**Example:**

```plaintext
"title": "@langTextVal(master.display-name)"
```

The function will select the value matching the highest priority language from `languagesPriority` in the config.

### **Site-Specific Values**

#### `@siteSpecificVal(values)`

Extracts a site-specific value based on the configured site priority. Takes an array of objects with `site-id` and `value` properties.

**Example:**

```plaintext
"is_active": "@siteSpecificVal(variant.online-flag)"
```

#### `@siteSpecificBool(values)`

Extracts a site-specific boolean value based on the configured site priority. Similar to `@siteSpecificVal` but specifically for boolean values.

**Example:**

```plaintext
"is_published": "@siteSpecificBool(variant.sitemap-included-flag)"
```

### **Custom Attributes**

#### `@customAttr(customAttributes, attributeId)`

Extracts a custom attribute value by ID, respecting language priority.

**Parameters:**

- `customAttributes` - Array of custom attribute objects
- `attributeId` - The attribute ID to extract (use `>>attributeId` for literal)

**Example:**

```plaintext
"color": "@customAttr(variant.custom-attributes|>>color)"
```

#### `@customAttrList(customAttributes, attributeId)`

Extracts a custom attribute list value by ID, respecting language priority. Returns an array of values.

**Example:**

```plaintext
"tags": "@customAttrList(master.custom-attributes|>>tags)"
```

### **Type Conversion**

#### `@toNumber(value)`

Converts a value to a number. Returns `undefined` if conversion fails.

**Example:**

```plaintext
"price": "@toNumber(master.price)"
```

#### `@toString(value)`

Converts a value to a string. Returns `undefined` if value is undefined.

**Example:**

```plaintext
"id_string": "@toString(master.product-id)"
```

### **Conditional Logic**

#### `@defOr(...values)`

Returns the first defined (not `undefined` or `null`) value from the arguments.

**Example:**

```plaintext
"description": "@defOr(master.long-description|master.short-description|>>Default description)"
```

#### `@defOrToNumber(...values)`

Returns the first defined value converted to a number. Useful for numeric fallbacks.

**Example:**

```plaintext
"weight": "@defOrToNumber(variant.weight|master.weight)"
```

#### `@boolOr(...values)`

Returns `true` if any value is truthy (and not the string `'false'`), otherwise `false`.

**Example:**

```plaintext
"is_active": "@boolOr(variant.online-flag|master.online-flag)"
```

#### `@falsyOr(...values)`

Returns `true` if any value is not `false` or the string `'false'`, otherwise `false`.

**Example:**

```plaintext
"is_published": "@falsyOr(variant.sitemap-included-flag|master.sitemap-included-flag)"
```

#### `@negate(value)`

Negates a boolean value.

**Example:**

```plaintext
"is_hidden": "@negate(master.visible-flag)"
```

### **String Operations**

#### `@concatSpace(...values)`

Concatenates string values with spaces. Returns `undefined` if the result is empty or only whitespace.

**Example:**

```plaintext
"description": "@concatSpace(master.short-description|master.long-description)"
```

#### `@htmlToText(html)`

Converts HTML content to plain text.

**Example:**

```plaintext
"plain_description": "@htmlToText(master.long-description)"
```

### **Image Operations**

#### `@simpleProductImages(images)`

Extracts product images based on the configured image include settings and path template.

**Example:**

```plaintext
"images": "@simpleProductImages(master.images)"
```

#### `@variantImages(images, variations, customAttributes)`

Extracts variant-specific images, considering variation attributes and custom attributes.

**Example:**

```plaintext
"images": "@variantImages(master.images|master.variations|variant.custom-attributes)"
```

### **Variation Attributes**

#### `@variationAttributeDisplayValue(variationAttributeId, variations, variationAttributeValue)`

Gets the display value for a variation attribute, respecting language priority.

**Example:**

```plaintext
"color_display": "@variationAttributeDisplayValue(>>color|master.variations|variant.color)"
```

### **Metadata**

#### `@variantWithoutMaster(meta)`

Returns whether the variant exists without a master product (from transformation metadata).

**Example:**

```plaintext
"is_standalone": "@variantWithoutMaster(meta)"
```

## **Usage Examples**

### **Basic Property Mapping**

```plaintext
{
  "properties_mapping": {
    "product_id": "variant.product-id",
    "title": "@langTextVal(master.display-name)",
    "description": "@htmlToText(@langTextVal(master.long-description))"
  }
}
```

### **Fallback Chain**

```plaintext
{
  "properties_mapping": {
    "caption": "@defOr(@concatSpace(@langTextVal(master.long-description))|@customAttr(master.custom-attributes,>>edwTitle))"
  }
}
```

### **Complex Conditional**

```plaintext
{
  "properties_mapping": {
    "is_active": "@falsyOr(@siteSpecificVal(variant.online-flag)|@siteSpecificVal(master.online-flag)|meta.variantWithoutMaster)"
  }
}
```

### **Array Mapping**

```plaintext
{
  "properties_mapping": {
    "external_identifiers": [
      {
        "output": [],
        "innerDocument": "!",
        "required": ["value"],
        "mappings": {
          "type": ">>ean13",
          "value": "@toString(variant.ean)"
        }
      }
    ]
  }
}
```

### **Nested Object Mapping**

```plaintext
{
  "properties_mapping": {
    "extended_attributes": [
      {
        "output": [],
        "innerDocument": "!",
        "required": ["value"],
        "mappings": {
          "name": ">>sizeAndFit",
          "value": "@customAttr(master.custom-attributes|>>sizeAndFit)"
        }
      }
    ]
  }
}
```

##