PIM integration

flowchart TB
    subgraph PIM
        P[PIM API]
    end
    subgraph U[Customer Solution]
        W
        J[JobServer]
        H[Webhooks]
    end
    J --> P
    P -.-> H
    W[Website] --> P

The Bizzkit PIM integration is implemented in the project Blueprint.Integration.PIM. We use the Bizzkit.Sdk.Pim Nuget package to call the API.

The configuration for the customer solution's PIM integration is in the appsettings-json files in the project. The configuration file for the PIM product itself is linked in the Config-solutionfolder for easy access.

The calls from the PIM API back to the customer solution are webhooks. These are endpoints configured in the PIM, that it uses to notify the customer solution about specific events.

PIM API

We use the following API endpoints via IPimClient:

Endpoint	Used for
`ResolvedViews_AttributeFieldValues_ResolveAsync()`	Getting resolved attribute values
`ResolvedViews_Attributes_SearchAsync()`	Getting attribute names
`Attributes_CreateAsync()`	Setting up attributes
`Attributes_ListAsync`	Setting up attributes
`GlobalLists_ListAsync()`	Setting up attributes
`GlobalLists_CreateAsync()`	Setting up attributes
`AttributeGroups_ListAsync`	Setting up attribute groups
`Brands_ImportFromCsvAsync()`	Creating brands
`ResolvedViews_Brands_SearchAsync()`	Getting brands
`DomainEvents_ListAsync()`	Setting up webhooks
`DomainEvents_UpdateAsync()`	Setting up webhooks
`DomainEvents_GetAsync()`	Setting up webhooks
`ResolvedViews_Products_Families_SearchAsync`	Getting product data (export)
`Products_ImportFromCsvAsync()`	Creating products (import)
`ResolvedViews_ProductHierarchies_SearchAsync()`	Getting product categories
`ProductHierarchies_ImportFromCsvAsync()`	Creating product categories
`Channels_CreateAsync()`	Creating channels
`Channels_ListAsync()`	Getting channels
`Devices_CreateAsync()`	Creating devices
`Devices_ListAsync()`	Getting devices
`Markets_CreateAsync()`	Creating markets
`Markets_ListAsync()`	Getting markets
`Segmentations_CreateAsync()`	Creating segmentations
`Segmentations_ListAsync()`	Getting segmentations
`TranslationCultures_CreateAsync()`	Creating translation cultures
`TranslationCultures_ListAsync()`	Getting translation cultures

Note, that we use CSV files to create brands, categories and products. More about that later.

Segmentations

Instead of having to manually setup segmentations in the PIM for each environment we have some predefined segmentations configured in code. You can find them in the static class PredefinedSegmentation.

These segmentations are syncronized with the PIM when you run the UpdateAttributeConfigurationJob which will check if they exist and otherwise create them.

You should modify these predefined segmentations so they fit your solution.

Note

These predefined configurations are optional to use, but make it easier to setup the solution, because you can rely on them being in the PIM.

Attributes

Similar to predefined segmentations we also have some predefined attributes that are configured in code. You can find them in the static class PredefinedAttributes. There are also attribute groups defined in the static class PredefinedAttributeGroups.

These atttributes are syncronized with the PIM when you run the UpdateAttributeConfigurationJob which will check if they exist and otherwise create them.

The attributes you need to use in the import of products (eg. from an ERP system) you should add to the predefined attributes. This way you know they are present in the PIM when you run the product import.

Brands

Brands are listed and created using the BrandRepository.

To create categories it uses a BrandCsvWriter. If you need to add custom attributes to brands, you will need to modify this in addition to modifying the mapping of brand views to the domain model. The model we use out of the box is super simple. Each brand only consists of an id and display name.

Products

As described in the products documentation product data often comes from an ERP-system, gets imported to the PIM to get enriched for web presentation and then exported and indexed in a search index.

Import

Importing products into the PIM is done using CSV files. The input to the import is a list of ImportProduct-objects. Feel free to modify this class and the ProductCsvWriter.CreateCsvObjects() to fit your specific import needs.

Export

Exporting products is done using the ResolvedViews_Products_Families_SearchAsync API call and then resolving the referential attributes afterwards. This is done in the ProductViewRepository. There are support for most scenarios out of the box, but not everything possible in the PIM. It will throw an exception if there is some attribute configuration or field type that can't be resolved or mapped.

Specifically regarding referential values only the following types are supported out of the box:

CMS articles
DAM files
Brands
Products
Youtube videos

For simple field values the following types are supported:

Bool
Char
Int16
Int32
Int64
Decimal
Guid
DateTime
DateTimeOffset
TimeSpan
String

Up to 4 fields per attribute is supported. Both plain and ranges are supported. Multivalue attributes are supported.

When you ask for product views you get a dictionary back where they key is the product variant tree height and the values are lists of views. It is separating them by tree height, because the products need to be mapped to the search index in different ways depending on whether a product family has variants or no variants. See the products documentation for details on this.

Webhooks

Webhooks are configured and setup from code as well. You can find them in the static class PredefinedWebhooks.

These webhooks are syncronized with the PIM when you run the UpdateAttributeConfigurationJob which will check if they exist and otherwise configure them.

The code that sets up the API for the webhooks are in the project Blueprint.Integration.PIM.Webhooks. This is a small ASP.NET Core API that handles the various PIM events. The API gets hosted in the Blueprint.Presentation.Webhooks site.