Enabling Variant Support in ECommerce API

Enabling variants in ECommerce API requires five “things” to be done:

1. A new feature must be added to and set on all items that are either products or variants, to tell EC which are products and which are variants. .
2. A new feature must be added to and set on all items that are a variant that tells which product is this a variant of.
3. Mappings for these must be created.
4. Variant support should be enabled in Settings.
5. (Optional) In case you want variants in multiple dimensions a few more features/mappings are needed.

The above seems quite a bit, but it is actually quite simple to do. The biggest task lies in modifying the data correctly.

The following sections describe how each of the 5 above steps are carried out:

Adding features to Product

ECommerceType

EC needs a feature that holds the value “Product” on all Perfion Items that are reckoned Products and “Variant” on all items that are reckoned variants. As part of the Auto Creating-features, a feature named  ECommerceType has already been created for this purpose. This feature should simply be added to the configuration of the base feature holdings Products and filled out on all Perfion items that are either products and variants. Items not representing neither a product nor a variant should have this field blank (but they may have any value not being “Product” and “Variant”).

ECommerceVariantOfProduct

This mapping should be added to the configuration of “Products” and filled out on both products and variants.

Note: The value has to be identical to the KeyField-value of which product it is a variant of, so it is important to check the mapping in order to verify which feature is mapped as KeyField product entity. As part of the auto-creating of features such a feature has already been created. It is called ECommerceVariantOfProduct.

Both ECommerceType and ECommerceVariantOfProduct has been added to the configuration on Product and filled out on the jugs as shown in Figure 1 below.

Note how the item with base value “EM77” has been designated the ECommerceType “Product” while all the Jugs below it has been designated the ECommerceType “Variant”. Note further how all the variants as value of the  ECommerceVariantOfProduct-feature points to “EM77” because they are variants of exactly that product.

It is a requirement that a variant must be child of its product. It is not a requirement, however, that it must be an immediate child. It is OK to have virtual nodes in between the product virtual node and its variants (although there are no such virtuals in the figure).

It is important to note, that even products that does not have any variants also need to have its ECommerceType set to Product. Otherwise they will be ignored by EC. Perfion Items having their ECommerceType set to anything but “Product” or “Variant” will simply be ignored by EC as soon as variant-support is enabled.

Adding mappings to the Product- and Variant-entities

With data in place, the necessary mappings can be created. Consider the product-mappings in Figure 37.

The first new mapping added is the ECommerceType mapping. The Ecommerce Output Kind is exactly the feature of the same name. This tells EC that it should use this feature to figure out what is products and what is variants. Note: It is OK only to map this on entity Product and not on both Product and Variant. Note further, that this mapping does not output anything, so anything typed in “ECommerce To” will be ignored.

The next one for Ecommerce OutputKind is VariantOfProduct. This is mapped on entity Variant and tells EC where it for all variants can find their products. This also is not output, so an ECommerceTo is not needed.

The last two mappings added are for entity variant, simply to output data on the individual variants. As can be seen we simply output Title and Item No.

Enabling Variants

Enabling variants is simply done by setting the setting VariantSupportEnabled to the value True. See more in section VariantSupportEnabled.

Querying products with variants

Querying products works the same, regardless of products have variants or not. Consider the following query:

<Execute method="GetProducts" refreshconfiguration="true">
  <Parameter id="Channel" value="My Channel" />
  <Parameter id="Keys" value="EM77" />
  <Parameter id="IncludeMappings">
    <Value>Item No</Value>
    <Value>Title</Value>
  </Parameter>
</Execute>

This will output the product with Key-value EM77. Now this product has variants, so it will look like this:

<Response>
  <Result>
    <Channel name="My Channel">
      <TotalCount>1</TotalCount>
      <Products>
        <Product id="721" ecommerceproduct="EM77">
          <Fields>
            <Field name="Item No">EM77</Field>
          </Fields>
          <Variants>
            <Variant id="625" ecommerceproduct="EM77" ecommercevariant="978ST">
              <Fields>
                <Field name="Title" culture="en-US">Vacuum Jug EM77  Chalk</Field>
                <Field name="Item No">978ST</Field>
              </Fields>
            </Variant>
            <Variant id="626" ecommerceproduct="EM77" ecommercevariant="980ST">
              <Fields>
                <Field name="Title" culture="en-US">Vacuum Jug EM77  Olive</Field>
                <Field name="Item No">980ST</Field>
              </Fields>
            </Variant>
<Variant id="627" ecommerceproduct="EM77" ecommercevariant="958ST">
              <Fields>
                <Field name="Title" culture="en-US">Vacuum Jug EM77  Purple</Field>
                <Field name="Item No">958ST</Field>
              </Fields>
            </Variant>
            ... more variants ...
         </Variants>
        </Product>
      </Products>
    </Channel>
  </Result>
</Response>

When querying products with variants the IncludeMappings and ExcludeMappings-parameters allow you prefix the FieldNames with the name of entity. The following query will include Item No on products and both Item No and Title on the variants.

<Execute method="GetProducts" refreshconfiguration="true">
  <Parameter id="Channel" value="My Channel" />
  <Parameter id="Keys" value="EM77" />
  <Parameter id="IncludeMappings">
    <Value>Item No</Value>
    <Value>Variant.Item No</Value>
    <Value>Variant.Title</Value>
  </Parameter>
</Execute>

Using Variant Dimensions

The jugs in previous sections were all variants in a single dimension, i.e. they only differed on one thing, in this case their color.

In case you have variants that differ in multiple dimensions, it is often preferable to utilize that for the end user of an ECommerce-system. EC allows you to output variants in any number of dimensions. Consider the pans shown in Figure 3.

Notice that the 10 variants this pan have are grouped in two dimensions: Color and Diameter.

You can tell EC about these dimensions by, on each product with variants in dimensions, assign the list of features that holds the dimensions. In this case we have two features Color and DiameterCM (as the features are named).

You also have to tell EC, that you have a feature telling in which features it can find these dimensions. This is done by creating yet another mapping as shown in Figure 4.

With data and mapping in place, the following query:

<Execute method="GetProducts" refreshconfiguration="true">
  <Parameter id="Channel" value="My Channel" />
  <Parameter id="Keys" value="1101" />
</Execute>

Now produces the following output:

<Response>
  <Result>
    <Channel name="My Channel">
      <TotalCount>1</TotalCount>
      <Products>
        <Product id="760" ecommerceproduct="1101">
          <Fields>
            <Field name="Item No">1101</Field>
            <Field name="Description" culture="en-US">High quality cast iron roasting pan with high gloss enamel with gradient. suitable for all cookers, incl. induction. Hand wash recommended.</Field>
          </Fields>
          <VariantDimensions>
            <VariantDimension name="VariantDimension" perfionname="ECommerceVariantDimensions">
              <FeatureName>Color</FeatureName>
              <Captions>
                <Caption culture="en-US">Color</Caption>
              </Captions>
            </VariantDimension>
            <VariantDimension name="VariantDimension" perfionname="ECommerceVariantDimensions">
              <FeatureName>DiameterCM</FeatureName>
              <Units>
                <Unit culture="en-US">cm</Unit>
</Units>
              <Captions>
                <Caption culture="en-US">Diameter</Caption>
              </Captions>
            </VariantDimension>
          </VariantDimensions>
          <Variants>
            <Variant id="638" ecommerceproduct="1101" ecommercevariant="1101225">
              <Fields>
                <Field name="Title" culture="en-US">Cocotte round, Black, 12cm</Field>
                <Field name="Item No">1101225</Field>
              </Fields>
              <VariantInstances>
                <VariantInstance>
                  <DimensionName>Color</DimensionName>
                  <InstanceId>343</InstanceId>
                  <InstanceSortOrder>5</InstanceSortOrder>
                  <Field name="Value" culture="en-US">Black</Field>
                </VariantInstance>
                <VariantInstance>
                  <DimensionName>DiameterCM</DimensionName>
                  <InstanceId>12</InstanceId>
                  <Field name="Value">12</Field>
                </VariantInstance>
              </VariantInstances>
            </Variant>
            ...
</Variants>
        </Product>
      </Products>
    </Channel>
  </Result>
</Response>

Notice how the product now outputs its Variant Dimensions, Color and DiameterCM and how each variant in its variant instances tells exactly which combination of dimensions it covers.

In Perfion 4.5 2019 R1 the elements InstanceId and InstanceSortOrder were added to VariantInstances.

InstanceId contains, as the name suggests, the Id of the VariantInstance. It is recommended that the feature to hold variant dimensions are selectables, and in this case, the id is simply the Item Id taken from Perfion which is guaranteed to be unique. In addition when you use a selectable feature, items (here colors) can be ordered by enabling “Custom Ordering” on the feature. This means you can sort the variant instances based on the ordering of colors, which you will find in the InstanceSortOrder-element. In the above example, we can see that the color “Black” has a unique id of 343 and the order of this color is 5.

If you are not using a selectable feature to hold a variant dimension (like the example above where DiameterCM is not a selectable) the ECommerce API will use its value as InstanceId (if it is localizable it will use the value in the default language, which is the first language mentioned in the Languages-setting) and it will have no InstanceSortOrder. Such a value will likely hold unique values, but it is not guaranteed to be unique and hereby not recommended to use a non-selectable feature to hold variant dimensions.