Concept - Buying Context

1 Introduction

Info

The buying context is part of the Intershop Commerce Management, released in 7.10.33.1, but it is also used in the upcoming Organization Hierarchy Service (OHS) which is currently still in development. 

As of 7.10.33 the Buying Context determines the checkout process in the Intershop Commerce Management (ICM) in addition to the settings for the Selling Organization (Channel) and buying user's customer assignment. The Buying Context was introduced in the context of the Organization Hierarchy Service (OHS). An organization hierarchy is a reflection of the customer's real organization structure. It is more detailed than ICM's previous customer representation having only one single entity.

1.1 Glossary

TermDescription
Buying ContextA Buying Context is formed by a Buying Organization's hierarchy tree and a specific node, called Group, of this tree.
Buying OrganizationActor that represents a self-contained business organization acting on the buy-side in Intershop Commerce Management.
GroupEntity of the hierarchy tree
ICMIntershop Commerce Management
OHSOrganization Hierarchy Service
PWAProgressive Web App

1.2 Organization Hierarchy Service (OHS)

The Organization Hierarchy Service (OHS) is the foundation for Buying Context creation. A Buying Context is formed by a Buying Organization's hierarchy tree and a specific node, called Group, of this tree.

Example: The Buying Organization BioTech and its Group BioTech_Jena form the Buying Context BioTech_Jena@BioTech.

The following diagram illustrates the big picture of the Buying Context and the basic interactions between the involved systems.

buying_context_communication_structure

The steps in the process are described as follows:

  1. The user logs in to PWA for the respective Buying Organization (former Customer).
  2. The OHS holds the hierarchy tree which a Buying Organization spans for its structural entities, like subsidiaries, departments, teams, etc. The nodes of the tree are called Groups. The PWA retrieves all Groups (entities of the hierarchy tree) the user is assigned to with a specific role, e.g. Buyer.
  3. From the list provided by the OHS in the PWA, the user selects the Group for which to place an order.
  4. When the user creates a new basket, the ID of the selected Group - and the ID of the Buying Organization (to identify the Group uniquely throughout all Buying Organization hierarchies) - are transmitted to ICM via a URL matrix parameter with the according REST request and every subsequent REST request to the /baskets resource as well as its sub-resources.
  5. ICM validates the values sent with the matrix parameter by a call to OHS to ensure that the Buying Organization and Group exist.

    Note

    A check if the user is authorized to order in this Buying Context is currently not performed and planned for future versions of OHS and ICM.
  6. The created basket is bound to the provided Buying Context and can only be manipulated and checked out in this context now.
  7. The basket's Buying Context is stored at the created order in the course of the basket checkout. This way the original Buying Context remains, even if the structure of the Buying Organization's hierarchy tree in OHS changes over the time.
  8. In the PWA the user requests placed orders for all or particular Buying Contexts. The filtering is done using the buyingContext query parameter.

2 PWA

A user of a Buying Organization can select a specific Group of this organization and place orders in the context of this Group. PWA forwards the selected Group to ICM via a matrix parameter inserted in the URL of arbitrary REST requests. The matrix parameter has the following structure: bctx={group_ID}@{buying_organization_ID}.

Example request to ICM
POST http://{host}:{port}/INTERSHOP/rest/WFS/inSPIRED-inTRONICS_Business-Site/rest;loc=en_US;cur=USD;bctx=BioTech_Jena@BioTech/baskets?include=all

Note

The length of the Buying Organization ID as well as the Group ID are limited to avoid exceeding the maximum URL length. Furthermore, these limitations are the reason why the matrix parameter's value does only contain the Buying Organization ID and the Group ID instead of the whole hierarchy path from the Buying Context's Group to hierarchy's root Group.

Note

The Buying Organization as well as Group ID of the Buying Context are case-sensitive.

3 ICM

3.1 Basic Structure

The Buying Context in ICM is represented by the following type:

com.intershop.component.organizationhierarchies.capi.buyingcontext.BuyingContext
public interface BuyingContext
{
	GroupPath getGroupPath();
	Group getRootGroup();
	Group getGroup();
	boolean isValidated();
	Optional<OrganizationServiceResult<GroupPath>> getServiceResult();
}

3.1.1 Group Path

The BuyingContext::getGroupPath() : GroupPath method returns the GroupPath type representing the whole path starting from Buying Context's Group upwards to Buying Organization hierarchy's root Group.

3.1.2 Root Group

The BuyingContext::getRootGroup() : Group method returns the root Group of Buying Organization's hierarchy.

3.1.3 Group

The BuyingContext::getGroup() : Group returns the Group representing the Buying Context.

3.1.4 Buying Context Validation

The result of the BuyingContext::isValidated() : boolean indicates whether the value provided by the Buying Context matrix parameter has already been validated by a call to the OHS. As this matrix parameter is provided by another system (e.g. PWA, arbitrary REST client) it might not be valid at all. Hence, ICM validates the provided value by calling OHS' REST interface to check if there is a representation for the Buying Organization and Group ID in the OHS.

3.1.5 Service Result of OHS Call

The result of the BuyingContext::getServiceResult() : Optional<OrganizationServiceResult<GroupPath>> indicates if the validation call to the OHS was successful or not. The returned OrganizationServiceResult<GroupPath> contains a status code and possible errors.

3.2 REST Servlet Filter

The REST Servlet Filter com.intershop.component.organizationhierarchies.capi.filter.BuyingContextRestFilter extracts the Buying Context from the bctx matrix parameter and makes it available to the Application.

3.3 Application

If a storefront REST request contains the Buying Context matrix parameter, the related Buying Context is available via com.intershop.component.organizationhierarchies.capi.buyingcontext.ApplicationBOBuyingContextExtension. A shortcut to retrieve the current request's Buying Context is provided by com.intershop.component.organizationhierarchies.capi.buyingcontext.CurrentBuyingContextProvider.

3.4 Basket

Baskets are Buying Context-aware in ICM now. This means, that a basket bound to a specific Buying Context is only retrievable and valid in this context.

3.4.1 Database Layer

The Buying Context is stored in the BASKET table in the following columns:

  • BUYINGCONTEXTORGANIZATIONID (VARCHAR256) - Stores the ID of the Buying Organization in OHS.
  • BUYINGCONTEXTGROUPID (VARCHAR256) - Stores the ID of the Group in OHS.

3.4.2 Business Object Layer

The Buying Context which a basket is bound to is retrievable via com.intershop.component.basket.capi.extension.BasketBOBuyingContextExtension on the Business Object layer.

3.4.3 REST

The payload of the basket includes the Buying Context the basket is bound to.

GET /baskets/<basket_id>
{
    "data": {
        ...
        "buyingContext": "BioTech_Jena@BioTech",
        ...
    }
} 

3.5 Order

In the course of the order creation, the Buying Context which the ordered basket is bound to is stored at the order by the com.intershop.component.order_orm.internal.handlerchain.BuyingContextOrderCreationHandler implementation. In contrast to the basket which only stores the values of the Buying Organization ID and Group ID, the whole Group path is stored at the order to keep this information at the order even if the structure of the Buying Organization's hierarchy tree in OHS changes over the time.

3.5.1 Database Layer

The complete Group path of the Buying Context is stored in the ISORDERBUYINGCONTEXT table.

3.5.2 Business Object Layer

The Buying Context of an order is retrievable via com.intershop.component.order.capi.extension.OrderBOBuyingContextExtension on the Business Object layer. The OrderBOBuyingContextExtension::createBuyingContext(BasketBO basketBO) : BuyingContext method creates the Buying Context for the order from the specified basket.

3.5.3 REST

The payload of the order includes the Buying Context which the order's basket was bound to. Additionally, the whole Group path - starting from the root Group downwards to Buying Context's Group - is returned as include if the value buyingContext is specified for the include query parameter.

GET /orders?include=buyingContext&filter[buyingContext]=BioTech_Jena@BioTech
{
    "data": {
        ...
        "buyingContext": "BioTech_Jena@BioTech",
        ...
    },
    "included": {
        "buyingContext": {
            "BioTech_Jena@BioTech": {
                "groupId": "BioTech_Jena",
                "groupName": "Bio Tech Location Jena",
                "groupPath": [
                    {
                        "groupId": "BioTech_Root",
                        "groupName": "Bio Tech Root"
                    },
                    {
                        "groupId": "BioTech_EMEA",
                        "groupName": "Bio Tech EMEA"
                    },
                    {
                        "groupId": "BioTech_Germany",
                        "groupName": "Bio Tech Germany"
                    },
                    {
                        "groupId": "BioTech_Jena",
                        "groupName": "Bio Tech Location Jena"
                    }
                ],
                "organizationId": "BioTech"
            }
        },
        ...
    }
} 

In case of order list REST requests it is possible to filter orders by their Buying Context. The filtering is done using the filter[buyingContext] query parameter.


Note

The matrix parameter bctx cannot be used for order filtering at all. The reason is that a user may request historical orders created for a Buying Context which does not exist any longer due to changes in the Buying Organization hierarchy.
Example: Buying Organization BioTech decided to close the subsidiary BioTech_Erfurt  in the course of a company restructuring. However, a user might check some orders created in the Buying Context BioTech_Erfurt after a certain period of time. If the orders were filtered by the value of the matrix parameter bctx, the PWA would be forced to set a parameter value that is no longer valid because the Group BioTech_Erfurt was deleted from the Buying Organization's hierarchy some time before. Furthermore, ICM would fail if it tried to validate a non-existing Buying Context at OHS.

This is the reason for orders being filtered by a query parameter and being ignored in the case of a GET request to the /orders resource.


Note

The Buying Organization as well as Group ID of the Buying Context are case-sensitive.

4 Limitations

4.1 Unsupported Features

Currently Buying Context is not supported for the following features:

  • Subscriptions (Recurring Orders)
  • Approval

4.2 Open Issues

4.2.1 Basket Merge

When an unauthenticated user creates a new basket and logs in to ICM later, the line items of this basket are merged to a possibly existing basket that has been created in the context of the user account before. This is no problem as long as the user is assigned to exactly one customer. It needs to be decided which of the user's baskets the one of the unauthenticated user should be merged with if the registered user owns several active baskets bound to different Buying Context instances. The required adjustments have to be made in the PWA.

4.2.2 Authorization

Currently there is no check whether a user is permitted to order for a specific Buying Context. This is going to be supported in the course of the introduction of a role concept in OHS and an authorization token functionality.


Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets