pCon.basket - Integration
    Preparing search index...

    pCon.basket - Integration

    API Version 2.9.0 (Basket 2.15.0)
    Date 2025-10-29


    When integrating pCon.basket the host system has to communicate with multiple services. Here is an overview of these services:

    pCon.basket provides the UI and can be seen as the user frontend for the EAIWS.

    1.2 pCon.configurator online / EAIWS

    The EAIWS is the central web service (backend) of pCon.basket and provides access to the article list and OFML article data. More details can be found in the EAIWS documentation.

    Documentation: https://docs.pcon-solutions.com/pCon/configuratorOnline/latest/pCon.configurator_Online_EAIWS_Specification.pdf

    pCon.login is responsible for the user authentication and authorization. It also controls the access to the OFML manufacturer data for each user.

    Documentation: https://login.pcon-solutions.com/doc/api/

    The Gatekeeper controlls the access to the EAIWS servers and is used as a service to create an EAIWS session. It also acts as a load balancer and switches between multiple EAIWS servers.

    Documentation: https://docs.pcon-solutions.com/webservice/gatekeeper/v3/index.html

    pCon.basket supports two modes. The standalone and the integration mode. By default it is running in standalone mode. In order to integrate pCon.basket into a host system the integration mode has to be used.
    pCon.basket can be run in an iframe/popup window or an embedded browser. The Basket UI requires a minimum size of 1000x600 pixels.

    pCon.basket can be integrated in two ways the basic integration or advanced integration. It is recommended to use the basic integration but depending on the use case it may be required to switch to advanced integration.

    In basic integration mode pCon.basket handles everything related to login and session creation. The license is also handled by pCon.basket. When starting the basket the host system receives the EAWIS session from pCon.basket.

    The URL-Parameter mode=auth-integration, client_id=xx and gatekeeper_id=xx with your client and gatekeeper id has to be used to enable basic integration mode.
    Note: As the gatekeeper ID may contain special characters it needs to be URL encoded (e.g. by using encodeURIComponent()).
    Example:

    https://integration.basket.pcon-solutions.com/<VERSION>/?mode=auth-integration&client_id=xx&gatekeeper_id=xx

    Advantages:

    • easier integration because pCon.basket manages the EAWIS session and the license

    Disadvantages:

    • use of pCon.login is mandatory
    • background operations on the EAIWS session without the pCon.basket beeing opened are not possible (because pCon.basket manages the session and the license)

    In advanced integration mode the host is responsible to login the user and to create the EAIWS session. When starting pCon.basket the host provides the created session.

    The URL-Parameter mode=integration has to be used to enable advanced integration mode.
    Example:

    https://integration.basket.pcon-solutions.com/<VERSION>/?mode=integration

    Advantages:

    • support for self hosted scenarios
    • support for background operations on the EAIWS session without pCon.basket beeing opened
    • use of pCon.login is optional (self hosted EAIWS)
    • more control over the pCon.login process (e.g. use of long term tokens)

    Disadvantages:

    • more difficult to integrate if pCon.login is used because of session and license management

    The comunication between host and basket is based on browser message events (see window.postMessage()).
    The basket will send messages to the host by calling postMessage on its opener window if it is running in an own window/tab or on its parent if it is running in an iframe.
    To send a message to the basket, postMessage has to be called on its window. If it is running in an iframe the iframe's contentWindow has to be used.

    The actual data/message is stored in the data of the message event. Further information about the structure of the data and the available messages can be found in the typescript definitions (which are also part of this documentation) for the message API.

    EAIWS provides a SOAP-API which can be used directly using .NET, Java or any other language with SOAP support. For JavaScript the eaiws wrapper of the W-CF framework can be used.

    W-CF is a Javascript framework which provides a wrapper for the EAIWS SOAP-API. It is hosted on NPM under the name @easterngraphics/wcf. After installing it can be used like this:

    import { EaiwsSession } from "@easterngraphics/wcf/modules/eaiws";

    var session = new EaiwsSession();
    session.connect(...);

    Please follow the W-CF documentation for further details.

    If the basket is started in integration mode it will request a configuration during its initilization by sending a wbkHost.getConfiguration message to the host. The host then has to send back the configuration. The basket will pause until it receives the wbk.configuration message. This finishes the initialization and the baskets starts to operate on the current EAIWS session. If the basket is finished with its operations a wbkHost.done message will be send to the host. The host then performs further operations (e.g. reading article data) on the session and can close the basket window afterwards.

    Note: After the basket requested the configuration it will wait 10 minutes for the wbk.configuration message. After 10 minutes a timeout error will be shown.

    In this mode pCon.basket is taking care of the user login and the EAIWS session managment. The wbkHost.getConfiguration message containes the ID of the created EAIWS session and the logged-in user.

    The initialization sequence looks like this:

    If the basket is started in integration mode it will request a configuration during its initilization by sending a wbkHost.getConfiguration message to the host. The host then has to send back the configuration which has to include the ID of the EAIWS session. The basket will pause until it receives the wbk.configuration message. This finishes the initialization and the baskets starts to operate on the given session. If the basket is finished with its operations a wbkHost.done message will be send to the host. The host then can close the basket window and perform further operations on the session.

    The basic initialization sequence looks like this:


    A more detailed look at step 1: login + create EAIWS session can be seen in the following diagram. It illustrates the use of pCon.login and the Gatekeeper.

    If pCon.login is used and a license for pCon.basket was issued it is necessary to periodically notify the server using the updateToken message that the license is still in use. How to do this is illustrated as part of the integration example. Please see the startLicenseKeepAlive() function in the file src/LoginHandler.ts. Without this message the license will be released and the EAIWS session will be automatically closed.

    A booked license is valid and blocked for 1 minute. With every updateToken message the license will be valid for 1 additional minute. If the license expires the license will be released. That means the license can be used to create another EAIWS session. As a result the current EAIWS session is no longer licensed and will be automatically closed if the server is unable to get a valid license again. In detail it works like this:

    1. the license will be released (it can be used to create another EAIWS session)
    2. the current EAIWS session will be suspended/paused
      • a suspended EAIWS session stays valid and can be reactivated for up to 24 hours, after that it will be permanently closed
      • a suspended session gets automatically reactivated with any request for this session
    3. if the session gets reactivated the server waits up to 15 minutes for the next updateToken message and uses the new access token to book a new license
    4. if after 15 minutes the server is not able to get a license the EAIWS session will be permanently closed

    The featureSet option of the wbk.configuration message can be used to enable a predefined set of features for pCon.basket. Currently two feature sets are supported Full and Configurator.

    The feature set Full is enabled by default and enables all features. Individual features can be disabled using the various options of the wbk.configuration message (e.g.: restrictions or disabledPluginCategories).

    The Configurator feature set can be used if pCon.basket should run in configurator mode. That means pCon.basket is primarily used as a product configurator and not to manage a complete quote/article list.
    The following options will be used when this feature set is enabled:

    disabledPluginCategories: [
        "ItemList",
        "ItemStatusBar",
        "ItemSelector"
    ]

    user: {
        restrictions: [
            "project.calculation",
            "project.customer",
            "project.data",
            "project.data.projectValidToDate.setDefault",
            "project.partyInCharge",
            "project.terms",
            "project.tax",
            "item.calculation",
            "item.calculation.purchaseCalculation",
            "item.calculation.margin",
            "item.externalItemNumber",
            "item.folder.create",
            "item.ofmlArticle.userDescription",
            "item.setArticle.create",
            "item.setArticle.convertTo",
            "item.setArticle.breakUp",
            "item.textItem.create",
            "item.userArticle.create",
            "item.userArticle.convertTo",
            "item.mergeArticles",
            "item.splitUpCompositeArticles",
            "item.markAsAlternative",
            "item.markAsOptional",
            "report",
            "order"
        ]
    }

    It is possible to disable additional features by defining the corresponding options of the wbk.configuration message. If in your case a feature which is disabled by the Configurator feature set should be enabled, you have to use the Full feature set instead and specify a custom list of disabledPluginCategories and restrictions.

    pCon.basket provides multiple reporting templates and its possible to define the list of the available templates using the wbk.configuration message (see report.templates option). By default the following standard templates are available for every user:

    ID/Name Description
    basket-standard-pro-fop Quote
    basket-standard-pro-noprices Article Overview
    basket-standard-pro-comparison Product Comparison
    basket-standard-management-overview-fop Management Overview

    It is also possible that the current users pCon.login organization provides additional customized reporting templates. These customized reports are by default not filtered by the report.templates option and are always available. If you want to filter these templates you have to set the option report.filterUserTemplates to true.

    To finish the integration and close the basket window, the user can click on the "Done" button of the application. The basket will then finish all pending tasks and will send a wbkHost.done message back to the host afterwards. The basket window can then savely be closed by the host. Alternatively if the basket window should be closed without using the "Done" button the wbk.finishIntegration message should be send the basket window. After finishing all pending operations the basket will send the wbkHost.done message back to the host. It is not recommended to close the basket and access the EAIWS session without waiting for the wbkHost.done message. The basket may not be finished with certain tasks and this may result in loss of data.

    Note: In basic integration mode pCon.basket is managing the EAIWS session. If the basket window gets closed the EAIWS session will also be closed. As long as an access to the EAIWS session is required the window has to stay open.

    If you have a database/catalog with non-OFML articles and want to use them inside pCon.basket, you can use the "custom catalogs" feature to do this. To enable this feature you have to register your custom catalog as part of the wbk.configuration as shown in the integration example.

    pCon.basket supports two types of non.OFML catalogs. External Catalogs and Custom Catalogs.

    After registering the catalog you have to listen and handle the messages wbkHost.getCustomCatalogArticles and wbkHost.getCustomArticle to provide pCon.basket with the required catalog/article data.

    Illustration of the message sequence:

    If you provide an externalUrl when registering the catalog, the catalog will be handeld as external and embedded inside the basket UI using an iFrame. More details can be found in the external catalogs documentation.

    By default pCon.basket user settings are stored at the users pCon.login account. If pCon.login is not used the settings are used locally in the currently used browser. If you want to manage the settings in other ways a custom user settings storage can be implemented.

    The API for the user settings storage is disabled by default. It can be enabled as part of the wbk.configuration message. To enable it the userSettingsStorage flag of the application.supportedAPIs property has to be set to true.

    To store certain settings pCon.basket sends the wbkHost.setUserSetting message. Each setting is represented as a key/value string pair. If the value of a given setting is undefined the setting should be deleted from the storage.

    Important: The host application should not modify the recieved values as the structure of the values may change between basket releases.

    To load settings pCon.basket sends the wbkHost.getUserSetting message. In this case the parameter of the message represents the key of the requested setting. In response a wbk.userSetting message has to be send back to the basket. If the requested setting is unknown or has no value, undefined has to be used as the settings value for the wbk.userSetting message.

    User restrictions can be used to limit the access for the user to certain application features. The restrictions are defined as part of the wbk.configuration message. The list of available restrictions can be seen here:

    export type UserRestriction =
        /** Editing of project informations and items is not allowed. (read-only access) */
        "edit" |

        /** Editing the project informations is not allowed. (read-only access) */
        "project.edit" |

        /** The project calculation will not be available. */
        "project.calculation" |
        /** Editing the project calculation is not allowed. (read-only access) */
        "project.calculation.edit" |
        /** The project purchase calculation will not be available. */
        "project.calculation.purchaseCalculation" |
        /** Editing the project purchase calculation is not allowed. (read-only access) */
        "project.calculation.purchaseCalculation.edit" |
        /** The condition type will not be visible in the project calculation. */
        "project.calculation.conditionType" |
        /** The margin will not be visible in the project calculation. */
        "project.calculation.margin" |

        /** The project customer information will not be available. */
        "project.customer" |
        /** Editing the project customer information is not allowed. (read-only access) */
        "project.customer.edit" |
        /** Editing/switching the customer by using the customer search is not allowed. (read-only access) */
        "project.customer.search.edit" |
        /** Editing the general customer data is not allowed. (read-only access) */
        "project.customer.general.edit" |
        "project.customer.general.company.edit" |
        "project.customer.general.externalCustomerId.edit" |
        "project.customer.general.customerNumber.edit" |
        "project.customer.general.generalAgreementNumber.edit" |
        "project.customer.general.customerRelatedRemarks.edit" |

        /** The customer main address will not be available. */
        "project.customer.mainAddress" |
        /** Editing the customer main address is not allowed. (read-only access) */
        "project.customer.mainAddress.edit" |
        /** The customer shipping address will not be available. */
        "project.customer.shippingAddress" |
        /** Editing the customer shipping address is not allowed. (read-only access) */
        "project.customer.shippingAddress.edit" |
        /** The customer billing address will not be available. */
        "project.customer.billingAddress" |
        /** Editing the customer billing address is not allowed. (read-only access) */
        "project.customer.billingAddress.edit" |

        /** The project data will not be available. */
        "project.data" |
        "project.data.projectName" |
        "project.data.projectNumber" |
        "project.data.projectState" |
        "project.data.projectDate" |
        "project.data.projectValidToDate" |
        "project.data.externalReferenceNumber" |
        "project.data.externalReferenceText" |
        "project.data.description" |
        "project.data.keywords" |
        "project.data.dataLanguage" |
        "project.data.defaultPriceDate" |
        "project.data.headerText" |
        "project.data.footerText" |

        /** Text formatting functions for project texts will not be available. */
        "project.data.textFormatting" |
        /** Editing the project data is not allowed. (read-only access) */
        "project.data.edit" |
        "project.data.projectName.edit" |
        "project.data.projectNumber.edit" |
        "project.data.projectState.edit" |
        "project.data.projectDate.edit" |
        "project.data.projectValidToDate.edit" |
        "project.data.externalReferenceNumber.edit" |
        "project.data.externalReferenceText.edit" |
        "project.data.description.edit" |
        "project.data.keywords.edit" |
        "project.data.dataLanguage.edit" |
        "project.data.defaultPriceDate.edit" |
        "project.data.headerText.edit" |
        "project.data.footerText.edit" |

        /** User is not allowed to change the default "valid to date" used for new projects. */
        "project.data.projectValidToDate.setDefault" |

        /** User is not allowed to change the default data language used for new projects. */
        "project.data.dataLanguage.setDefault" |

        /** The project party in charge information will not be available. */
        "project.partyInCharge" |
        /** Editing the project party in charge information is not allowed. (read-only access) */
        "project.partyInCharge.edit" |
        /** User is not allowed to change the default party in charge used for new projects. */
        "project.partyInCharge.setDefaults" |

        /** The project currency and taxes will not be available. */
        "project.tax" |
        /** Editing currency and taxes is not allowed. (read-only access) */
        "project.tax.edit" |
        /** Currency exchange rates will not be available. */
        "project.tax.exchangeRates" |
        /** Editing the currency exchange rates is not allowed. (read-only access) */
        "project.tax.exchangeRates.edit" |
        /** User is not allowed to change the default exchange rates used for new projects. */
        "project.tax.exchangeRates.setDefaults" |
        /** Tax rates will not be available. */
        "project.tax.taxRates" |
        /** Editing the tax rates is not allowed. (read-only access) */
        "project.tax.taxRates.edit" |
        /** User is not allowed to change the default tax rates used for new projects. */
        "project.tax.taxRates.setDefaults" |

        /** The project terms will not be available. */
        "project.terms" |
        /** Editing the project terms is not allowed. (read-only access) */
        "project.terms.edit" |

        /** Editing or creating items is not allowed. (read-only access) */
        "item.edit" |

        /** Additional user defined item images will not be available. */
        "item.additionalImages" |

        /** Extra item texts (e.g. special model information) will not be available. */
        "item.extraTexts" |
        /** Editing the extra item texts is not allowed. (read-only access) */
        "item.extraTexts.edit" |

        /** The external item number of items will not be available. */
        "item.externalItemNumber" |
        /** Editing of the external item number of items is not allowed. (read-only access) */
        "item.externalItemNumber.edit" |

        /** The item comments will not be available. */
        "item.comments" |
        /** Editing of item comments item is not allowed. (read-only access) */
        "item.comments.edit" |

        /** The item calculation will not be available. */
        "item.calculation" |
        /** Editing the item calculation is not allowed. (read-only access) */
        "item.calculation.edit" |
        /** The item purchase calculation will not be available. */
        "item.calculation.purchaseCalculation" |
        /** Editing the item purchase calculation is not allowed. (read-only access) */
        "item.calculation.purchaseCalculation.edit" |
        /** The condition type will not be visible in the item calculation. */
        "item.calculation.conditionType" |
        /** The margin will not be visible in the item calculation. */
        "item.calculation.margin" |
        /** The `update condition amounts` function will not be available. */
        "item.calculation.updateConditionAmounts" |

        /** The item configuration will not be available. */
        "item.configuration" |
        /** Configuration of items/articles is not allowed. (read-only access) */
        "item.configuration.edit" |

        /** Creating folders will not be available. */
        "item.folder.create" |
        /** Folder sub totals will not be available. */
        "item.folder.subTotal" |
        /** Additional text for folders will not be available. */
        "item.folder.additionalText" |
        /** Full width images for folders will not be available (reporting only). */
        "item.folder.fullWidthImage" |

        /** Creating set articles will not be available. */
        "item.setArticle.create" |
        /** Converting a folder into a set article will not be available. */
        "item.setArticle.convertTo" |
        /** Breaking up a set article will not be available. */
        "item.setArticle.breakUp" |
        /** Full width images for set articles will not be available (reporting only). */
        "item.setArticle.fullWidthImage" |
        /** The option to collapse (hide sub items) for set articles will not be available (reporting only). */
        "item.setArticle.collapse" |

        /** Creating text items will not be available. */
        "item.textItem.create" |
        /** Additional text for text items will not be available. */
        "item.textItem.additionalText" |

        /** User defined description for OFML articles will not be available. */
        "item.ofmlArticle.userDescription" |
        /** Editing the user defined description for OFML articles is not allowed. (read-only access) */
        "item.ofmlArticle.userDescription.edit" |
        /** Updating/migrating ofml articles will not be available. */
        "item.ofmlArticle.update" |

        /** Creating user articles will not be available. */
        "item.userArticle.create" |
        /** Converting an article into a user article will not be available. */
        "item.userArticle.convertTo" |
        /**
         * Editing the purchase price of a user article is not allowed. (read-only access)
         * The purchase price will be linked to the sales price in this case.
         */
        "item.userArticle.purchasePrice.edit" |

        /** Merging articles will not be available. */
        "item.mergeArticles" |

        /** Splitting up composite articles will not be available. */
        "item.splitUpCompositeArticles" |

        /** Mark items as alternative (or vice versa) will not be available. */
        "item.markAsAlternative" |

        /** Mark items as optional (or vice versa) will not be available. */
        "item.markAsOptional" |

        /** It is not allowed to enter a negative quantity. */
        "item.quantity.negative" |
        /** It is not allowed to enter a zero quantity. */
        "item.quantity.zero" |

        /** Geometry export for articles will not be available. */
        "item.geometryExport" |
        "item.geometryExport.3ds" |
        "item.geometryExport.dwg" |
        "item.geometryExport.fbx" |
        "item.geometryExport.glb" |
        "item.geometryExport.usdz" |
        "item.geometryExport.pec" |

        /** Reporting will not be available. */
        "report" |

        /** Editing the report is not allowed. (read-only access) */
        "report.edit" |

        /** User is not allowed to change the default tamplate options used for new projects. */
        "report.template.options.setDefaults" |

        /** User is not allowed to add attachments and cover cheets. */
        "report.attachments" |

        /** Order information / placing an order will not be available. */
        "order" |

        /** Editing the order information is not allowed. (read-only access) */
        "order.edit" |

        /** Editing the order number is not allowed. (read-only access) */
        "order.orderNumber.edit" |

        /** Editing the order number is not allowed. (read-only access) */
        "order.vendorNumber.edit" |

        /** Editing the order main address is not allowed. (read-only access) */
        "order.mainAddress.edit" |

        /** Editing the order shipping address is not allowed. (read-only access) */
        "order.shippingAddress.edit" |

        /** Editing the order billing address is not allowed. (read-only access) */
        "order.billingAddress.edit" |

        /** Catalog search is not available */
        "catalog.search";

    The application language can be changed by the user in the application settings. It is also possible to pre-define the langauge by using the locale url paramter. In this case the user will not be able to change the language manually. Example:

    https://www.example-basket.com/?mode=integration&locale=en-US

    The Changelog can be found here: Changelog


    © 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.

    Settings

    Member Visibility

    On This Page

    1 Introduction2 Integration Mode3 Message API4 EAIWS API5 Session Initialization6 Finish Integration7 Custom Catalogs8 User Settings9 User Restrictions10 FAQ11 ChangelogLegal remarks