How to handle complex attributes
Introduction
Each product in SCAYLE is defined by its unique characteristics, which are crucial for detailed descriptions. Consider a blue T-shirt in size “S”, a white Nike sneaker, or a wooden shelf measuring 100cm. These defining features, such as color, product family, size, or brand, are organized within what is known as attribute groups. Simple attribute groups, like size (where a variant has a single value) or color (where a product might come in multiple colors, like blue and red) provide basic product descriptions. However, not everything can be described with simple attribute groups. Sometimes you have to combine several simple attributes and add some values to one product characteristic. Complex attribute groups enable the creation of detailed value constellations, such as {amount} % {material}, or {amount} {unit} {measurementLocation}. For example, the material composition of a T-shirt might be 80% cotton and 20% polyester. These more detailed values are known as complex attribute groups in SCAYLE. This tutorial will guide you through creating complex attribute groups and how to populate them with values.
Prerequisites
Before tackling this topic, you should have a basic understanding of what attribute groups are, where to find them, and how to edit them.
Best Practices
Creation and usage in the SCAYLE Panel
Creating a complex attribute group is almost identical to the general attribute group creation process. The differences start appearing when choosing the structure of the attribute group (advanced).\
In the following steps, you’ll tailor your attribute group according to your requirements. This tutorial will concentrate on material composition as an example of a complex attribute group.
Creation in the SCAYLE Panel
You can configure a complex attribute group based on your specific needs. Here are the available components you can choose from:
- Text
- Long Text
- Numeric
- Date
- Attribute
- Attribute group
We recommend utilizing the SCAYLE Panel for creating advanced and complex attribute groups, given its user friendly interface.
In this tutorial, we’ll cover the common use cases of material compositions. Attribute groups needed include “unit” (containing “%”) and “material”. The configuration steps are as follows:\
- Preconditions: The simple attribute group “material” must already exist including all needed values.
- Select numeric for the first field, where you'll later input varying material percentages.
- Select attribute > unit > %. This ensures the "%" sign automatically follows the numeric value.
- Select attribute group > material, enabling the selection of materials from your pre-defined list.
Creation via the AdminAPI
It’s also possible to create a complex attribute group with the Admin API, using the “create attribute groups” endpoint. Given that the request body is quite nested, this chapter provides additional information and detail on how to handle the request.
| In the first block you define the name of the attribute group and its frontend names across different languages. |
|---|---|
| For this advanced (complex) attribute group, set isShared to false. Additionally, you can select the attribute group's "level," with options including master, product, or variant, to suit your requirements. |
| In the structure block, you’ll define the structure of your complex attribute group configuration. Aimed at achieving a display like “90% cotton,” the setup should include a numeric input, a “%” unit, and the “material” attribute group |
| This final step allows you to specify the attribute group's applicability to certain shop countries, whether shop-specific values are permitted, and if each item needs a unique attribute value, indicated by isDifferentiating |
Usage in the SCAYLE Panel
Complex attribute group values are set on the Product Detail Page (PDP) in the panel. Once you have attached the attribute group to the master categories it will appear on the PDP. Accessing the attribute group on a product's page reveals an input field, a "%" sign, and a dropdown list. For a product comprising 97% cotton and 3% elastane, input “3” and “elastane,” then click to add another component, followed by “97” and “cotton.”
\
Setting advanced attributes via the Admin API
To visualize your attribute group in JSON format, use the JSON Preview button in the panel.
To see the attribute group based on a specific product, use the Admin API product endpoint:
GET https://{{tenant-space}}.admin.api.scayle.cloud/v1/products/{{productIdentifier}}?with=attributes,advancedAttributes
A typical API response might look like this:
This response shows the type advancedList and the component IDs:
| 1234 | Numeric input field |
|---|---|
| 9522 | Unit attribute group with the defined value “%” |
| 2255 | Material attribute group |
The specific endpoint to use to update an attribute depends on the attribute group's level (master, product, variant). You’ll find the relevant endpoints in these hyperlinks.
For material composition at the master level, the endpoint must be:
POST https://{{tenant-space}}.admin.api.scayle.cloud/v1/product-masters/{{productMasterIdentifier}}/attributes \
For a 50% wool, 50% cotton T-shirt, the payload would be structured like this:
