Handling Structured and Nested Product Data

Imagine, you have a shop that offers food products. As required in many countries you are required to provide the nutrition facts about your food products. To do so, you need to provide quantities for, for example, sugar, fat, and protein for each of the products you offer. Look at the yummy tub of ice cream below for which we need to store some nutrition facts.

Wouldn't it be great to have a structured data object that holds all those nutrient information and that we could reuse in all the products? That's really not a big deal in the commercetools platform, you can easily define ProductTypes with custom attributes the products of that type should have in common and you can nest this ProductType into another one. Confused? Don't worry, we'll guide you step by step through this tutorial.

Create simple Product Type

Our objective is to construct a food-product-type that contains nutrition information captured in a ProductType nutrient-information. Moreover, the food-product-type does not only contain one object of the type nutrient-information, but a structure such as a Set of them, for example, one for fat, one for sugar, and so on as depicted in the figure below:.

We always need to start with the creation of the simple ProductType that should be nested into the advanced ProductType. We must do it this way since we need the typeID of the ProductType to be nested first. Otherwise we wouldn't be able to setup the reference relationship between the advanced ProductType and the nested ProductType properly.

For the example we need to design the nutrient-information ProductType first. To keep it simple this ProductType contains two attributes only: one that holds a number indicating the quantity of a nutrient (quantityContained) and one attribute for the type of nutrient (nutrientTypeCode). We'll set both attributes as mandatory to be filled with values by setting isRequired to true for each attribute. For now nested attributes are not searchable in the commercetools platform so that we need to set is Searchable to false.

AttributeDefinition quantityContainedAttribute = AttributeDefinitionBuilder
        .of("quantityContained", en("quantity contained"), NumberAttributeType.of())
        .isRequired(true)
        .attributeConstraint(AttributeConstraint.NONE)
        .isSearchable(false)
        .build();
AttributeDefinition nutrientTypeAttribute = AttributeDefinitionBuilder
        .of("nutrientTypeCode", en("nutrient type Code"), StringAttributeType.of())
        .isRequired(true)
        .attributeConstraint(AttributeConstraint.NONE)
        .isSearchable(false)
        .build();
final ProductTypeDraft productTypeDraft =
        ProductTypeDraft.of(typeKey,
                "nutrient-information",
                "The nutrient-information product type.",
                asList(quantityContainedAttribute, nutrientTypeAttribute));
return client.execute(ProductTypeCreateCommand.of(productTypeDraft));

Create advanced Product Type

After we created the product type to be nested we can now create the advanced food-product-type by referencing the previously created nutrient-information product type in a nested attribute we call nutrients. Furthermore we add the attribute taste that gives a textual description about how excellent the food product tastes.

AttributeDefinition tasteAttribute = AttributeDefinitionBuilder
        .of("taste", en("taste"), StringAttributeType.of())
        .isRequired(true)
        .attributeConstraint(AttributeConstraint.NONE)
        .isSearchable(false)
        .build();
AttributeDefinition nutrientsAttribute = AttributeDefinitionBuilder
        .of("nutrients", en("food nutrients"), SetAttributeType.of(NestedAttributeType.of(nestedProductType)))
        //nestedProductType is a Referenceable<ProductType>
        .isRequired(false)
        .attributeConstraint(AttributeConstraint.NONE)
        .isSearchable(false)
        .build();
final ProductTypeDraft productTypeDraft = ProductTypeDraft
        .of(typeKey, "food-product-type", "The food product type.", asList(tasteAttribute, nutrientsAttribute));
return client.execute(ProductTypeCreateCommand.of(productTypeDraft));

Create Product

We now have everything we need for creating an example-food-product of the food-product-type. The taste of the example-food-product is excellent of course, but we are also nesting following nutrient-information into the example-food-product: 1.4 units of FAT and 1.15 units of SUGAR. For the example we have reused the nutrient-information product type two times, but you can add more if you need since we defined the nutrients attribute of the food-product-type as set of nutrient-information.

For doing this with the commercetools platform API you Create a Product with following AttributeDefinition:

final AttributeDraft tasteAttributeDraft = AttributeDraft.of("taste", "excellent!");
final AttributeDraft nutrientsAttributeDraft = AttributeDraft.of("nutrients",
        asSet(
                asSet(
                        AttributeDraft.of("quantityContained", 1.4),
                        AttributeDraft.of("nutrientTypeCode", "FAT")
                ),
                asSet(
                        AttributeDraft.of("quantityContained", 1.15),
                        AttributeDraft.of("nutrientTypeCode", "SUGAR")
                )
        ));
final List<AttributeDraft> attributesList = asList(tasteAttributeDraft, nutrientsAttributeDraft);
final ProductVariantDraft productVariantDraft = ProductVariantDraftBuilder.of()
        .sku(sku)
        .attributes(attributesList)
        .build();
final ProductDraftBuilder productDraftBuilder = ProductDraftBuilder.of(productType, en("example-food-product"),
        en(slug), productVariantDraft);
return client.execute(ProductCreateCommand.of(productDraftBuilder.publish(true).build()));

Summary

What have we just done? Basically, we have defined a ProductType that we reused in another ProductType. This allows us the composition of advanced product types based on existing ones. The commercetools platform supports that by using its nested AttributeType as illustrated in the figure below:

The following JSON snippet shows how an existing ProductType is nested into an AttributeDefinition of another ProductType in the commercetools platform:

{
  "name": "nestedProductType",
  "type": {
    "name": "nested",
    "typeReference": {
      "id": "<nested-product-type-id>",
      "typeId": "product-type"
    }
  }
}