Modify data structures to enhance searches and navigation

In some cases, you can enhance the ease and accuracy of navigation or of searches on search terms by performing operations known as transformations on your data structures.

Oracle Commerce supports three types of transformations:

split-regex - Splits the value of a dimension or property and assigns each part of the split value to a new dimension or property.
split-jsonpath - Replaces the JSON value of a property with values that it extracts from the JSON.
concatenate - Concatenates the values of dimensions or properties into a single new dimension or property.

One or more transformations can be performed on a single attribute (property or dimension). Transformations are in all cases optional.

The following sections describe each of these transformations.

Configure a split-regex transformation

A split-regex transformation divides the value of a dimension or property into separate values and assigns each separate value to a new dimension or property.

This transformation is useful when the Catalog contains an attribute whose value is a delimited list of values. Such a list is not usable for user navigation. However, the split-regex transformation can split the list into separate values that are useful for navigation.

The transformation uses a regex pattern to determine where to split the dimension or property value. The pattern can be either a single character or a more complex regex pattern; for example, the following pattern specifies that a value is split at any occurrence either of two dashes or of a comma and a semicolon:

"(\-\-)|[,;]"

Suppose that your product data provides the following different values for a dimension named country:

"country": "UK, US, DE"

Although such an assignment is acceptable in the Catalog, is it not useful for user navigation by dimension. The split-regex transformation, however, can convert this assignment into ones that are useful for navigation, as follows:

"country": "UK",
"country": "US",
"country": "DE"

The conversion above is performed by the following split-regex transformation:

{
  "ecr:type": "attributes-owner-folder",
  "country": {
    "ecr:type": "dimension",
    "mergeAction": "update",
    "indexingTransforms": [
      {
        "transform": "split-regex",
        "pattern": ","
      }
    ],
    "ignoreDuplicatePropertyValues": "true"
  }
}

The following table lists the properties of the split-regex transformation:

Property	Data type	Default value	Comments
`"transform"`	String	n/a	Required. Must be set to `"split-regex"` Example: `"transform": "split-regex"`
`"splitPattern"`	String	none	Required. The regex pattern must comply with `java.util.regex.Pattern`. Example: `"splitPattern": "[,;\t]"`
`"sourcePropertyNames"`	JSON Array	The name of the attribute to which this transform applies.	Optional. Example: `"sourcePropertyNames": [` `"shirt.color",` `"dress.color",` `"pants.color"` `]`
`"ignoreDuplicate` `PropertyValues"`	Boolean	True	Optional. Example: `"ignoreDuplicatePropertyValues":false`
`"trimWhitespace"`	Boolean	True	Optional. Example: `"trimWhitespace": false`
`"removeSourceProperty` `Values"`	Boolean	True when the source property is the same as the attribute name. False otherwise.	Optional.

Configure a split-jsonpath transformation

The split-jsonpath transformation extracts values from a specified location in the JSON value of a specified property. The transformation replaces the JSON value of the property with the extracted values. No other properties are created or modified by this transformation.

For example, suppose that the following JSON has been assigned as the value of a property named product.shoeSize:

{
  "product.name": "Suede Shoes",
  "product.childSKUs": [
    {
      "sku.id": "1000-R-M8",
      "shoe.color": "Red",
      "shoe.size": "8"
    },
    {
      "sku.id": "1000-B-M8",
      "shoe.color": "Blue",
      "shoe.size": "8"
    },
    ...
  ]
}

The following split-jsonpath transformation replaces the JSON value of the property product.shoeSize with values that it extracts from the JSON value:

{
  "ecr:type": "attributes-owner-folder",
    "product.shoeSize": {
       "ecr:type": "dimension",
       "isAutogen": true,
       "indexingTransforms": [
           {
                "transform": "split-jsonpath",
                "sourcePropertyNames": [
                    "product.shoeData"
                 ],
                "splitPaths": [
                    "$['product.childSKUs'][*]['shoe.size']"
                ]
           }
       ]
    }
}

The split-jsonpath transformation assigns the extracted values to product.shoeData as follows:

"product.shoeSize": "8"

The following table lists the properties of a split-jsonpath transformation:

Property	Data type	Default value	Comments
`"transform"`	String	N.A.	Required. Must be set to `"split-jsonpath"` Example: `"transform": "split-jsonpath"`
`"sourcePropertyNames"`	JSON Array	The attribute name to which this transform belongs	Optional. Example: `"sourcePropertyNames":` `[ "product.data" ]`
`"removeSourceProperty` `Values"`	Boolean	True when the source property is identical to the attribute. False otherwise.	Optional. Example: `"removeSourcePropertyValues": true`
`"ignoreDuplicate` `PropertyValues"`	Boolean	True	Optional. Example: `"ignoreDuplicatePropertyValues": false`
`"splitPaths"`	JSON Array	Not applicable	Required when it is not an identity transform. The array values must comply with `com.jayway.jsonpath.JsonPath`. Example: `"splitPaths": [` `"$['childSKUs'[*]['id']"` `]` Note: When `splitPaths` is not specified for an identity transform, then the source property values will be parsed as a JSON Path and the resulting JSON key:value pairs will be added to the record.

Configure a concatenate transformation

A concatenate transformation can combine the following:

The different values of a multi-assigned property, or the values of two or more different properties.
The values of two or more dimensions.

The concatenated values are assigned to a single new dimension or property.

To include the new property in searches, you must add it to the fields array of your search interface.

You can concatenate localized properties with non-localized properties. The resulting property is localized. You cannot, however, concatenate properties that are localized to different locales.

For example, the following JSON example creates a record property named all.colors and assigns to it, as a single unitary value, the concatenated values of the existing record properties shirt.color, dress.color, and pants.color:

{
"ecr:type": "attributes-owner-folder",
"all.colors": {
    "propertyDataType": "ALPHA",
    "ecr:type": "property",
    "indexingTransforms": [
        {
            "transform": "concatenate",
            "sourcePropertyNames": [
                "shirt.color",
                "dress.color",
                "pants.color"
            ]
        }
    ]
  }
}

For example, suppose that values are assigned to the source properties as follows:

"shirt.color": "Red",
"dress.color": "Yellow, Black, Red",
"pants.color": "Orange"

The concatenate transformation above assigns the follow value to the output property all.colors:

"all.colors": "Red Yellow, Black, Red Orange"

The following table lists the properties of a concatenate transformation:

Property	Data type	Default value	Comments
`"transform"`	String	Not applicable	Required. Must be set to `"concatenate"` Example: `"transform": "concatenate"`
`"sourcePropertyNames"`	JSON Array	The attribute name to which this transformation belongs.	Optional. Example: `"sourcePropertyNames":` `[ "product.brand_name", "product.color" ]`
`"removeSourcePropertyValues"`	Boolean	True when the source property is equivalent to the attribute name. False otherwise	Optional. Example: `"removeSourcePropertyValues": true`
`"ignoreDuplicatePropertyValues"`	Boolean	True	Optional. Example: `"ignoreDuplicatePropertyValues": false`

Disable transformations on a property or a dimension

The system owner can disable transformations on a property or dimension specified by non-system owners. To do this, specify an empty indexingTransforms attribute.

The following example disables transformations by non-system owners on the property named product.color:

"product.color": {
     "ecr:lastModifiedBy": "admin",
        "propertyDataType": "ALPHA",
        "indexingTransforms": [],
        "ecr:type": "property"
    }

Applying transformations

Transformations are applied by POST or PUT REST API calls of the following form:

POST | PUT /gsadmin/v1/${appName}/attributes/${owner}

For example:

POST /gsadmin/v1/attributes/owner1

When both the system owner and a non-system owner specify transformations, the transformation specified by the system owner is used. However, when only a non-system owner specifies a transformation, the non-system owner’s transformation is used.

For more information about how to make POST and PUT calls, see Understand how to execute endpoints.