Data entity types¶
A data entity type can be defined as an object with certain properties, a key and value map. There are three main data entity types in Voyado Elevate 3: product, category, and ad.
The data entities are derived from a retailer's own systems, such as PIM, CMS, CRM, and ERP, and transformed by the retailer (or an implementing partner) into Elevate compatible XML and imported into Elevate with the RESTful API.
Each entity type have user-defined and configurable attributes as well as reserved attributes and attribute names. The attributes are based on a retailer's data model. The data model can be considered as the design specification for the XML, and lays the groundwork to a successful Elevate integration.
A general recommendation is that all data that can be used in Elevate such as attributes for sort, search, presentation, facets, and so on should be used in Elevate. This includes copy such as product descriptions from a CMS and price data from a PIM.
Reserved attributes and attribute names¶
Reserved attributes and reserved attribute names, also known as reserved words for attributes, are not the same thing. A reserved attribute is an attribute with a name that is allowed in the data model but will be interpreted by Elevate in a specified way. A reserved attribute name is a word that is not allowed in the data model. Each data entity have their own set of reserved attribute names. Using a reserved attribute name in a data model will result in import errors.
Product¶
A product is the main data entity in Voyado Elevate. Together with variants, it is how content is mainly represented in Voyado Elevate and hold all necessary information of an actual product. Products can have variants and be a part of one or several categories.
Variants are items that represent a product but due to different characteristics, or business reasons, must be accounted for separately. Variants can be placed in two different ways in a data model. Either the variant is nested inside the product or it is a stand-alone entity that has a product key link that connects it to its parent product. Product and variant keys must be unique.
Reserved product attributes
The following product attributes are reserved in Voyado Elevate:
product_key, variant_key, locale
Reserved product attribute names
The following product attributes names are reserved in Voyado Elevate:
relevance_class, relevance, sales, rank, abandoned_timestamp, viewed_timestamp, bought_timestamp, proportion, rating, clicks, explanation, revenue, personal
Mandatory product and variant attributes
The following product attributes are mandatory:
product_key
The following variant attributes are mandatory:
variant_key
product_key (if the variant is a stand-alone entity and not nested in a product)
Recommended product attributes
The following product attributes are recommended to use:
locale
market
Attribute restrictions
User-defined attributes can not be more than 2 000 characters long and their values can not be more than 2 000 000 characters.
A product or variant key may not contain any whitespace characters or commas, ,.
XML structure examples¶
The following examples showcase how different types of products and data models result in different XML structures.
Fashion/apparel/lifestyle product example
...
<product>
<product_key>1234567-1</product_key>
<title>Free Run 2</title>
<url>/products/1234567</url>
<has_image>true</has_image>
<image_url>/images/products/1234567-1.jpg</image_url>
<price>99.00</price>
<market>UK</market>
<locale>en-GB</locale>
<release_date>2017-03-10</release_date>
<section>men-shoes-running-shoes</section>
<brand>Nike</brand>
<color>Black</color>
<variants>
<variant>
<variant_key>1234567-1-42</variant_key>
<size>42</size>
<in_stock>true</in_stock>
</variant>
<variant>
<variant_key>1234567-1-43</variant_key>
<size>43</size>
<in_stock>true</in_stock>
</variant>
</variants>
</product>
<product>
<product_key>1234567-2</product_key>
<title>Free Run 2</title>
<url>/products/1234567/2</url>
<has_image>true</has_image>
<image_url>/images/products/1234567-2.jpg</image_url>
<price>99.00</price>
<market>UK</market>
<locale>en-GB</locale>
<release_date>2017-03-10</release_date>
<section>men-shoes-running-shoes</section>
<brand>Nike</brand>
<color>White</color>
<variants>
<variant>
<variant_key>1234567-2-42</variant_key>
<size>42</size>
<in_stock>false</in_stock>
</variant>
<variant>
<variant_key>1234567-2-43</variant_key>
<size>43</size>
<in_stock>true</in_stock>
</variant>
</variants>
</product>
...
Books/media/technology product example
...
<product>
<product_key>42037246</product_key>
<title>Ruins</title>
<artist>First Aid Kit</artist>
<category>music</category>
<url>/music/42037246</url>
<has_image>true</has_image>
<image_url>/images/music/42037246.jpg</image_url>
<market>UK</market>
<locale>en-GB</locale>
<release_date>2018-01-19</release_date>
<category_slug>new-releases</category_slug>
<media>CD</media>
<price>15.00</price>
<description>The Swedish folk duo’s fourth album is a showcase for their sweet harmonies, with some bold stylistic departures.</description>
<in_stock>true</in_stock>
<label>Columbia</label>
<distributor>SME</distributor>
<ean>0190758060125</ean>
<tracks><track>Rebel Heart</track><track>It's a Shame</track><track>Fireworks</track><track>Postcard</track><track>To Live a life</track><track>My Wild Sweet Love</track><track>Distant Star</track><track>Ruins</track><track>Hem of Her Dress</track><track>Nothing Has to Be True</track></tracks>
</product>
...
Furniture/home improvement product example
...
<product>
<product_key>D55012505</product_key>
<title>Work desk Basic</title>
<category>desks</category>
<url>/products/D55012505/</url>
<market>UK</market>
<locale>en-GB</locale>
<width>120</width>
<depth>80</depth>
<min_height>65</min_height>
<max_height>125</max_height>
<max_load>100</max_load>
<description>Versatile desk available in several materials and colors.</description>
<variants>
<variant>
<variant_key>D55012505-white-birch</variant_key>
<article_no>D55012505-1-1</article_no>
<url_addon>#/white-birch/</url_addon>
<color>White</color>
<material>Birch veneer</material>
<motorized>false</motorized>
<price>120.00</price>
<in_stock>true</in_stock>
<has_image>true</has_image>
<image_url>/images/products/D55012505-white-birch.jpg</image_url>
</variant>
<variant>
<variant_key>D55012505-clear-acrylic-oak-veneer</variant_key>
<article_no>D55012505-0-4</article_no>
<url_addon>#/clear-acrylic-oak-veneer/</url_addon>
<color>Clear acrylic</color>
<material>Oak veneer</material>
<motorized>true</motorized>
<price>210.00</price>
<in_stock>true</in_stock>
<has_image>true</has_image>
<image_url>/images/products/D55012505-clear-acrylic-oak-veneer.jpg</image_url>
</variant>
</variants>
</product>
...
Category¶
Categories are modeled as a tree structure that is defined during imports. There is always a root and all categories have an identifying parent category.
Categories and products are tightly coupled as a category contains products and a product is a part of one or more categories. This relationship is also defined during the imports.
The maximum number of category trees is 100 and a category tree has a max depth of 10 levels. A tree can hold maximum 10 000 categories and each category can hold up to 100 attributes.
Categories also support custom attributes to enable retrieval of images, links, or localized names directly from a result without multiple queries.
Reserved category attribute names
The following category attributes names are reserved in Voyado Elevate:
key, relevance, product_count, selected, sales, personal, revenue, explanation
Mandatory category attributes
The following category attributes are mandatory:
key
parent
Recommended category attributes
The following category attributes are recommended to use:
display_name
locale
market
Attribute restrictions
User-defined attributes can not be more than 2 000 characters long and their values can not be more than 2 000 000 characters.
A category key may not contain any whitespace characters or commas, ,.
XML structure examples¶
The following example showcase the XML structure of a basic category tree. The category tree attribute product_attribute="section" is used to connect to the category attribute of a product. The corresponding category key value men-shoes-running-shoes can be found in the Fashion/apparel/lifestyle product example.
Category example
...
<category_tree product_attribute="section">
<category key="men-shoes" parent="root">
<display_name>Mens shoes</display_name>
<locale>en-GB</locale>
<attributes>
<market>UK</market>
<url>/categories/mens-shoes</url>
<department>Shoes</department>
</attributes>
</category>
<category key="men-shoes-running-shoes" parent="men-shoes">
<display_name>Running shoes</display_name>
<locale>en-GB</locale>
<attributes>
<market>UK</market>
<url>/categories/men-shoes-running-shoes</url>
<department>Men</department>
</attributes>
</category>
<category key="men-shoes-tennis-shoes" parent="men-shoes">
<display_name>Tennis shoes</display_name>
<locale>en-GB</locale>
<attributes>
<market>UK</market>
<url>/categories/men-shoes-tennis-shoes</url>
<department>Men</department>
</attributes>
</category>
</category_tree>
...
Ad¶
Ads are used to add banners, content blocks, and static page links to pages in addition to products that is relevant in the context. Context can be different for each visitor of a site.
Ads can be used as a static ad where static data is used. Ads can also be used as a live ad where static data is used together with a number of products connected to the ad, live products. Which products a visitor is shown in the ad depends on the visitor and how popular the products in the ad are. Products in a live ad will be internally ranked based on the active exposure strategy as set in the Business app, and will be personalized if possible.
Reserved ad attribute names
The following ad attribute names are reserved in Voyado Elevate:
ad_key, rank, locale, products, related, included, explanation
Mandatory ad attributes
The following ad attributes are mandatory:
ad_key
Recommended ad attributes
The following ad attributes are recommended to use:
locale
market
Attribute restrictions
User-defined attributes can not be more than 2 000 characters long and their values can not be more than 2 000 000 characters.
An ad key may not contain any whitespace characters or commas, ,.
XML structure examples¶
Ad example
...
<ad>
<ad_key>ad2018011420180214</ad_key>
<start_time>2018-01-14T08:00:00+01:00</start_time>
<end_time>2018-02-15T24:00:00+01:00</end_time>
<included>category:'cd' AND genre:'soul' AND genre:'rnb'</included>
<related>category:'cd' AND genre:'jazz'</related>
<title>Valentines day music offers</title>
<market>UK</market>
<locale>en-GB</locale>
<tags>cd,music</tags>
<live_products>3</live_products>
<campaign_key>valentines2018</campaign_key>
<campaign_url>/campaigns/valentines-2018/music/</campaign_url>
<format>fullwidth</format>
<image_url>/images/ads/ad2018011420180214.jpg</image_url>
<ad_category>frontpage</ad_category>
</ad>
...
Synonym¶
A data format for managing synonyms was introduced with the Web API v2. Synonyms are used to extend searches of a phrase to include similar search phrases.
A synonym includes a locale, one search phrase, and one synonym phrase that will be used together with the search phrase. If the synonym is valid for all locales, the value global should be used.
Reserved synonym attribute names
The following synonym attribute names are reserved in Voyado Elevate:
locale, search_phrase, synonym_phrase
Data type availability
The synonym data entity type format is available with the Web API v2 only.
Special characters
Special characters in synonyms must be escaped using a preceding backslash, for example \' and \".
XML structure examples¶
Synonym example
...
<synonym>
<locale>en-GB</locale>
<search_phrase>Shoes</search_phrase>
<synonym_phrase>Boots</synonym_phrase>
</synonym>
<synonym>
<locale>en-GB</locale>
<search_phrase>Shoes</search_phrase>
<synonym_phrase>Sneakers</synonym_phrase>
</synonym>
...