web-api

Contains methods for accessing the Catalogue API, including helper methods and classes. We strongly suggest you make use of it when accessing the Catalogue API.

CatalogueAPI

The CatalogueAPI-class contains methods for accessing making requests to the Catalogue API.

Example

const api = new CatalogueAPI();
api.auth = auth; // Where auth is an AuthorizeResponse object

// ...and now you can for example do...x

const toc = await api.getTocTree({ lang, enterprise, prdCat, prdCatVersion, vendor, priceList });

// ...and now you have a list of Products for your given Catalogue, Vendor and PriceList.

CatalogueAPI browserless

CatalogueAPI uses fetch internally, which normally comes from the browser. In order to use the CatalogueAPI without a browser, you need to replace this fetch function with one that can be used without a browser. One such example is Node-fetch, which would look like this:

import fetch from "node-fetch";

const api = new CatalogueAPI(fetch);

CfgProduct

CfgProduct is a class that is responsible for keeping track of your product. Loading the product, loading Additional Products, handling the configuration of the product, revalidating when changing options and such. This class is required to use babylon-view or babylon-view-react. The CfgProductConfiguration class mentioned below is internal in the class, so no need to explicitly use it.

CfgProductSettings

Type representing the configuration settings for a product in a catalogue. This can be passed when creating a CfgProduct. Example below:

{
    /**
     * Specifies whether a select-one Feature must have exactly one Option set at a time.
     * If set to true, an error will be thrown if more or less than one Option is selected. This enforcement is
     * not available in Catalogue Creator, and some catalogues may not meet this requirement. Defaults to false.
     */
    strictSelectOneSelectionCount: boolean,
    /**
     * Controls if SyncGroups are applied Faster or Stricter.
     *
     * Fast - Tries to minimize the number of validation calls to the API to lower the response times
     * for selecting options. Might not always give the expected result for complex products.
     *
     * Strict - Apply the SyncGroups rules in a stricter fashion to be as close to CET as possible,
     * which might result in longer response times and more validation calls to the API when
     * selecting options.
     *
     * The SDK will default to Strict, but we recommend that you try out Fast since cases where the
     * results differ should be rare in most real uses cases and the speedup can be quite large.
     */
    syncGroupsApplyMode: SyncGroupsApplyMode | undefined,
    /**
     * Controls checking each Option in a Feature group for duplicate descriptions. This comparison check can
     * take a really long time as the Feature group grows in size.
     *
     * The SDK will default this to enabled.
     */
    disableMatchOnDescription: boolean,
}

Note: The SDK provides default values for the above properties if not explicitly set.

ApiSelection v/s DtoConf

Since version 2.0 of the SDK there are two different versions of the methods used to set or get the Configuration of a Product.

ApiSelection (setApiSelection and getApiSelection) are the older ones. These use a format which is close to the internal representation in Catalogues. This is the format which is used to communicate with the API, so these methods can be useful if you for some reason need data which is compatible with the API calls.

DtoConf (setDtoConf and getDtoConf) are the newer ones. These use a format designed to:

Be easy to read.
Be more robust. The old format excludes information about what Features selected Options belong to and assume this information can be understood from context. This information is explicit in the new format.
Can be requested to contain extra data like GroupCodes, Units and Product Parameters. While this is strictly speaking not part of the Configuration, it can be very useful for external applications. (The extra data is ignored if included in data sent into the system).

DtoAdditionalProductConf v/s DtoAdditionalProductConfiguration

The old structure for Product Configuration uses the objects DtoAdditionalProductConfiguration and DtoSelectedOption. DtoAdditionalProductConfiguration is used for both the root Product and actual Additional Products. The new structure uses DtoProductConf, DtoAdditionalProductConf, DtoFeatureConf and DtoOptionConf. DtoProductConf is the used for root Products and DtoAdditionalProductConf for child Products.

A simple rule is that anything named Conf is the new version.

DtoProductConf objects can be converted into the old format using the method convertDtoProductConfToV1.

Initial product configuration

An initial Product Configuration in the DtoProductConf or DtoAdditionalProductConfiguration formats can be passed to CfgProduct.make to load the Product with the passed Product Configuration from the start. As is always the case when applying a Product Configuration it has to be compatible with the Product. Care has to be taken so that the Catalogue-maintainer does not change the Product in such a way that this stops being the case.

When a Product is initialized with an initial Product Configuration Reset will be to that configuration.

Example on how to use CfgProduct

const product = await CfgProduct.make(
    api, // Here you pass something that can do product calls. Normally this will be an instance of the API
    {
        lang,
        enterprise,
        prdCat,
        prdCatVersion,
        vendor,
        priceList,
        partNumber,
    },
    settings, // Here you can pass in settings (CfgProductSettings) to modify certain behaviors
    initialProdConf // Here you can optionally pass an initial product configuration
);

setCfgProduct((oldProduct) => {
    if (oldProduct !== undefined) {
        oldProduct.destroy();
    }
    return product;
});

const product = await CfgProduct.make({
    api,
    {
        lang,
        enterprise,
        prdCat,
        prdCatVersion,
        vendor,
        priceList
        partNumber,
    },
});

product.listenForChange((newRef) => {

    // Someone has changed something for this product, let's rerender GUI
    rerender();

});

// own to let the user make selections and thus configure your amazing product, but for the sake of
// this example we'll add a line selecting an option (provided it happens to exist in your Product).

await product.configuration.features[1].options[3].features[3].options[7].setSelected(true);

// ... which will trigger the change event and thus make the code above perform update the GUI. (And internally validations and sub product loading might be triggered)
// The await is optional. If you have it your code will wait for all consequences of the setSelected until it continues. Including validation calls to the server. Not having it will make the code continue directly.

An example showing how to try to make user selections survive changing product


const oldProduct = getProduct();

const newProduct = await CfgProduct.make({
    api,
    {
        lang,
        enterprise,
        prdCat,
        prdCatVersion,
        vendor,
        priceList
        partNumber,
    },
});

if (oldProduct !== undefined) {
    // true as the second argument below will make it try to match on descriptions, not code.
    const updateHappened = await newProduct.tryMatchSelection(oldProduct, true);

    // If we got false this means no change happened. This either means that they already had the same selections, or there were no matching properties to update. Validation is done internally, and newProduct will do notifications, so we probably don't need to use updateHappened
    if (updateHappened) {
        // Show smiley face
    }
}

// ... and now we are ready to use the data
setProduct(newProduct);

CfgProductConfiguration

CfgProductConfiguration is a class that can be used as a middle layer between the Product Configuration API-methods and your GUI. It makes some aspects of the product configuration easier to understand. It is used internally by the CfgProduct class and you do not need to instantiate it yourselves.

configurationGenerator

This package also contains the configurationGenerator which can be used to traverse all Products in one or more Catalogues. This is can be used to do slide-show like apps or as we use it in test-app, for testing multiple products.

CatalogueAPI​

Example​

CatalogueAPI browserless​

CfgProduct​

CfgProductSettings​

ApiSelection v/s DtoConf​

DtoAdditionalProductConf v/s DtoAdditionalProductConfiguration​

Initial product configuration​

Example on how to use CfgProduct​

An example showing how to try to make user selections survive changing product​

CfgProductConfiguration​

configurationGenerator​