How to start using EPS

1. Introduction

Product and category data are expected as messages in a topic-based system, preferably Kafka. Messages are formatted as JSON strings.

• Updates and Inserts: Handled within the same topic, meaning every update must include a complete message (not just the modified fields).
• Deletes:
• Can be delivered in a separate topic containing only the identifier.
• Alternatively, they can be handled within the same topic as tombstone messages (preferred method) to retain the full dataset in the topic.
• A full data export should be easily achievable.

---

2. Product Data Structure

Product data is structured into two levels:

• Variation Level: Represents a purchasable element, e.g., a clothing item with a specific size and color.
• Item Level: Groups multiple variations into a single displayable product in the product list.

---

2.1 Product-Level Data

2.1.1 Mandatory Fields

Field	Description
productId	ID of the parent entity, grouping multiple variations into a displayable product.
shortDescription	Short product description, typically displayed in product lists.
categories	List of shop categories in which the product should be clustered.

2.1.2 Important Fields

Field	Description
brand	Product brand (used for brand filtering).

2.1.3 Optional Fields

Field	Description
longDescription	Detailed product description (searchable field).

---

2.2 Variation-Level Data

2.2.1 Mandatory Fields

Field	Description
sku	SKU of a variation (purchasable item).
color	Product color.
size	Product size (used for size filtering).
searchColor	Searchable color (used for color filtering).
price	Numeric price.
image	URL of the product image.
availability	Availability score (numeric: 0 = out of stock, 1 = fully available, values between 0-1 indicate backorder status, e.g., 0.2 for delayed availability). Defined per tenant.

2.2.2 Important Fields

Field	Description
articleNumber	Article number (used for search when customers know the number).
oldPrice	Original price, useful for filtering discounted items.

2.2.3 Important Fields for Full Data Responses

Field	Description
oldPriceType	Example: MSRP (Suggested Retail Price).
link	URL to the product detail page (can be absolute or relative).
basePrice	Numeric base price (e.g., 23.99 / 100ml) for legal requirements.
basePriceUnit	Unit for base price.

2.2.4 Optional Fields

Field	Description
moreDimensions	Additional dimensions (e.g., for furniture).
colorImage	URL of the color swatch image, useful for products with multiple colors.

---

2.3 Attributes (Available for Both Product and Variation Levels)

Tip

Attributes are additional data fields that are not covered by the predefined fields.

2.3.1 Filter Attributes

• Used for creating additional product filters.
• These values are included in the search index.

Structure

Field	Description
displayName	Filter name (shown in UI).
value	Display name of the filter value (shown in UI).
name (optional)	Identifier of the filter (auto-generated if not provided).
id (optional)	Filter value ID (must be unique across all filters if provided).

---

2.3.2 Attributes for Search Index

• These attributes do not generate filters but are indexed for search relevance.
• They have three importance levels: high, medium, low.

Structure

Field	Description
name	Attribute name.
value	Attribute value.

---

2.3.3 Attributes for Full Data Responses

• These attributes are not indexed and do not generate filters.
• They are passed through in the search response but are only used for display purposes (e.g., marketing flags, energy efficiency labels).

Structure

Field	Description
name	Attribute name.
value	Attribute value.

---

2.3.4 Attributes for Ranking

• These attributes are not indexed and do not generate filters.
• They are sent to the ranking engine to influence product sorting in search results.

Structure

Field	Description
name	Attribute name.
value	Attribute value (numeric or text).

---

2.4 Example Product Message

Example JSON Payload representing a product with two variations

{
    "productId":"AKLBB123456",
    "brand":"ADIDAS",
    "shortDescription":"2 Jogging pants",
    "longDescription":"2 high-quality jogging pants made of cotton.",
    "filterAttributes":[
        {
            "name":"Ratings",
            "value":4
        },
        {
            "name":"Product type",
            "value":"Sport pants"
        }
            ],
            "searchIndexAttributesHigh":[
        {
            "name":"Material",
            "value":"98% Cotton, 2% Elastane"
        }
            ],
            "displayDataAttributes":[
        {
            "name":"avgRating",
            "value":"4.25"
        },
        {
            "name":"ratingCount",
            "value":4
        }
    ],
    "ruleEngineValues":[
        {
            "name":"onlineSales7d",
            "value":2378.9
        }
    ],
    "categories":[
        "Cat123",
        "Cat3456",
        "Cat7890"
    ],
    "variations":[
        {
            "sku":"12345678-50",
            "artNo":"12345678",
            "color":"dark-anthracite",
            "searchColor":"black",
            "size":"50",
            "link":"https://theshop.com/article/12345678-50",
            "price":39.99,
            "oldPrice":49.99,
            "oldPriceType":"MSRP",
            "basePrice":19.99,
            "basePriceUnit":"Unit",
            "availability":1,
            "image":"https://theshop.com/static/img/245435845.jpg",
            "colorImage":"https://theshop.com/static/img/black.jpg",
            "filterAttributes":[
                {
                    "name":"Size Type",
                    "value":"Regular"
                }
            ]
        }
    ]
}

---

3. Categories

Category Fields

Field	Type	Description
id	string	Unique category identifier.
displayName	string	Category name (shown in navigation and search).
parentId	string	ID of the parent category (empty for root category).
position	integer	Sorting position within subcategories.
isOnline	boolean	Whether the category is active (true/false).

Examples of Category Attributes

Attribute	Description
UrlSlug	Auto-generated URL for categories.
filters	Comma-separated list of available filters.
standardFilters	Default filters applied in the category (e.g., “sale items” in a SALE category).