2. Introduction

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.

2.1. Glossary

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

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.

3. 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}.

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

4. ICM

4.1. Basic Structure

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

4.1.1.1.1. com.intershop.component.organizationhierarchies.capi.buyingcontext.BuyingContext

public interface BuyingContext
{
	GroupPath getGroupPath();
	Group getRootGroup();
	Group getGroup();
	boolean isValidated();
	Optional<OrganizationServiceResult<GroupPath>> getServiceResult();
}

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

4.1.2. Root Group

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

4.1.3. Group

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

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

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

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

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

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

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

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

4.4.3. REST

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

4.4.3.1.1. GET /baskets/<basket_id>

{
    "data": {
        ...
        "buyingContext": "BioTech_Jena@BioTech",
        ...
    }
} 

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

4.5.1. Database Layer

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

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

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

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

5. Limitations

5.1. Unsupported Features

Currently Buying Context is not supported for the following features:

• Subscriptions (Recurring Orders)

• Approval

5.2. Open Issues

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

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