pCon.basket - External Catalogs

API Version 1.1.0
Date 2023-08-21


Content

▶︎
all
running...

1 Introduction

This document describes how to integrate a product catalog or configurator into pCon.basket. External catalogs are embedded using an HTML IFrame. Thus a public HTTPS URL for the catalog has to be provided.
The communication between pCon.basket and the catalog is done using postMessage. More information can be found here: Window.postMessage()

The basic sequence for the catalog integration looks like this:

sequenceDiagram autonumber actor U as User participant B as Basket participant C as External<br/>Catalog U ->> B : user selects catalog in basket UI activate B B ->> C : load catalog URL in iframe deactivate B activate C C ->> B : request catalog parameters <br/> message: wbk.externalCatalog.getCatalogParameters deactivate C activate B B ->> C : send catalog parameters <br/> message: wbk.externalCatalog.catalogParameters deactivate B activate C C ->> C : process catalog parameters U ->> C : user selects/configures articles in catalog C ->> B : send article data <br/> message: wbk.externalCatalog.insertArticles deactivate C activate B B ->> B : insert articles into article list deactivate B

2 Catalog Registration

For an external catalog to be visible in pCon.basket, it must be registered. This can be done as part of the OFML data registration. Please follow the DSR specification for further information. If you are integrating pCon.basket it is also possible to register catalogs using the integration API.

Catalogs which are specified in DSR have to provide a logo image. This image has to be a JPEG with the name catalog-logo.jpg that is hosted in the root folder of the catalog website.

For example the image URL for the catalogs https://www.example.com and https://www.example.com/my-catalog.html
will be https://www.example.com/catalog-logo.jpg.

If you are using the integration API to register the catalog you may specify a custom logo URL. Please check the Integration Example for an example.

3 Message API

pCon.basket will send messages to the catalog by calling postMessage on the iframe's contentWindow. To send a message to the basket, postMessage has to be called on the parent window of the catalog.

The actual message and its parameters are stored in the data of the message event. Every message data has the following structure:

interface MessageData
{
    /** message identifier */
    type: string;
    /** optional parameter of the message */
    parameter?: string | object;
}

4 Catalog Parameters

To initialize the product catalog/configurator with the correct language, currency and other settings the catalog has to request the catalog parameters upon startup. This is done using the wbk.externalCatalog.getCatalogParameters message. The basket will respond with the a wbk.externalCatalog.catalogParameters message. The parameter of the received message has the following structure.

interface CatalogParameters
{
    /** preferred locale for the external catalog UI */
    locale: string;
    /** preferred currency for article prices */
    currency: string;
    /** preferred language for article data in order of priority */
    language: Array<string>;
    /** currently active tax scheme */
    taxScheme: TaxScheme;
    /** active color scheme of the basket */
    theme: Theme;
}

///// subtypes /////

interface TaxScheme
{
    id: string;
    country: string;
    region: string;
    taxTypes: Array<TaxType>;
}

interface TaxType
{
    id: string;
    rateUnit: string;
    taxCategories: Array<TaxCategory>;
}

interface TaxCategory
{
    id: string;
    rate?: number;
}

interface Theme
{
    primaryColor: string;
    textColor: string;
    fontFamily: string;
}

The following JavaScript code snippet demonstrates how the catalog parameters can be requested:

//register event handler for incoming messages
window.addEventListener("message", onMessage);

//request catalog parameters
window.parent.postMessage({ type: "wbk.externalCatalog.getCatalogParameters" }, "*");

//function which handles all incoming messages
function onMessage(pEvent) {
    if (pEvent.data.type === "wbk.externalCatalog.catalogParameters") {     
        //... process the catalog parameters here
        console.dir(pEvent.data.parameter);
    }
}

5 Sending Articles to pCon.basket

When the user is finished selecting or configuring the articles in the catalog the selected articles have to be sended to the basket. This is done using the wbk.externalCatalog.insertArticles message. The message expects an array of articles as parameter. pCon.basket supports two kinds of articles, Custom and Ofml.

5.1 Custom Articles

Custom articles are user defined articles and usually do not exist in any OFML catalog. The data structure of a custom article looks like this:

interface CustomArticle
{
    type: "Custom";
    manufacturerId?: string;
    seriesId?: string;
    baseArticleNumber?: string;
    finalArticleNumber?: string;
    variantCode?: string;

    /**
     * Quantity of the article
     * @defaultValue 1
     */
    quantity?: number;

    /** short text as simple string or as multi language map (language code -> text) */
    shortText?: string | { [language: string]: string };
    /** long text as simple string or as multi language map (language code -> text) */
    longText?: string  | { [language: string]: string };
    /** feature text as simple string or as multi language map (language code -> text) */
    featureText?: string | { [language: string]: string };

    /** Additional comments/notes for this article. */
    comments?: string;

    purchasePrice?: Money;
    salesPrice?: Money;
    packagingInfo?: PackagingInfo;

    /** Map from tax type to tax category for the active tax scheme. */
    taxes?: { [type: string]: string };

    /**
     * Url or data-URI for the article image.
     * Currently only jpg and png images are supported.
     */
    imageUrl?: string;
}

///// subtypes /////

interface Money
{
    value: number;
    currency: string;
}

interface Value
{
    value: number;
    unit: string;
}

interface PackagingInfo
{
    width?: Value;
    height?: Value;
    depth?: Value;
    volume?: Value;
    tareWeight?: Value;
    netWeight?: Value;
    itemsPerPackUnit?: number;
    packUnitsPerArticle?: number;
}

5.2 OFML Articles

OFML articles are predefined articles which can only be inserted if the user has access to the corresponding OFML catalog. The data structure of an OFML article looks like this:

interface OfmlArticle
{
    type: "Ofml";
    manufacturerId: string;
    seriesId: string;
    baseArticleNumber: string;
    variantCode?: string;
    ofmlVariantCode?: string;

    /**
     * Quantity of the article
     * @defaultValue 1
     */
    quantity?: number;
}

5.3 Example

The following JavaScript code snippet demonstrates how to send two custom articles to the basket:

window.parent.postMessage({
    type: "wbk.externalCatalog.insertArticles",
    parameter: [
        {
            type: "Custom",
            manufacturerId: "TEST",
            seriesId: "OFFICE",
            baseArticleNumber: "office-chair",
            shortText: "Office Chair",
            salesPrice: { value: 100, currency: "EUR" }
        },
        {
            type: "Custom",
            manufacturerId: "TEST",
            seriesId: "OFFICE",
            baseArticleNumber: "office-tabel",
            shortText: "Office Table",
            salesPrice: { value: 200, currency: "EUR" }
        }
    ]
}, "*");

6 History

Version 1.1.0

Version 1.0.0


© EasternGraphics GmbH | Albert-Einstein-Straße 1 | 98693 Ilmenau | GERMANY

This work (whether as text, file, book or in other form) is copyright. All rights are reserved by
EasternGraphics GmbH. Translation, reproduction or distribution of the whole or parts thereof is permitted only with the prior agreement in writing of EasternGraphics GmbH.

EasternGraphics GmbH accepts no liability for the completeness, freedom from errors, topicality or continuity of this work or for its suitability to the intended purposes of the user. All liability except in the case of malicious intent, gross negligence or harm to life and limb is excluded.

All names or descriptions contained in this work may be the trademarks of the relevant copyright owner and as such legally protected. The fact that such trademarks appear in this work entitles no-one to assume that they are for the free use of all and sundry.