Skip to content

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>&lt;track&gt;Rebel Heart&lt;/track&gt;&lt;track&gt;It's a Shame&lt;/track&gt;&lt;track&gt;Fireworks&lt;/track&gt;&lt;track&gt;Postcard&lt;/track&gt;&lt;track&gt;To Live a life&lt;/track&gt;&lt;track&gt;My Wild Sweet Love&lt;/track&gt;&lt;track&gt;Distant Star&lt;/track&gt;&lt;track&gt;Ruins&lt;/track&gt;&lt;track&gt;Hem of Her Dress&lt;/track&gt;&lt;track&gt;Nothing Has to Be True&lt;/track&gt;</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>
...

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>
...
×
Copyright

This online publication is intellectual property of Voyado Lund AB. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Voyado Lund AB nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Voyado Lund AB essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE