Integrating Bizzkit PIM and Ecommerce Search

This integration syncronizes product data from PIM into ECS. Products and SKUs in ESC will be created/updated/deleted via a webhooks configured in PIM. The webhooks must be configured using this tool for the integration to work.

The following rules are used for created Products and SKU's in ECS.

Standalone

flowchart TD
    a[Product]

A product that does not have an ancestor or any descendents is considered standalone and is in ECS mapped to 1 product and 1 sku.

From the example above we would transfer 1 product and 1 sku to ECS.

flowchart LR
    subgraph PIM
    p[Product Hat12]
    end
    subgraph ECS
    ep[Product Hat12]-->es[Sku Hat12]
    end
    PIM-->ECS

Product with color variants

flowchart TD
    a[Product]
    aa[Color Variant A]
    ab[Color Variant B]
    a --> aa
    a --> ab

We asume that if a product only has a single ancestor and no descendents then the product is a standalone color variation. Since there are no variants of the product is is seen as one-size product. A standalone color variation is therefore mapped as 1 product and 1 sku.

From the example above we would transfer 2 product and 2 sku's to ECS.

flowchart LR
    subgraph PIM
    p1[Product Hat12]
    p11[Product HatRed16]
    p12[Product HatBlue17]
    p1-->p11
    p1-->p12
    end
    subgraph ECS
    ep1[Product HatRed16]-->es1[Sku HatRed16]
    ep2[Product HatBlue17]-->es2[Sku HatBlue17]
    end
    PIM-->ECS

Family with color and size variants

flowchart TD
    a[Product Family]
    aa[Color Variant A]
    ab[Color Variant B]
    aaa[Size Variant AA]
    aab[Size Variant AB]
    aba[Size Variant BA]
    abb[Size Variant BB]
    a --> aa
    a --> ab
    aa --> aaa
    aa --> aab
    ab --> aba
    ab --> abb

From the example we would transfer 2 product and 4 sku's to ECS where each product is part of the same Family

flowchart TB
    subgraph PIM
    p1[Product Hat12]
    p11[Product HatRed16]
    p12[Product HatBlue17]
    p111[Product HatRedXS32]
    p112[Product HatRedXL33]
    p121[Product HatBlueXS35]
    p122[Product HatBlueXL36]
    p1-->p11
    p1-->p12
    p11-->p111
    p11-->p112
    p12-->p121
    p12-->p122
    end
    subgraph ECS
    ep1["`Product HatRed16
    Family Hat12`"]
    ep2["`Product HatBlue17 
    Family Hat12`"]
    es11[Sku HatRedXS32]
    es12[Sku HatRedXL33]
    es21[Sku HatBlueXS35]
    es22[Sku HatBlueXL36]
    ep1-->es11
    ep1-->es12
    ep2-->es21
    ep2-->es22
    end
    PIM-->ECS

Deep product structure

flowchart LR
    a[Order]
    b[Family]
    c[Sub Family]
    d[Product]
    e[Variant]
    a --> b
    b --> c
    c --> d
    d --> e

In deep structures only the two last levels will be handled. From the sample above we would transfer 1 product and 1 sku ECS. The Product will be mapped as part of Sub Family

flowchart TB
    subgraph PIM
    a[Clothes]
    b[Shirts]
    c[T-Shirts]
    d1[Red]
    d2[Blue]
    e1[XL]
    e2[XL]
    a --> b
    b --> c
    c --> d1
    c --> d2
    d1 --> e1
    d2 --> e2
    end
    subgraph ECS
    ep1["`Red T-Shirt
    Family T-Shirts`"]
    ep2["`Blue T-Shirt 
    Family T-Shirts`"]
    es1[XL Red T-Shirt]
    es2[XL Blue T-Shirt]
    ep1-->es1
    ep2-->es2
    end
    PIM-->ECS

Setup

Use the Courier SDK or Courier API to setup a webhook configuration between PIM and ECS

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

using Bizzkit.Sdk.EcommerceSearch.Courier.Preview;

var factory = new CourierClientFactory(new CourierConnectionOptions
{
    BaseUrl = "courier-admin-host",
    Authority= "auth",
    ClientId= "client-id",
    ClientSecret= "client-secret",
    Scope = "courierapi/"
});

var client = await factory.CreateAuthenticatedClientAsync();

var settings = new BizzkitPimSettingsModel()
{
PimSegmentationId = 1
};

await client.UpsertBizzkitPimSettingsAsync("esc-segmentation-id", settings);

1
2
3
4
5
6

curl -X 'PUT' \
    'https://bizzkitqa-ecs-courier.bizzk.it/courier-api/esc-segmentation-id/bizzkit-pim/settings?api-version=25-Preview' \
    -H 'accept: text/plain' \
    -H 'Authorization: Bearer TOKEN \
    -H 'Content-Type: application/json' \
    -d '{ "pimSegmentationId": 1 }' 

There must be a configuration for each PIM segmentation that should be integrated with ESC and all configurations must be unique, meaning only one per PIM and ECS segment

After a configuration is created, products in the PIM segmentation will be created as Products and SKUs in ESC and any changes to products after this will also be added/updated/deleted in ECS

Attribute Mapping

By default the configuration handles all attribute values in PIM automatically using the following rules.

Product fields

For the ECS product fields the values will be taken from the first ancestor of the lowest product in the structure as described in Deep product structure. If the product is Standalone the values will be taken from the product itself.

Sku fields

The ECS sku fields will always be mapped from the lowest product in the structure

Besides this the following attribute types will be mapped

Pure string attributes

PIM string attributes will be mapped to ECS Sku.Metadata.AttributeName

E.g. [My Attribute].[Field1]='My attribute value' mappes to sku.metadata.my_attribute_1='My attribute value'

For multivalue attributes the values will added as a comma separated string

String attributes with a data source

PIM string attributes with a datasource (e.g. a global list) will be mapped to ECS Sku.StringAttributes.AttributeName

E.g. [My Attribute].[Field1] mappes to Sku.StringAttributes.my_attribute_1 as a key/value pair using the global list item name as key

For multivalue attributes the values will add individual key/value pairs

Numeric attributes

PIM numeric attributes will be mapped to ECS Sku.NumericValues.AttributeName where the value is an array of numbers

E.g. [My Attribute].[Field1] mappes to Sku.NumericAttributes.my_attribute_1 as a key/value pair using the name of the attribute as key

For multivalue attributes the values will added to the value array using the name of the attribute as key

Interval attributes

A special case is PIM attributes with exactly 2 numeric fields. These will handled as interval attributes

E.g. [My Attribute].[Field1] and [My Attribute].[Field2] mappes to Sku.IntervalAttributes.my_attribute

Other attribute types

The following PIM attributes will be mapped to ECS Sku.Metadata.AttributeName

Mapping overriding

Via the Courier API it is possible to configure an attribute mapping to override the automatic mapping. This is usefull for when using other attributes than the automatic configuration uses.

Any attribute/field configured in the manual mapping models will not be handled during automatic mapping, but instead be used as specified in the manual mapping. This way a String attribute or a Numeric attribute can be mapped as Pure string attribute if desired.

In this example alternative fields are configured for ProductId and ShortDescription. Additionally the PIM attribute MY_CUSTOM_NUMBER is mapped manually as meta-data

 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

using Bizzkit.Sdk.EcommerceSearch.Courier.Preview;

var factory = new CourierClientFactory(new CourierConnectionOptions
{
    BaseUrl = "courier-admin-host",
    Authority= "auth",
    ClientId= "client-id",
    ClientSecret= "client-secret",
    Scope = "courierapi/"
});

var client = await factory.CreateAuthenticatedClientAsync();

var settings = new BizzkitPimSettingsModel()
{
    PimSegmentationId = 1,
    Mappings = new BizzkitPimMappingsModel()
    {
        ProductId = new BizzkitPimFieldModel { SystemName = "PRODUCT_ID", FieldIndex = 1},
        ShortDescription = new BizzkitPimFieldModel { SystemName = "SUMMARY", FieldIndex = 1},
        SkuMetaData = [ new BizzkitPimFieldModel { SystemName = "MY_CUSTOM_NUMBER", FieldIndex = 1 }]
    }
};

await client.UpsertBizzkitPimSettingsAsync("esc-segmentation-id", settings);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

curl -X 'PUT' \
    'https://bizzkitqa-ecs-courier.bizzk.it/courier-api/esc-segmentation-id/bizzkit-pim/settings?api-version=25-Preview' \
    -H 'accept: text/plain' \
    -H 'Authorization: Bearer TOKEN \
    -H 'Content-Type: application/json' \
     -d '{
    "pimSegmentationId": 1,
    "mappings": {
        "productId": {
            "systemName": "PRODUCT_ID",
            "fieldIndex": 1
        },
        "shortDescription": {
            "systemName": "SUMMARY",
            "fieldIndex": 1
        },
        "skuMetaData": [
            {
                "systemName": "MY_CUSTOM_NUMBER",
                "fieldIndex": 1
            }
        ]
    }
}'

Manually configurable attribute mappings

The following mappings can be manually configured

If an attribute uses multiple fields it is possible to map each underlying field. E.g. StringAttributes = [new BizzkitPimFieldModel { SystemName = "MY_CUSTOM_NUMBER", FieldIndex = 3 }].

Manual mapping only

It is also possible to completely disable automatic mapping of attributes. In this case only ProductId and SkuId will use the default value UNIQUE_NAME. All other mappings must be configured manually

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

using Bizzkit.Sdk.EcommerceSearch.Courier.Preview;

var factory = new CourierClientFactory(new CourierConnectionOptions
{
    BaseUrl = "courier-admin-host",
    Authority= "auth",
    ClientId= "client-id",
    ClientSecret= "client-secret",
    Scope = "courierapi/"
});

var client = await factory.CreateAuthenticatedClientAsync();

var settings = new BizzkitPimSettingsModel()
{
    PimSegmentationId = 1,
    Mappings = new BizzkitPimMappingsModel()
    {
        MappingType = BizzkitPimMappingType.Manual
    }
};

await client.UpsertBizzkitPimSettingsAsync("esc-segmentation-id", settings);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

curl -X 'PUT' \
    'https://bizzkitqa-ecs-courier.bizzk.it/courier-api/esc-segmentation-id/bizzkit-pim/settings?api-version=25-Preview' \
    -H 'accept: text/plain' \
    -H 'Authorization: Bearer TOKEN \
    -H 'Content-Type: application/json' \
     -d '{
    "pimSegmentationId": 1,
    "mappings": {
        "mappingType": "Manual"
    }
}'