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.

Facets

❗️

Deprecation notice

Configuring facets via catalog ingestions is deprecated. If you choose to ingest a field using facets on your template it won't be automatically configured.

Instead, you should ingest the data as metadata and configure it to be facetable via the customer dashboard or API.

Both items and variations can ingest the same facets array. It is data shaped in a key-value pair that will be ingested into your Facets. Here is how each object should look inside the key-value pair array:

Keep in mind that facets should have primitive values or an array of primitive values. This means you cannot store JSON or complex data within a facet.

Here is an example of valid facet values:

{
  "facets": [
    {
      "key": "stock",
      "value": 42
    },
    {
      "key": "color",
      "value": "green"
    },
    {
      "key": "prices",
      "value": [10, 20, 30]
    }
  ]
}

Metadata

Both items and variations can ingest the same metadata array. It is data shaped in a key-value pair that will be ingested into your Metadata. Here is how each object should look inside the key-value pair array:

Unlike facets, metadata fields can hold JSON data. To achieve this, specify a JSON piece of data in the value and it will be ingested and returned as JSON during API calls.

Here is an example of valid metadata values:

{
  "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!"
        }
      ]
    }
  ]
}

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.