Skip to content

Working with Data Priming

Data priming, or priming, is the addition of a retailers historical sales statistics into Apptus eSales. The use of historical sales statistics enables eSales to more quickly improve personalised 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 Apptus eSales customers.

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 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 eSales market where the purchase was performed</market>
        <lines>
            <line>
                <product_key>The unique eSales key of the purchased product</product_key>
                <variant_key>The unique eSales 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 eSales market where the purchase was performed. Defaults to Unknown market if omitted. Sweden
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 Apptus eSales.
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 Apptus eSales. 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

The priming data file is validated with the Primer tool and the following command.

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

Finalise data priming

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

×