Introduction

All calculation tasks required upon calculating baskets or orders will be done by this framework. Generally, the calculation is triggered during the checkout process as well as when adding or removing items from or to the basket. The present concept is addressed to developers who want to become familiar with the basic structure of this framework.

What Is the Idea?

The idea behind this framework is the spreadsheet functionality. The values are stored in cells, and you can define rules that will be executed when the cells are calculated.
Simple example:

In this example, the cell B will be calculated with the rule X. Once the values for cell B are available, the cell C can be calculated through rule Y. So the whole calculation can be defined only with the cells and the rules. All rules and cells will be defined in a rule set.
One goal of this framework is to handle the complexity of very extensive basket calculations. In the past, there was a large pipeline, which was difficult to handle and extend. To overcome these problems, the basket calculation framework has been introduced.

Glossary

Putting All Together

The Result Set defines all Rules and Cell Selectors. The Rules themselves use the Cell Selectors to create the Computed Items. The Cell Selectors are used to get the Computed Items in the calculation. The Result View defines methods to get the results. All BO classes (e.g,, the OrderBO) use the Result View to retrieve the calculated values.

Detailed Discussion

SubGroup in Detail

The cell and the group as selector are easy to understand, but the SubGroup is a little more sophisticated.
Consider the following scenario:

Assume, there is a basket with four line items. Each line item represents a cell in a group called RootLineItem. The ID of the cell in this group is, for instance, also the UUID of the line item object. Now you can easily select the computed items (created during the calculation).
Now we want to calculate two or more taxes for each line item. At the creation time we do not know how many taxes will be there, so a group would not help here. Each tax needs a unique ID, but the ID is not unique here, except we specifically create the ID, which requires a difficult algorithm to resolve the correct taxes of the line item.
For that case, we can create a sub group of a given computed item. The SubGroup helps to create and to select child items that belong to one parent. In our case, we can create many taxes for one line item.

It is also possible to create a sub group in a sub group and so on. This way, you can map even complex scenarios.

"Rules" for the Rule Set

Every rule set must match the following criteria:

• The cell selectors must be disjoint to each other.
  This means that no computed item can be created that is part of two different cell selectors.
• Computed items are immutable.
  That also means that only one rule can create this item. In addition, you should not change it afterwards.
• The rules as edges with its cells as nodes should always be one graph without circles and all connected. The framework will automatically test this. The reason is that a cell must be calculated exactly once.

Computed Items Types

The computed items will be used to store the results of the rule execution.

com.intershop.component.foundation.capi.spreadsheet.ComputedItem

The interface ComputedItem is the base interface for all computed items.

com.intershop.component.foundation.capi.spreadsheet.ComputedMoneyItem

The interface ComputedMoneyItem passes on the amount of money.

com.intershop.component.shipping.capi.shippingchargecalculator.ComputedShippingBucketItem

com.intershop.component.shipping.capi.shippingchargecalculator.ComputedShippingExtraChargeItem

com.intershop.beehive.bts.capi.orderprocess.calculation.ComputedProductLineItem

The interface ComputedProductLineItem encapsulates a ProductLineItem.

com.intershop.beehive.bts.capi.orderprocess.calculation.ComputedQuantityItem

com.intershop.component.marketing.capi.promotion.calculation.rule.ComputedDiscountItem

The interface ComputedDiscountItem stores the discounts.

com.intershop.beehive.bts.capi.payment.calculation.ComputedPaymentInstrumentItem

The interface ComputedPaymentInstrumentItem stores the payment instrument item.

com.intershop.component.foundation.capi.spreadsheet.ComputedPercentageItem

The interface ComputedPercentageItem stores the percentage item.

com.intershop.beehive.bts.capi.orderprocess.calculation.ComputedServiceLineItem

The interface ComputedServiceLineItem stores the service line item.

Calculation Rule

The calculation rules are doing the real calculation. They use the input, transform it, and finally write the outcome into the target cells. Besides the input and target cells, the rule considers the current com.intershop.component.spreadsheet.capi.CalculationContext. This can contain important attributes which influences the way a rule processes the data. The context is built each time a re-calculation of the basket is required. To hook into this preparation step, ICM has the pipeline extension point ProcessBasketCalculation-PrepareCalculationContextData.

Each rule has to implement the base class com.intershop.component.spreadsheet.capi.CalculationRule.

Existing Rules

Intershop recommends to use the existing rules whenever possible.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.CreateInitialProductItemsRule

The class CreateInitialProductItemsRule initially creates product line items from the line item container.

com.intershop.component.foundation.capi.spreadsheet.rules.AddMoneyRule

The class AddMoneyRule adds the values of a certain input structure and outputs the result in a new target structure, e. g.,:

• sub sub groups in sub groups
• sub groups in groups
• sub groups in cell
• groups in cell
• group sets in groups
• group sets in cell

Depending on the target structure, the values will be added differently. If you, for instance, pass in a group set and want to specify a group as return value, all sets of each group will be added together (so that you get a sum for each group set). If you specify a cell as return value, all values of all group sets will be added to a single sum.

com.intershop.component.foundation.capi.spreadsheet.rules.AddQuantitiesRule

The class AddQuantitiesRule adds the quantities.

com.intershop.beehive.bts.capi.payment.calculation.CalculatePaymentCostsRule

The class CalculatePaymentCostsRule calculates the payment costs of the given order amount.

com.intershop.component.foundation.capi.spreadsheet.rules.ComputeQuantityRule

Computes the quantities of all child items in relation to their root items.
If the root item has the quantity of a and the child item the quantity of b, the resulting quantity is a*b.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.CopyMoneyValueIntoNativeAttributeRule

The class CopyMoneyValueIntoNativeAttributeRule copies the attributes to the given native targets.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.CreateInitialServiceItemsRule

The class CreateInitialServiceItemsRule creates the initial service items from the given line item container.

com.intershop.component.warranty.capi.orderprocess.calculation.rules.CreateWarrantyPricesRuleNet / Gross

The rules CreateWarrantyPricesRuleNet and CreateWarrantyPricesRuleGross create the single prices for each warranty. The classes are specific for the price types Net and Gross.

com.intershop.component.shipping.capi.shippingchargecalculator.rule.FilterShippingCalculationProductItemsRule

Filters the product line items with the service type flag ExcludeFromShipping from the computed product line items and returns the new group.

com.intershop.component.marketing.internal.promotion.basketcalculation.PromotionBasketCalculationRule

The class PromotionBasketCalculationRule calculates all discounts and promotions configured in the channel.

com.intershop.component.marketing.capi.promotion.calculation.rule.PromotionCalculationRule

The class PromotionCalculationRule calculates all discounts and promotions configured in the channel. The rule uses the variables

• AppID
• UserGroups
• UserGroupsByType
• CurrencyCode
• CustomPromotionParameters
• ProductRepositoryDomain
• CurrentDate
• PromotionUserGroups
• DisableMessages
• PromotionCodeMapping

from the calculation context.

com.intershop.component.shipping.capi.shippingchargecalculator.rule.ShippingBucketCreationRule

This rule is a calculation step within the basket calculation.
It determines the shipping buckets for further shipping cost calculation.

com.intershop.component.shipping.capi.shippingchargecalculator.rule.ShippingExtraChargeCalculatorRule

This rule is a calculation step within the basket calculation.
It determines the extra cost applied on each product line item due to surcharges defined with the product or shipping rule.

com.intershop.component.shipping.capi.shippingchargecalculator.rule.ShippingPLIChargeCalculatorRule

This rule is a calculation step within the basket calculation.
It determines the bucket cost and shipping PLI cost for each product line item within each shipping bucket.

com.intershop.component.foundation.capi.spreadsheet.rules.CalculateMoneyRateRule

The class CalculateMoneyRateRule calculates the percentage values of the given two money items.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.DetermineProductItemsWithPriceRule

This rule is a calculation step within the basket calculation.
It determines the product line items with a price (filters them).

com.intershop.component.foundation.capi.spreadsheet.rules.MultiplyMoneyWithPercentageRule

The class MultiplyMoneyWithPercentageRule multiplies prices with a percentage value.

com.intershop.component.foundation.capi.spreadsheet.rules.MultiplyMoneyWithQuantityRule

The class MultiplyMoneyWithQuantityRule multiplies single prices with given quantities.

com.intershop.component.foundation.capi.spreadsheet.rules.SubtractMoneyRule

The class SubtractMoneyRule subtracts the given two money items.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.CalculateSingleProductBasePricesRule

This rule determines the product single base price for one or more product line items.
For the (scaled) price lookup, the quantities are accumulated for all line items referring to the same product.
The old net price flag at prices is not taken into account by this rule.
The rule can be configured to perform a lookup for a given currency (that might be different to the purchase currency of the LineItemCtnr).
The actual price lookup is performed via the ProductPriceMgr. If the flag BasePriceFixed is set for the product line item, the single base price is directly taken from the ProductLineItemPO.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.DetermineIncludedTaxRatesRule

Determines the percentage amount of included taxes for the given gross price and the according tax rate.
Mathematically this means r = (1-(1(1+p))). This expression is calculated via the data type Double. With this the maximum precision is also bound to the Double data type.

com.intershop.beehive.bts.capi.payment.calculation.DeterminePaymentItemTaxRatesRule

The class DeterminePaymentItemTaxRatesRule determines the tax rate for the given payment elements.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.DetermineProductItemTaxRatesRule

The class DetermineProductItemTaxRatesRule determines the tax rates of the given PLIs.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.CalculateTaxSumsPerRateRule

The class CalculateTaxSumsPerRateRule calculates all taxes by its tax rates.

com.intershop.component.foundation.capi.spreadsheet.rules.RoundMoneyRule

The class RoundMoneyRule rounds the given money items.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.CreateChildProductItemsRule

The class CreateChildProductItemsRule creates a sub group of product line items.
Child products are sorted by the product UUID.

com.intershop.component.foundation.capi.spreadsheet.rules.SelectMoneyRule 

The class SelectMoneyRule selects one of two money inputs as output, depending on which one is available. If both are available, the first input will be returned.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.CollectPromotionDiscountValuesRule 

The class CollectPromotionDiscountValuesRule collects promotion discounts with the same line item ID and adds them up. This is necessary because promotion discounts may be split up on individual items. For example, a line item with a quantity of three may include two items with a discount value of $1.00 and one item with a discount value of $1.02. Because values like taxes are calculated on a per-item basis (in the V3 rule sets), they need to be added up at the end to determine the gross value of the line item.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.DetermineTaxRatesForPromotionDiscountsRule 

The class DetermineTaxRatesForPromotionDiscountsRule maps a set of given tax rates to associated promotion discounts. This is necessary because promotion discounts may be split up on individual items. For example, a line item with a quantity of three may include two items with a discount value of $1.00 and one item with a discount value of $1.02. In this scenario the first "sub item" in the calculation may have an ID of "0-0" and the second one "0-2" (where the first number is always the associated line item). Tax rates, on the other hand, are always associated with line items, and because they use different IDs (in this scenario it would simply be "0"), a mapping is needed, which is what this rule does.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.CalculateAverageTaxRateRule 

The class CalculateAverageTaxRateRule calculates the average tax rate from all line items and the individual tax rates. The tax rate is calculated based on the base price distribution of the line items, i.e., items with a higher price have a higher weight when calculating the average tax rate.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.ChangeMoneySignRule 

The class ChangeMoneySignRule changes the sign of a money item, i.e., multiplies it with -1. This is used to compare certain calculation values with discounts (as discounts are always negative).

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.DetermineMaximumMoneyItemRule 

The class DetermineMaximumMoneyItemRule determines the maximum from a given set of money items.

com.intershop.component.marketing.capi.promotion.calculation.rule.CashbackCalculationRule

The CashbackCalculationRule calculates the (optional) cashback earning promotion dependent on the current basket, which is represented by the passed computed items.

com.intershop.component.shipping.capi.shippingchargecalculator.rule.BucketCostDistributionRule

The BucketCostDistributionRule distributes costs from surcharges over the given items.

com.intershop.component.shipping.capi.shippingchargecalculator.rule.CalculateBucketTaxes

The class CalculateBucketTaxes calculates the taxes for the given buckets.

com.intershop.component.shipping.capi.shippingchargecalculator.rule.CalculateSumPerBucketCostRule

This rule sums up all values while considering their relation to the buckets (and their surcharges).

com.intershop.component.shipping.capi.shippingchargecalculator.rule.CalculateTotalShippingDiscountRule

The rule calculates the total shipping discount on bucket or line item container level.

com.intershop.component.shipping.capi.shippingchargecalculator.rule.ShippingGroupedChargeCalculatorRule

The rule ShippingGroupedChargeCalculatorRule groups money values by the rule ID of there related ComputedShippingExtraChargeItem.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.CopySingleBasePricesToPlis

The class copies the provided amounts to the field "SingleBasePricePC" of the ComputedProductLineItem list.

com.intershop.beehive.bts.capi.orderprocess.calculation.rules.DistributeMoneyValueRule

The calculation rule DistributeMoneyValueRule distributes the value of a given ComputedMoneyItem evenly onto other items.

com.intershop.beehive.bts.capi.payment.calculation.CalculateBaseAmountsRule

The class CalculateBaseAmounts calculates the base amounts for all payment instrument information (PIIs).

com.intershop.beehive.bts.capi.payment.calculation.CalculatePaymentSurchargesRule

The calculation rule CalculatePaymentSurchargesRule determines payment surcharges (costs and taxes). It uses the context variable "PaymentConfigurations" to load the configuration of the payment cost handling.

com.intershop.beehive.bts.capi.payment.calculation.CalculatePIICostsRule

The CalculatePIICostsRule calculates the payment costs for all PaymentInstrumentInfo objects.

com.intershop.beehive.bts.capi.payment.calculation.CopyMoneyAmountToPII

This rule sets the amount for the payment attribute at the PaymentInstrumentInfo objects.

com.intershop.beehive.bts.capi.payment.calculation.DeleteObsoletePIIs

This rule deletes (removes) persistent payment instrument objects that are assigned to the basket but not needed anymore (e.g., free gifts not applied anymore).

com.intershop.beehive.bts.capi.payment.calculation.DistributeBasketTotalAmountRule

This rule distributes the basket total amount over the payment instruments. It also divides the payment instruments in two groups (open and limited tender).

com.intershop.beehive.bts.capi.payment.calculation.DistributePaymentCostsRule

The class DistributePaymentCostsRule determines payment surcharges (cost and taxes). It uses the context variable "PaymentConfigurations" to load the configuration of the payment cost handling.

com.intershop.component.shipping.capi.shippingchargecalculator.rule.CalculateTaxSumsPerRateAndBucketRule

The calculation rule CalculateTaxSumsPerRateAndBucketRule groups the shipping cost tax values by their tax rate. The sums are calculated for each bucket.

Existing Reference Calculation Rule Sets

Intershop provides the option to set up your own desired way of basket calculation via CalculationRulesets and also offers example calculation rule sets, which are used in the demo shop inTRONICS.
For details on how to create your own calculation rule sets, see Cookbook - Basket Calculation.

This section will give you an overview of the existing example calculation rule sets:

• NetBasedCalculation_V1

• GrossBasedCalculation_V1

• NetBasedCalculation_V2
• GrossBasedCalculation_V2
• NetBasedCalculation_V3
• GrossBasedCalculation_V3

The Net and Gross based V2 calculation rule sets are well known and available since IS 7.0. In IS 7.6 we introduced the Net and Gross based V3 calculation rule sets.

Usage in Demo Store

At the moment the calculation rule sets NetBasedCalculation_V3 and GrossBasedCalculation_V3 are used in the demo store as default but there is always the possibility to change the reference rule sets or to use your own. For registering a new rule set, please have a look at Cookbook - Basket Calculation | Recipe: Register the Rule Set.

Differences

NetBasedCalculation_V1,GrossBasedCalculation_V1

V1 was the very first rule set already used in previous Enfinity Shop software and had yet limited features. It was not able to use a mix of GROSS and NET values. If your prices in the database were gross, all displayed and calculated prices in your shop had to be gross as well. This V1 rule set is no longer used, but is preserved for downwards compatibility reasons to handle old orders that were once created with this rule set.

NetBasedCalculation_V2,GrossBasedCalculation_V2

V2 is the default calculation rule set for all Intershop 7.x versions starting with Intershop 7.0.0.0 and before Intershop 7.8.0.0  (with Intershop 7.8.0.0 and newer the default rule set was switched to V3).

Example: In a scenario with net prices in the database and gross prices displayed in the storefront (Net Based Taxation Service, Channel Preference Price Type = Net, Price Display = Gross), the V2 basket calculation works like this:

1. The single net price of one line item position is summed up.
2. From this sum the tax is calculated and finally rounded to 2 positions after decimal point for the exact gross price.

At  the same time, the single gross price of this line item has to be displayed in the storefront (rounded at 2 positions) as well as the total gross price of the number of this line item summed up ( rounded at 2 positions).

Example in numbers:

• We have a line item with net price = $10.10 and a tax rate at 19% and put it 6 times into the basket.
• In the storefront, we see for this line item: single gross price = $12.02 ($12.019 rounded per requirement) and a total gross price = $72.11 ($72.114 rounded per requirement)
• This line item is calculated as follows: $10.10 x 19% = $12.019. Then $12.019 x 6 = $72.114. This gets rounded to $72.11.
• Finally, we have an exactly calculated gross total = $72.11, but the displayed prices do not sum up logically: $12.02 x 6 <> $72,11.

Disadvantage: The prices displayed in the storefront may not sum up logically.

Advantage: The calculation totals are more precise due to less rounding in between.

NetBasedCalculation_V3,GrossBasedCalculation_V3

In Intershop 7.6, we introduced a new calculation value called 'single discounted base prices'. This is due to the fact that some e-commerce managers wanted to calculate the discount at the level of single products to ensure that the correct discount is provided, e.g., to a taxation service. Furthermore, we are using the 'single discounted base prices' for calculating the PLI net and gross prices by multiplying it with the PLI quantity. Especially in net/gross settings where you store net prices and display those as gross prices, that change prevents the calculation from rounding issues.

V3 is the default calculation rule set for all Intershop 7.8.x versions and newer, starting with Intershop 7.8.0.0.

Example: In a scenario with net prices in the database and gross prices displayed in the storefront (Net Based Taxation Service, Channel Preference Price Type = Net, Price Display = Gross), the V3 basket calculation works like this:

1. The tax is calculated for the single net price of one line item and rounded to 2 positions.
2. The rounded single tax values are summed up to get the total line item gross price.

At the same time, the single gross price of this line item has to be displayed in the storefront (rounded at 2 positions) as well as the total gross price of the number of this line item summed up (rounded at 2 positions).

Example in numbers:

• We have a line item with net price = $10.10 and a tax rate at 19% and put it 6 times into the basket.
• In the storefront, we see for this line item: single gross price = $12.02 ($12.019 rounded per requirement) and a total gross price = $72.12 ($12.02 x 6 = $72.12, no further rounding required).
• This line item is calculated as follows: $10.10 x 19% = $12.019. This gets rounded to $12.02. The rounded result multiplied with the actual number of this line item: $12.02 x 6 = $72.12.
• Finally, we have a calculated gross total = $72.12 based on rounded single tax values, and the displayed prices sum up logically: $12.02 x 6 = $72.12.

Disadvantage: The calculation totals are less precise due to cumulative rounding issues made for intermediate results.

Advantage: The prices displayed in the storefront sum up logically.

Next Steps

It may be beneficial to only have one rule set instead of two different ones for net and gross based calculations. The only difference between the two is the factor by which taxes are calculated and if they are added or subtracted from the "base" price.