Skip to content

Getting started

The aim of this article is to help developers get started developing integrations with Ecommerce Search.

Setup Environment

The first thing to do is set up a local Bizzkit development environment. A detailed guide for doing this can be found here.

Ingesting products

It is not possible to do any searching without any products. So the first step is to ingest products into the system. This can be done using the SDK or with plain HTTP. A more detailed description of ingesting products can be found here, but to simply ingest some products to start working, it is enough to interact with swagger. See the full API reference here.

  1. Go to https://ecommercesearch.bzk.hdk/swagger/index.html or where you might access the admin site swagger.
  2. Authorize.

  3. Go to POST /api/segments with request body

    1
2
3
4
5
6
    {
    "segmentId": "b2c-en-test",
    "language": "English",
    "name": "English market - test",
    "createDefaultValues": true
}

  4. To ingest products, go to PUT /api/ingestion/segments/{segmentId}/products/bulk with segmentId b2c-en-test and request body

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
    {
    "products": [
        {
            "name": "Woolen socks",
            "shortDescription": "Some nice woolen socks",
            "longDescription": "Some very nice and warm woolen socks",
            "productNumber": "prod-1",
            "metadata": {
                "splash": "New"
            },
            "categories": [
                {
                "categoryPathElements": [
                    {
                    "categoryId": "c-1",
                    "categoryName": "Women's socks"
                    }
                ]
                }
            ],
            "productId": "socks1"
        },
        {
            "name": "Comfy socks",
            "shortDescription": "Some comfortable socks",
            "longDescription": "Excellent socks during winter",
            "productNumber": "prod-2",
            "metadata": {
                "splash": "New"
            },
            "categories": [
                {
                "categoryPathElements": [
                    {
                    "categoryId": "c-1",
                    "categoryName": "Women's socks"
                    }
                ]
                }
            ],
            "productId": "socks2"
        }
    ]
}

  5. To ingest SKUs, go to PUT /api/ingestion/segments/{segmentId}/skus/bulk with segmentId b2c-en-test and request body

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
    {
    "skus": [
        {
            "productId": "socks1",
            "skuNo": "socks-red-xs",
            "ean": "0012345678905",
            "name": "Red socks",
            "stringAttributes": {
                "COLOR_ID": {
                "name": "Color",
                "values": {
                    "GREEN_ID": "Green",
                    }
                },
                "SIZE_ID": {
                "name": "Size",
                "values": {
                    "XL_ID": "XL"
                    }
                },
                "SEASONS_ID": {
                "name": "Seasons",
                "values": {
                    }
                }
            },
            "stock": 1,
            "prices": {
                "priceGroupPrices": [
                {
                    "priceGroupId": "default",
                    "price": 4199,
                    "listPrice": 4200
                }
                ]
            },
            "commercialParameters": {
                "seasonal": ""
            },
            "skuId": "socks-sku-1"
        },
        {
            "productId": "socks2",
            "skuNo": "socks-comfy-m",
            "ean": "0012345678906",
            "name": "Blue socks",
            "stringAttributes": {
                "COLOR_ID": {
                "name": "Color",
                "values": {
                    "GREEN_ID": "Blue",
                    }
                },
                "SIZE_ID": {
                "name": "Size",
                "values": {
                    "M_ID": "m"
                    }
                },
                "SEASONS_ID": {
                "name": "Seasons",
                "values": {
                    "WINTER_ID": "Winter"
                    }
                }
            },
            "stock": 1,
            "prices": {
                "priceGroupPrices": [
                {
                    "priceGroupId": "default",
                    "price": 4299,
                    "listPrice": 4300
                }
                ]
            },
            "commercialParameters": {
                "seasonal": "winter"
            },
            "skuId": "socks-sku-2"
        }
    ]
}

Searching for products

Now that products have been ingested, it is possible to search for them.

  1. To go https://search.bzk.hdk/swagger/ or where you might access the search api. See the full search API reference here.
  2. Go to POST /products with request body
1
2
3
4
5
{
  "segmentId": "b2c-en-test",
  "scopeId": "browse",
  "phrase": ""
}

You should see two products. In order to affect the data returned in these products, you can make changes to the scope. You can also do a search for

1
2
3
4
5
{
    "segmentId": "b2c-en-test",
    "scopeId": "browse",
    "phrase": "comfy"
}

You should then only see one product.

Commercial sorting

When the SKUs were ingested, the comfy socks had a commercial parameter of being seasonal for winter. Commercial sorting can give products that are suited for winter a boost.

  1. Go to https://ecommercesearch.bzk.hdk/sort/parameters or where you might access the admin site
  2. Add a new parameter with id seasonal, name Seasonal and type Term
  3. Create partition with id winter, name Winter and term winter
  4. Go to https://ecommercesearch.bzk.hdk/sort/contexts
  5. Click on the Fallback context
  6. Click Parameters
  7. Click ADD PARAMETER
  8. Choose Seasonal
  9. Type 1000 into Winter
  10. Comfy socks should now have a boost score of 1000
  11. Click SAVE

Contexts can be used for many things, boosting seasonal products is just one example. To understand how contexts work, read about them here.

Next steps

Ecommerce Search provides several other interesting features to get started with. Have a look at the dashboard, or maybe diagnostics.

To get a better understanding of some of the fundamental pieces of Ecommerce Search, read more about products, segments, text analysis and of course search.