Data transformation

Data transformation lets you create computed attributes that don't exist as-is in Akeneo, and use them in your native field and metafield mappings exactly like a native PIM attribute. A computed attribute can hold a simple constant value, or a value derived from one or more Akeneo attributes through an expression.

What is a data transformation attribute?

A data transformation attribute is a virtual attribute that you define directly in the app, in the Data Transformation tab. Once created, it behaves like any other Akeneo attribute in your mapping screens: you can select it as the source of a native field, or a metafield - both at the product, product model, and variant level.

You define your data transformation attributes by writing a JSON list directly in the app's editor, in the Data Transformation tab - there's no drag-and-drop form for this yet.

Each data transformation attribute has:

• A Default value, used whenever no transformation is configured, or whenever a transformation returns an empty result.
• An optional Transformation, a rule that computes the attribute's value from one or more Akeneo attributes each time a product is synchronized.

This lets you cover two use cases:

• Constant values that have no equivalent Akeneo attribute (for example, a fixed compliance label to push to every product).
• Computed values built from existing Akeneo attributes (for example, combining a product's name with a reference data label into a single text value).

Supported attribute types

This is the type of the data transformation attribute itself, that is, the value your transformation produces as output. Today, it is always Text.

Transformation rules

A transformation rule reuses the same transformation service that powers the Transformation block of Akeneo's Catalogs for apps: it computes an attribute's value from one or more Akeneo attributes using that service's expression language. The expression is evaluated by Akeneo on real product data every time the app fetches the attribute's value.

Supported Akeneo attribute types for transformations

Each transformation rule lists, in a pim_attributes array, the Akeneo attributes its expression is allowed to use as input. Unlike the output of the transformation, which is always Text (see Supported attribute types above), these source attributes can be of several types. The following table lists which Akeneo attribute types can currently be referenced this way.

Writing an expression

An expression references the Akeneo attributes declared in pim_attributes - not to be confused with the code you set on the data transformation attribute itself in Step 2 below. In the expression, each entry of pim_attributes is referenced by its alias when one is set, or by the Akeneo attribute's own code otherwise. An alias is only required when the same Akeneo attribute is listed more than once, for example once to read its code and once its label (see the example further down). Expressions combine these references using functions. The following functions are available:

Functions can be nested; the most deeply nested function is evaluated first, for example CONCATENATE(name, ': ', CLEANHTML(description)).

For more details on each function, see the Akeneo function list. For tips on building an expression step by step, see best practices to onboard the DSL transformation block easily.

Prepare your mapping

Step 1: Open the Data Transformation tab

In your Shopify app, go to the Data Transformation tab, located between Configuration and Products.

Step 2: Define a data transformation attribute

Open the configuration helper panel and use its Attribute tab to see the supported attribute types, view a JSON example, and copy a ready-to-use template into the editor with Add template. Then edit the generated entry:

1. Set a unique code for the attribute (lowercase letters, digits, and underscores only).
2. Set the type (currently pim_catalog_text).
3. Optionally set a label and a default_value.

Step 3: Add a transformation rule (optional)

To compute the attribute's value instead of relying only on the default value, use the Transformations tab of the configuration helper. From there you can view the transformation's properties, copy a template with Copy template, or use Add template with Value transformation rule directly next to an attribute template. Then edit the generated transformations entry:

1. List the Akeneo attributes the expression needs in pim_attributes, each with a code.
2. Add an alias when an attribute is referenced more than once, or when you need a clearer name to use in the expression.
3. Add a property when you need a sub-value of the attribute instead of its raw value, for example the code or label of a simple or multi select option.
4. Write the expression, referencing each attribute by its alias (or its code if no alias is set).

Step 4: Save your mapping

Click Save. The app validates your JSON mapping before saving it. The following rules apply:

• Each attribute code must be unique, and each label, when set, must be unique.
• An attribute can have at most one transformation.
• An attribute that is already used in a Product, Product variant, or Metafield mapping cannot be removed or have its code changed.
• Each transformation rule is tested against a sample product; a rule that the expression engine rejects (for example, an invalid expression, or a referenced attribute that doesn't exist) blocks saving until it's fixed.

JSON mapping template

[
    {
        "code": "",
        "type": "pim_catalog_text",
        "label": "",
        "default_value": "",
        "transformations": [
            {
                "type": "value_transformation_rule",
                "pim_attributes": [
                    { "code": "" }
                ],
                "expression": ""
            }
        ]
    }
]

JSON mapping example

The example below defines two data transformation attributes: a constant value with no transformation, and a computed value built from the product's name and the code and label of a country_of_origin simple select attribute.

[
    {
        "code": "compliance_label",
        "type": "pim_catalog_text",
        "label": "Compliance label",
        "default_value": "N/A"
    },
    {
        "code": "origin_summary",
        "type": "pim_catalog_text",
        "label": "Origin summary",
        "default_value": "N/A",
        "transformations": [
            {
                "type": "value_transformation_rule",
                "pim_attributes": [
                    { "code": "name" },
                    { "alias": "country_code", "code": "country_of_origin", "property": "code" },
                    { "alias": "country_label", "code": "country_of_origin", "property": "label" }
                ],
                "expression": "CONCATENATE(name, ' - ', country_code, ' - ', country_label)"
            }
        ]
    }
]

Field descriptions

Use your data transformation attributes in mapping

Once saved, a data transformation attribute appears in the attribute picker of your Products, Products with variants, and Metafields mapping screens, next to your regular Akeneo attributes. Select it as the source of any field or metafield exactly as you would a native PIM attribute, then save your mapping as usual.

The transformation is recomputed on each synchronization, so the value pushed to Shopify always reflects the current Akeneo data.