Working with data priming¶

Data priming, or priming, is the addition of a retailers historical sales statistics into Voyado Elevate 3. The use of historical sales statistics enables Elevate to more quickly improve personalized results and content for visitors.

Priming is not a mandatory integration activity, but if priming is to be done for a site, it must be performed at the end of an Integration before go-live. Priming is only to be performed once.

A Primer tool used to verifying priming data is available for Voyado Elevate customers.

Market identifiers and key conventions

Market identifiers and product key conventions must be consistent across the imports, the notifications, and the data priming. The format of the customer keys in the data priming must match the format of the keys used with requests and notifications. Ensure this is consistent.

Data origin¶

Priming data is generated by a retailer's e-commerce systems such as a PIM or ERP. The priming data output must be in XML with UTF-8 encoding.

Data modification¶

Before data is validated with the Primer tool, the XML must be transformed to comply with the file syntax for data priming.

File syntax¶

A data file contains a root element, orders, with one or more order elements. An order includes one or more products that have been purchased and its related purchase data. The order elements must be in ascending chronological order, i.e. oldest first/newest last.

The following example presents the syntax of an XML-file with all available elements for data priming.

File syntax example


<?xml version="1.0" encoding="UTF-8"?>
<orders>
    <order>
        <time>The time of the order written in ISO-8601 format</time>
        <customer_key>The visitor id</customer_key>
        <market>The Elevate market where the purchase was performed</market>
        <lines>
            <line>
                <product_key>The unique Elevate key of the purchased product</product_key>
                <variant_key>The unique Elevate key of the purchased variant</variant_key>
                <quantity>The quantity of the purchased product</quantity>
                <unit_cost>The cost of the purchased product</unit_cost>
                <unit_selling_price>The selling price of the purchased product</unit_selling_price>
            </line>
        </lines>
    </order>
</orders>

Elements¶

The following elements are allowed in a priming data XML-file.

Name	Type	Description	Example
`orders`	Root element	The root element of the priming data file. It can only hold `order` elements as child elements. Required element.	N/A
`order`	Container element	The element containing all information about a purchase. Parent element is `orders`. Required element.	N/A
`time`	time_point	The time of the order. The time should be written in ISO 8601 format, including offset. Required element.	`2017-10-14T12:00:00+01:00`
`customer_key`	string	The visitor id. With Web API v2, always a UUID v4. With Web API v1, a SHA256 hash if the visitor was signed in, otherwise a UUID / GUID.	`5G7HJ...R77T1`
`market`	string	The Elevate market where the purchase was performed. The same value as the market notification value as set in the Admin app. Defaults to `Unknown market` if omitted.	`swe`
`lines`	Container element	The element containing the `line` elements. Parent element is `order`. Required element.	N/A
`line`	Container element	The element containing all elements related to the purchase of a specific product in an order. Required element.	N/A
`product_key`	string	The unique key of the purchased product. The `product_key` must be the same key as for the product imported into Voyado Elevate. Required element.	`shirt_79709`
`variant_key`	string	The unique variant key of the variant. The `variant_key` must be the same key as for the variant imported into Voyado Elevate.	`shirt_79709_M`
`quantity`	int	The quantity of the purchased product. The following bounds apply: `quantity` ≥ 1. Defaults to 1 if omitted.	`2`
`unit_cost`	double	The cost of the purchased product. The following bounds apply: `unit_cost` ≥ 0.	`15.2`
`unit_selling_price`	double	The selling price of the purchased product. The following bounds apply: `unit_cost` ≥ 0. Defaults to 1 if omitted.	`20.0`

Example priming data¶

The following example will add two orders with a total of three products as priming data.

XML


<?xml version="1.0" encoding="UTF-8"?>
<orders>
    <order>
        <time>2017-10-14T12:00:00+01:00</time>
        <customer_key>d9528030-509c-4e0f-b585-7168f1e9feca</customer_key>
        <market>UK</market>
        <lines>
            <line>
                <product_key>P_555452-0446_UK</product_key>
                <variant_key>V_555452-0446_1_UK</variant_key>
                <quantity>3</quantity>
                <unit_cost>2.2</unit_cost>
                <unit_selling_price>5.5</unit_selling_price>
            </line>
        </lines>
    </order>
    <order>
        <time>2017-10-14T12:00:05+01:00</time>
        <customer_key>e030d954-b585-280f-509c-68f171fee9ca</customer_key>
        <market>UK</market>
        <lines>
            <line>
                <product_key>P_335975-0444_UK</product_key>
                <variant_key>V_335975-0444_3_UK</variant_key>
                <quantity>1</quantity>
                <unit_cost>3.5</unit_cost>
                <unit_selling_price>4.2</unit_selling_price>
            </line>
            <line>
                <product_key>P_133449-0338_UK</product_key>
                <quantity>2</quantity>
                <unit_cost>5.1</unit_cost>
                <unit_selling_price>8.5</unit_selling_price>
            </line>
        </lines>
    </order>
</orders>

Validate data¶

Download the Primer tool and validate the priming data file with the following command.


java -jar primer.jar validate file-name.xml

Finalise data priming¶

When the priming data file is complete and validated, contact Voyado Support to finalise the data priming process.