Inventory service layer

The inventory service layer provides read-only integration with inventory / stock information from an external commerce system (ECS). However, you can extend this service layer to support read-write integration if desired.

You can find all configuration for the inventory service layer n the Sitecore.Commerce.Inventory.config file. Here you will find all details for the entities, pipelines, and repositories used by the inventory system.

Note

We highly recommend that you do not modify this file when adding your ECS connector components to the pipelines, overriding entity definitions, and so on. Instead, use Sitecore configuration patching, and include all of your ECS configuration in a separate file named {ECSName}.Connectors.Inventory.config.

In the stock inventory system, there is no inheritance hierarchy for entities and all of the connect pipelines treat them as read-only entities. If you want to support updating stock information through the inventory system, you must extend the system with your own pipelines and service provider methods.

The pipelines of the inventory service layer can be divided into four categories:

  • Runtime Integration:

    • commerce.inventory.getStockInformation

    • commerce.inventory.getPreOrderableInformation

    • commerce.inventory.getBackOrderableInformation

    • commerce.inventory.getStockLocations

    • commerce.inventory.getProductStockLocations

  • Search Integration:

    • commerce.inventory.stockStatusForIndexing

  • Event Raising:

    • commerce.inventory.visitedProductStockStatus

    • commerce.inventory.productsAreBackInStock

    • commerce.carts.addCartLines

  • Products Back In Stock Engagement Plan:

    • commerce.inventory.visitorSignUpForStockNotification

    • commerce.inventory.removeVisitorFromStockNotification

    • commerce.inventory.getBackInStockInformation

Of these pipelines, only the following require integration with the ECS:

  • commerce.inventory.getStockInformation

  • commerce.inventory.stockStatusForIndexing

  • commerce.inventory.getPreOrderableInformation

  • commerce.inventory.getBackOrderableInformation

  • commerce.inventory.getBackInStockInformation

  • commerce.inventory.getStockLocations

  • commerce.inventory.getProductStockLocations

Extending the other pipelines is optional.

StockStatus and StockDetailsLevel Entities

The StockStatus and StockDetailsLevel entities are slightly different from traditional entities, in that they are intended to represent enumeration values. StockStatus represents a standard enumeration, and StockDetailsLevel represents a flags enumeration.

If either of these entities need to be extended for an ECS, the extended entities must also expose constants/read-only properties that represent the possible values for the entity. For example, if extending StockStatus to contain a new Downloadable value, then the extended EcsStockStatus entity should expose a staticreadonly field that represents the Downloadable value (that is, public static StockStatus Downloadable = new EcsStockStatus(5, “Downloadable);)

The InventoryProductBuilder

The InventoryProductBuilder class is a helper class used in the inventory system to build InventoryProduct entities based on the current site context, compare InventoryProduct entities, and so on. If you extend the InventoryProduct entity, this class also needs to be extended. Configuration for the InventoryProductBuilder is located in configuration at sitecore/inventoryProductBuilder

The InventoryAutomaionProvider

The InventoryAutomationProvider class is a helper class used by the conditions and actions in the Products Back in Stock engagement automation plan to access automation state data as strongly-typed classes. Automation state data in the inventory system is stored as JSON serialized strings. The InventoryAutomationProvider class is responsible for serializing and deserializing information stored in the automation state data row.

Products Back in Stock Engagement Automation Plan

The plan is provided as a branch template and multiple instances can be created. Create one instance per shop.  You can customize the default plan with different or more states as is needed. Its purpose is to notify customers by email message when a product they are interested in is back in stock and available for order.

This automation plan maintains state data that is serialized in JSON format. The following values are used to track customer back-in-stock notification requests, all of which represent a list of StockNotificationRequest objects:

  • commerce.productNotifications

    Contains the list of valid notification requests that the customer is interested in.

  • commerce.expiredNotifications

    Contains the list of notification requests that have expired.

  • commerce.backInStockProducts

    Contains the list of products that are back in stock.

To support this automation plan, two new conditions and two actions have been created.

  • Action: Remove Expired Back In Stock Notifications

    This action updates the automation plan state data, and removes the back-in-stock notification requests that are past their interest date. The default interest date is 180 days after the day the customer requested to be notified when a product is back in stock.

  • Action: Send Back In Stock Notification Email

    This action sends an email message to the customers when a product they are interested is back in stock. Customize this action for each shop to contain the correct email address and email body branding.

  • Condition: Are Products Back In Stock Condition

    This condition checks if any products that customers are interested in are back in stock. If at least one product is back in stock, this condition will evaluate as true.

  • Condition: Has List Of Visitor Notifications Expired Condition

    This condition checks if the customer still has any valid back-in-stock’ notification requests. If at least one back-in-stock notification request exists that has not expired, this condition will evaluate to false.

All of these conditions and actions rely on the InventoryAutomationProvider class to access automation state data and perform notification comparisons. So, customizing the conditions and actions directly is not necessary. Instead, you can update the InventoryAutomationProvider class to extend any functionality needed in this automation plan.

Extend the InventoryProduct entity

The InventoryProduct entity is used to uniquely identify a product/stock information in the external commerce system (ECS). If the default InventoryProduct entity is not sufficient to identify stock information, you must extend this entity, as well as a few provider classes in the inventory system.

To extend the InventoryProduct entity:

  1. Create an EcsInventoryProduct class that derives from InventoryProduct entity that contains the information required to identify stock information in your ECS.

  2. Create an EcsCommerceContext class that derives from the CommerceContextBase class that exposes properties that represent the additional information required to identify stock information in your ECS. It will be the responsibility of the client site / application to set these properties based on client state.

  3. Create an EcsInventoryProductBuilder class that derives from the InventoryProductBuilder, and override all methods of the base class to properly handle your EcsInventoryProduct. In particular, you must use the new EcsCommerceContext inside CreateInventoryProduct() to populate the additional properties of your EcsInventoryProduct. For example:

    var ecsProductInfo = ((EcsCommerceContext)this.CommerceContext).EcsProductInfo;
  4. Create an EcsInventoryAutomationProvider class that derives from InventoryAutomationProvider, and override the GetProductNotifications, GetExpiredNotifications, and GetProductsBackInStock methods. These methods must return an EcsInventoryProduct for the StockNotificationRequest.Product property. Automation state data in the inventory system is stored as JSON serialized strings, so this will usually require some custom deserialization code.

  5. Register your EcsInventoryProduct entity at sitecore/commerce.Entities/InventoryProduct.

  6. Register your EcsCommmerceContext at sitecore/commerceContext.

  7. Register your EcsInventoryProductBuilder at sitecore/inventoryProductBuilder.

  8. Register your EcsInventoryAutomationProvider at sitecore/inventoryAutomationProvider.