All available transformations in the Ditto transformer system 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) 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.,>>%truefor boolean)!path- Reference to a previously extracted value in the result objectpath1||path2- Fallback: usepath1if available, otherwisepath2path??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
>>%trueor>>%falseThe
!prefix references previously mapped values in the result objectYou can create fallback chains with
||or@defOr()Array mappings require an
outputproperty specifying the output type (such as[]for arrays)The
innerDocument: "!"syntax uses the entire document as the source for an array iterationrequiredfields 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.
"property": "master.display-name"
Hardcoded Values
Sets the property to the literal string "kg".
"property": ">>kg"
Boolean Casting
Sets the property to the boolean true (not the string).
"property": ">>%true"
Fallback Values
Uses path1 if it exists, otherwise falls back to path2.
"property": "path1||path2"Result Object Reference
References a value from a previously mapped property in the result object.
"property": "!previousProperty"Conditional Transformation
Applies targetValue only if the condition is met. Supports operators: ===, ==, !==, !=.
"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:
"encoded": "@base64Encode(master.product-id)"
@cleanString(source)
Cleans a string from special characters, HTML tags, and trailing dots and commas.
Example:
"clean": "@cleanString(master.display-name)"
@cleanEmail(source)
Normalizes an email by converting it to lowercase.
Example:
"email": "@cleanEmail(contact.email)"
@cleanURI(source)
Cleans a URI from special characters, HTML tags, and trailing dots and commas.
Example:
"url": "@cleanURI(master.link)"
@normalizeString(source)
Normalizes a string from special characters, HTML tags, trailing dots and commas, and converts to lowercase.
Example:
"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:
"string_value": "@parseString(master.price)"
String Concatenation
@concatName(...values)
Concatenates one or more strings separated by a space.
Example:
"full_name": "@concatName(contact.firstName|contact.lastName)"
@concatString(...values)
Concatenates one or more strings without any separator.
Example:
"combined": "@concatString(prefix|master.product-id)"
@concatWithComma(...values)
Concatenates one or more strings joined with comma and space.
Example:
"tags": "@concatWithComma(tag1|tag2|tag3)"
Date Operations
@formatDate(date, [format], [isUtc])
Formats a date according to parameters.
Parameters:
date- Date object or stringformat(optional) - Format stringisUtc(optional, default:true) - Whether to use UTC timezone
Example:
"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:
"parsed_date": "@parseDate(master.creation-date)"
ID Generation
@generateId(...values)
Creates an MD5 hash based on concatenating passed string values. Takes multiple arguments.
Example:
"id": "@generateId(master.product-id|variant.product-id)"
@generateCleanId(...values)
Creates an MD5 hash based on concatenating cleaned string values. Takes multiple arguments.
Example:
"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:
"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:
"lang_id": "@generateIdFromLanguageCode(master.language)"
@generateUUID()
Creates a random UUID value.
Example:
"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:
"lang_code": "@getLanguageCode(master.language)"
@getLanguageFromCode(source)
Gets the language displayName from a language code.
Example:
"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:
"country_code": "@getCountryCode(master.country-code|master.country-name)"
@getCountryName(countryCode)
Gets the country name given an ISO3 country code.
Example:
"country_name": "@getCountryName(master.country-code)"
Link Operations
@getLinkType(source)
Identifies if the link is for a social website.
Example:
"link_type": "@getLinkType(master.social-link)"
@getLinkService(source, service)
Identifies the service provider of the link.
Example:
"service": "@getLinkService(master.link|facebook)"
@createURL(url, source)
Creates a URL from passed parameters.
Example:
"full_url": "@createURL(>>https://example.com|master.path)"
@generateFacebookImageLink(facebookId)
Generates a link for the Facebook profile photo based on the Facebook ID.
Example:
"fb_image": "@generateFacebookImageLink(contact.facebook-id)"
Array Operations
@splitList(input)
Splits a list of items into an array.
Example:
"tags": "@splitList(master.tags)"
@uniqueArray(target)
Ensures array elements are unique.
Example:
"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:
"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:
"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:
"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:
"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:
"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:
"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 objectsattributeId- The attribute ID to extract (use>>attributeIdfor literal)
Example:
"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:
"tags": "@customAttrList(master.custom-attributes|>>tags)"
Type Conversion
@toNumber(value)
Converts a value to a number. Returns undefined if conversion fails.
Example:
"price": "@toNumber(master.price)"
@toString(value)
Converts a value to a string. Returns undefined if value is undefined.
Example:
"id_string": "@toString(master.product-id)"
Conditional Logic
@defOr(...values)
Returns the first defined (not undefined or null) value from the arguments.
Example:
"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:
"weight": "@defOrToNumber(variant.weight|master.weight)"
@boolOr(...values)
Returns true if any value is truthy (and not the string 'false'), otherwise false.
Example:
"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:
"is_published": "@falsyOr(variant.sitemap-included-flag|master.sitemap-included-flag)"
@negate(value)
Negates a boolean value.
Example:
"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:
"description": "@concatSpace(master.short-description|master.long-description)"
@htmlToText(html)
Converts HTML content to plain text.
Example:
"plain_description": "@htmlToText(master.long-description)"
Image Operations
@simpleProductImages(images)
Extracts product images based on the configured image include settings and path template.
Example:
"images": "@simpleProductImages(master.images)"
@variantImages(images, variations, customAttributes)
Extracts variant-specific images, considering variation attributes and custom attributes.
Example:
"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:
"color_display": "@variationAttributeDisplayValue(>>color|master.variations|variant.color)"
Metadata
@variantWithoutMaster(meta)
Returns whether the variant exists without a master product (from transformation metadata).
Example:
"is_standalone": "@variantWithoutMaster(meta)"
Usage Examples
Basic Property Mapping
{
"properties_mapping": {
"product_id": "variant.product-id",
"title": "@langTextVal(master.display-name)",
"description": "@htmlToText(@langTextVal(master.long-description))"
}
}
Fallback Chain
{
"properties_mapping": {
"caption": "@defOr(@concatSpace(@langTextVal(master.long-description))|@customAttr(master.custom-attributes,>>edwTitle))"
}
}
Complex Conditional
{
"properties_mapping": {
"is_active": "@falsyOr(@siteSpecificVal(variant.online-flag)|@siteSpecificVal(master.online-flag)|meta.variantWithoutMaster)"
}
}
Array Mapping
{
"properties_mapping": {
"external_identifiers": [
{
"output": [],
"innerDocument": "!",
"required": ["value"],
"mappings": {
"type": ">>ean13",
"value": "@toString(variant.ean)"
}
}
]
}
}
Nested Object Mapping
{
"properties_mapping": {
"extended_attributes": [
{
"output": [],
"innerDocument": "!",
"required": ["value"],
"mappings": {
"name": ">>sizeAndFit",
"value": "@customAttr(master.custom-attributes|>>sizeAndFit)"
}
}
]
}
}