Constructor connectors leverage transformation templates to allow you to customize how your data is ingested. While partner connectors provide a base layer of transformation, the Omni Connector relies on you to specify how the data is transformed.

There are three types of transformation templates:

• Item: Allows you to customize how your Constructor items are transformed.
• Variation: Allows you to customize how your Constructor variations are transformed.
• Item Group: Allows you to customize how your Constructor item groups are transformed.

Keep in mind that fixtures stored in the repository represent the data that flows through a connector in a live integration. It will always follow the same structure, so you can refer to a fixture to see how to reach for the pieces of data you want to use.

Each transformation template is expected to return an object with the data that should be ingested. This data mostly follows the CSV Feed Format for items, variations, and item groups, but note that templates might provide additional fields to expose connector features.

Data structure

As mentioned preceding, each template is expected to return a specific set of fields to be ingested.

Note that in templates, fields are optional. For the case of partner connectors, not returning a field means you will not override what the connector is doing, and for the Omni Connector, not returning a field means that Constructor will not ingest it.

Please note that not returning a required field (for example, id) might cause your ingestion to fail.

Item template

The item template is expected to return an object containing the following fields:

Variation template

The variation template is expected to return an object containing the following fields:

Item group template

The item group template is expected to return an object containing the following fields:

Note that any JSON data can be ingested into the item group data field, similarly to how metadata works with JSON.

🚧

A note on parent_ids

Fields parent_ids and parent_id are mutually exclusive and should not be present in the template simultaneously. When using parent_ids make sure to also inject the root group with id all to preserve the hierarchy.

Metadata

Both items and variations can ingest Metadata to define extended fields.

Metadata can be defined in two ways - either as an object or an array of key-value pairs.

Object metadata

The simplest use case is to define your metadata in a single object. In this case, the fields are parsed as the keys and values as values.

Here's an example on how to define your metadata in an object:

{
  "metadata": {
    "allergens": "gluten",
    "rating": 4.99,
    "reviews": [
      {
        "author": "John Doe",
        "rating": 5,
        "comment": "Great!"
      },
      {
        "author": "Jane Doe",
        "rating": 4,
        "comment": "Good!"
      }
    ]
  }
}

Key-value pair metadata

For more specific use cases, you can shape metadata in a key-value pair array. Note that with this approach, you can force fields to be parsed into JSON with the json flag. You must follow this structure:

Here's an example on how to define your metadata in a key-value pair:

{
  "metadata": [
    {
      "key": "allergens",
      "value": "gluten"
    },
    {
      "key": "rating",
      "value": 4.99
    },
    {
      "key": "reviews",
      "value": [
        {
          "author": "John Doe",
          "rating": 5,
          "comment": "Great!"
        },
        {
          "author": "Jane Doe",
          "rating": 4,
          "comment": "Good!"
        }
      ]
    }
  ]
}

🚧

A note on facets

Facets are no longer defined in a catalog file. Instead, you should ingest this data as metadata and configure it as facetable via the Constructor dashboard or our API.

How do I create a transformation template?

Prerequisites

To develop transformation templates, you will need:

• A mapping template: Required if you are using the Omni Connector. This allows you to generate fixtures.
• Fixtures: Ideally, a fixture for each template type you will develop.

Develop your transformation templates

Follow the development flow to develop and test each transformation template.

Refer to your fixtures to understand the data structure, and write each template according to the tables preceding to map it in a way Constructor can understand. Make sure you also cover any cases for your integration.

Once you are happy with how your template looks, you can execute it and create automated tests to ensure it works properly. Finally, when you are satisfied with all of your templates, you can deploy them.

📘

Need more information on developing transformation templates?

Please refer to the README.md file within your Connect CLI repository for more details and examples on developing item, variations, and item groups templates.