Base Commerce Extension - Key concepts

The hybris documentation about this extension is so detailed, that it may take some hours to read it throughly. It wrote this summary for the Hybris eCommerce certification.

• Base Store which offers products from different catalogs (products and classification). It doesn't have a physical address. It may be linked to warehouses to keep track of “web” stock.
• Point of Service: It is a physical branch store with an address. It may be linked to warehouses to keep track of the “in store” stock.

They shouldn't be used in production without customization.

• An order can be canceled as long as it wasn't shipped.
• Digital products cannot be canceled
• A recalculation of the orders is done for partial cancellations

• The customer calls a customer representative who looks for the order, check the goods and ask for authorization to accept them. The goods are sent to the inventory.
• Creates, returns and process
  • ReturnRequets for an order
  • Return Merchandise Autorization (RMA)
  • Replacement Order with the RMA value
  • Refund based on order entries
• Checks if a product is returnable using a ReturnableCheckStrategy. The default implementation allows the return if the product wasn't returned yet.
• An implementation for ReturnEntryProcessor, ReplacementOrderProcessor and RefundOrderProcessor must be provided 

• The call center agent checks if the customer could receive a replacement or a refund for the returned goods.
• It works together with a returnRequest following this flow:
  • With OrderModel createRefundOrderPreview(OrderModel original) a clone of the original order is created. This allows the system to preview the refund
  • Create refundEntryModels with the quantity and the orderEntries to be refunded.
  • Use the method void apply(List<RefundEntryModel> refunds, OrderModel order) to subtract the refunded products from the preview order. The order is recalculated by this method.
  • If the customer accepts the refund, the method void apply(OrderModel previewOrder, ReturnRequestModel request) is called to modify the original order of the return request.

This functionality is privided by the OrderHistoryService. Here is a diagramm with the involved classes

• The OrderHistoryEntryModels are used to register the steps of the order. They are created using the model service and associated manually to the order. No new version of the order is created.
• When the order is modfied and a snapshot of the old states is required:
  • Call OrderModel createHistorySnapshot(OrderModel paramOrderModel) to create a clone of the current order. This clone would have a version number and will be associated to the current order through the field originalVersion.
  • Make changes to the original order. It doesn't have an version number and it represents the actual state of the order.
  • A OrderHistoryEntryModel with the cloned order as the previous order and the actual order as order may be created to document the changes.
  • Call void saveHistorySnapshot(OrderModel clonedOrder) to save the order created by createHistorySnapshot. Jalo attributes like the tax total values and the calculated flag are updated in this step.
  • Save the modified order and the order history entry using the model service. 
• When searching for orders, remember that the actual order doesn't have a version number. Orders with version numbers are snapshots.

• The OrderSplittingService defines the interface used by this service. It contains implementations of SplittingStrategy.
• The default strategies are SplitByAvailableCount, SplitByDeliveryMode, SplitByNamedDeliveryDate and SplitByWarehouse.
• WarehouseService: Contains utility methods for the splitByWarehouse strategy.
  • Because the strategy to select the warehouse for a product and warehouse only selects warehouses with the flag default turned on (class DefaultWarehouseSelectionStrategy), in a base shop assigned to many warehouses, all warehouses must be default.
• Consigment: Each group of order entries sent to a warehouse which make up a delilvery.
• ConsigmentService: Creates consigments and choose the warehouse for each one of them. The default implementation choose one randomly.
• There are also order entry groups which are not exactly the same as consigments:

.	Order Entry Groups	Consignments
Applies to	Cart and Order entries	Order entries
Grouping by	A charateristic like the delivery address or pickup location	By the delivery location
Further splitting?	No	Yes, a consignment can be splitted
Has it owns status?	No	Yes
Result of one order entry	Maximal one group	It may result in many consigments
Are applicable to every entry?	Yes, each entry must belong to a group	No, some entries may no have a consignment. In what situation could this happens?
Persistent?	No, it is a DataObject	Yes, it is Hybris Item Type

• Hybris may place orders on the warehouses (Process2WarehouseAdapter.prepareConsignment and shipConsignment methods)
• The warehouses may inform Hybris about updates (Warehouse2ProcessAdapter.receiveConsignmentStatus method)
• An implementation for these two interfaces must be developed.

• It is iimplemented in the basecommerce extension but it belongs to the order management for B2B
• The customer can create an order which will be place in the future.
  • The developer has to clone an existing cart or order
  • A better alternative is to use the ScheduleOrderService which creates CronjobModels. A trigger must be provided. The methods createOrderFromOrderTemplateCronJob and createOrderFromCartCronJob use an order or a cart to create a new order which is scheduled in the future. createScheduledOrderCronJob creates recurring orders. For this to work, the default implementation of OrderUtility must be extended and the method runOrder(OrderModel order) must be written. It may also make recurring orders based on a schedule. These orders are based on a previous order or basket.

• The geographical information is saved in a pointOfService.
• Any item to be searched must be associated to a pointOfService.
• Each point of service may have an OpeningSchedule with the opening times.
• A defaultLocation associates a pointOfSale with GPS coordinates.
• A locationDTOWrapper associates a POJO address with GPS coordinates.
• The interface GPS represents a geographical position
• LocationService: Finds the list of nearest pointOfServices (Locations) to a town, postal code or GPS coordinate. 
  • Getting locations from neighborhood
  • Getting locations near a temporary location, e.g. my current location.
  • CRUD operations on locations
• LocationMapService: It finds the same as LocationService but it returns a map.
• GeoWebServiceWrapper: This interface is used to integrate geocoding services.
• There is a default integration for GoogleMaps. It generates geographical information from addresses. It uses two methods:
  • Javascript for geocoding the address entered by the customer
  • HTTP Requets for geocoding points of services using the geocodingCronJob.
• Google don't allow to save the GPS information for more than 30 days and it must be used in a Google Map. To meet these legal requirements a mock implementation is shipped with the basecommerce extension
• MapService: Generates maps with the given points of service.
• RouteService
• Use Cases
  • Geocode the address of the customer
  • Get nearby points of services like branch offices
  • Use them to create a map
  • The customer choose a point
  • Return the route to that point.
• To use the extension the locations of the base store must be configured. The geocodingCronJob will then get the GPS coordinates.
• Steps to activate the buy and pick up functionality

• Translates a short URL into a long URL
• deepUrlModel: It is used for the short URL generation
• A DeeplinkUrlRule generates an URL from an Item.
• DeeplinkUrlService: Generates long and shorts URLs from an Item.
• GenericDeeplinkUrlServlet: Detects a short URL and redirects the request to a long URL.

Explanation of the data model

• FraudService: Generates a report for a customer, an order or a cart (any abstract order) using a given provider. It returns a non-persistent response.
• Symptoms are recognized and their points are sum up to calculate a score. This score doesn't trigger any decision.
• FraudReport: It persists the response from FraudService. It contains a list of FraudSymptomScoringModel. You would have to create a converter from the fraudServiceResponse to the FraudReport if you want to save it into the database.
• FraudServiceProvider: Interface for third party providers. It is used by the Fraud Service.
• OrderFraudSymptomDetection: Basic Implementation of symptoms provided by Hybris. It doesn't use any third party services.
  • BlackListSymptom, WhiteListSymptom, FirstTimeOrderSymptom, DifferentAddressesSymptom, OrderThresholdSymptom and OrderEntriesSymptom are the default symptoms.
  • There aren't any default symptoms related to the customer.
• The fraud detection could be done in an action in a workflow.

Most of the services described here were built before Hybris 5.3. On those days Hybris was marketed to be a e-commerce platform covering all steps of the selling, ordering and logistics process with a monolitic architecture. Because of this, Hybris developed its own data structures for features which big companies outsource or implement on their ERP system like order splitting in consigments and fraud detection.
As developers we have to understand how the ERP works, then analyse the requirements for our shop and then decide if it is worth using the Hybris data structures and services and keep our custom code compatible with the next versions. If the business decides on the contrary, they have to understand the future costs and limitations. As developers, we have to do the most to keep our code compatible with Hybris.

–Based on SAP Hybris 1905