Calculation Framework
The idea of calculation framework
starts off with understanding of two main concepts: Calusage and Calmethod.
CALUSAGE_ID
|
DESCRIPTION
|
-1
|
Discount
|
-2
|
Shipping
|
-3
|
Sales Tax
|
-4
|
Shipping Tax
|
-5
|
Coupon
|
-6
|
Surcharge
|
-7
|
Shipping Adjustment
|
-8
|
Installment Adjustment
|
List
of Task
|
Application
|
Initialization
|
Combination
|
Qualification
|
Calculation
|
Summation
|
Finalization
|
General flow of calculation methods
The general flow of
calculation methods, when they are used as part of the order process, is as
follows:
1. InitializeCalculationUsage
2. ApplyCalculationUsage calls:
a. CalculationCodeCombine calls:
i. CalculationCodeQualify
b. CalculationCodeCalculate calls:
i. CalculationRuleCombine calls:
i. CalculationRuleQualify
ii. CalculationRuleCalculate calls:
i. CalculationScaleLookup
ii. CalculationRange
c. CalculationCodeApply
3. SummarizeCalculationUsage
4. FinalizeCalculationUsage
Code snippet from com.ibm.commerce.order.calculation.ApplyCalculationUsageCmdImpl :
public void performExecute()throws ECException
{
String strMethod = "performExecute";
ECTrace.entry(68L, super.getClass().getName(), "performExecute");
Group[] groups = callCodeCombine(this.iItems);
if (groups != null)
{
for (int i = 0; i < groups.length; ++i)
{
Group group = groups[i];
if (!(group.isCalculated()))
callCodeCalculate(group);
if (!(group.isEmpty()))
{
updateAppliedItems(group);
callCodeApply(group);
}
}
}
ECTrace.exit(68L, super.getClass().getName(), "performExecute");
}
callCodeCombine
methods invoke the com.ibm.commerce.order.calculation.CalculationCodeCombineCmd
which internally checks for Calculation code qualify:
items = (isRestricted(abCode))
? callCodeQualify(abCode, items) : items;
How calculation usages work
WebSphere Commerce performs all calculations for one
calculation usage at a time.
The order of calculation usages is stored in the SEQUENCE column of the
STENCALUSG database table. The entries in this table are initially populated
with information from the language-independent bootstrap file: wcs.bootstrap.xml.
Calculation usages as
defined in wcs.bootstrap.xml, are processed in the following order by
default:
1. Coupon
2. Discount
3. Shipping
4. Sales tax
5. Shipping tax
6. Surcharge
7. Shipping adjustment
Calculation usages are
invoked by the OrderPrepare command. This command creates a list of OrderItems
for which monetary amounts will be calculated. The applicable calculation
usages for the store or store group to which the order belongs are processed
according to the sequence that you define for them in the STENCALUSG database
table.
The OrderPrepare command
processes the calculation usages according to the following sequence:
1.
All calculation usages
are initialized using the InitializeCalculationUsage calculation methods
referenced in the CALMETHOD_ID_INI column of the STENCALUSG database table.
2.
All calculation usages
are applied using the ApplyCalculationUsage calculation methods referenced in
the CALMETHOD_ID_APP column of the STENCALUSG database table.
3.
All calculation usages
are summarized using the SummarizeCalculationUsage calculation methods
referenced in the CALMETHOD_ID_SUM column of the STENCALUSG database table.
4.
After the OrderPrepare
controller command completes, the OrderProcess controller command is called.
The OrderProcess controller command finalizes all calculation usages by calling
the FinalizeCalculationUsage calculation methods referenced in the
CALMETHOD_ID_FIN column of the STENCALUSG database table entry for each
calculation usage.
The CALMETHOD_ID_XXX will refer to the Task
(Command) in the CALMETHOD table which will be used to perform the necessary
logic processing. Refer the attached snapshot of a database extract for a
particular CALUSAGE(this extract is a sub-set of all CALMETHODS listing
only the calculation methods for Discount calculation [CALUSAGE_ID = -1]) from
the CALMETHOD table showing the various commands representing each of the
tasks.
How calculation usages are applied
When a calculation usage
is applied, the following steps occur:
1.
The ApplyCalculationUsage calculation method calls a
CalculationCodeCombine calculation method. The CalculationCodeCombine
calculation method returns a list. Each item in the list consists of a
calculation code and the OrderItems in the order to which the calculation code
applies.
2.
The ApplyCalculationUsage calculation method calls a
CalculationCodeCalculate calculation method for each item in the list that is
returned by CalculationCodeCombine. CalculationCodeCalculate returns a list.
Each item in the list consists of each OrderItem and the monetary amount
associated with the OrderItem for the calculation usage. For tax calculation
methods, there might be multiple monetary amounts for different taxes that
apply to the OrderItem. In this case, the tax categories are returned as part
of the list as well.
3.
The ApplyCalculationUsage calculation method calls a CalculationCodeApply
calculation method for each group of OrderItems
Calculation codes indicate the calculations that must be performed
Items for sale in a retail store often have attached price tags
indicating information other than the price of the item. For example, if the
item is on sale, the price tag indicates the percentage discount to apply to
the price. Similarly, WebSphere Commerce attaches calculation codes to order
items to indicate the calculations to be performed.
In the same way price tags are attached to the items for sale in a
retail store, calculation codes are considered to be attached to order items.
If the calculation code is directly attached to the
order/orderitem the attachment is said to be a direct one. Example: when we set
up an order level it creates an entry in the CALCODE table. This can be a
direct attachment and if found qualified by CalculationCodeQualify on attaching
with an order will make a corresponding entry in the ORDCALCD and ORDICALCD
tables.
[use the following sql to check:
select * from clcdpromo where px_promotion_id in
(select px_promotion_id
from px_promotion where px_group_id in
(select px_group_id
from px_group where grpname='OrderLevelPromotion'));
]
If the calculation code gets attached to an orderitem on being
virtue of its attachment to the corresponding catalog entry or catalog group,
it will be considered as an indirect attachment. Example: ProductLevelPromotion
and CategoryLevelPromotion will make corresponding entries in the CATENCALCD
and CATGPCALCD tables respectively and will get attached to the orderitem at
the time of purchase. This is an indirect calcode-orderitem attachment.
[use the following sql to check:
select * from clcdpromo where px_promotion_id in
(select px_promotion_id
from px_promotion where px_group_id in
(select px_group_id
from px_group where grpname in
(‘ProductLevelPromotion’,'CategoryLevelPromotion')));
]
Same logic applies when we configure Sales Tax/ Shipping charge.
The store can have a default Calculation Code at the store level. This will be
captured in the STENCALUSGE table and will be applied automatically for all
qualifying purchases in the store.
Tables related to Calculation Code:
· CALCODE
· ORDCALCD
Calculation rules
Separating the calculation rule from the calculation code offers
more flexibility and easier customization than having the calculation code
perform calculations directly. By separating calculation rules from calculation
codes, you can have many calculation rules for one calculation code.
For example, if you have
a store that ships products to a number of jurisdictions in which you must
collect sales tax and there are various sales taxes in each jurisdiction, you
would complete the following steps:
1. Create a sales tax calculation code and associate it with the
catalog entries for products that must be taxed.
2. For each jurisdiction in which you must collect sales taxes,
create one calculation rule to calculate each sales tax for the jurisdiction.
Each calculation rule must be associated with the following attributes:
o A tax category
o A tax jurisdiction.
o The sales tax calculation code
The sales tax
calculation code calculates amounts for all tax categories, by having several calculation rules, one for each
category. A calculation rule calculates an amount for a particular tax
category.
If you want your store
to ship products into a new jurisdiction in which you must collect sales taxes,
you do not have to create a new calculation code and attach it to the order
item. You can create new calculation rules and associate them with the
appropriate tax categories, the new tax jurisdiction, and the existing
calculation code
There are 3 Calculation methods that
can work on the Calculation Rules:
· CalculationRuleQualify
· CalculationRuleCalculate
· CalculationRuleCombine
The following commands implement the
CalculationRuleQualifyCmd interface and are provided with WebSphere Commerce:
· DiscountCalculationRuleQualifyCmdImpl
· ShippingCalculationRuleQualifyCmdImpl
· TaxCalculationRuleQualifyCmdImpl
The
CalculationRuleCombine calculation method calls the CalculationRuleCalculate
method to calculate the result of a particular calculation rule. For a
calculation rule and a list of order items, this command returns a monetary
amount for each item. The currency of the calculated monetary amount is the
order currency.
The
CalculationRuleCalculateCmdImpl command, which is provided with WebSphere
Commerce, implements the CalculationRuleCalculateCmd interface.
The CalculationRuleCombine method returns a list
that includes the following items:
· A calculation rule
· A list of OrderItems to which the calculation
rule applies
· A list of monetary amounts corresponding to each
item
The
CalculationRuleCombineCmdImpl command, provided with WebSphere Commerce,
implements the CalculationRuleCombineCmd interface.
The
CalculationRuleQualify calculation method checks if a calculation rule applies
to list of order items and returns a list of elements. Each element is a group
of order items that should be processed together by the calculation rule.
CalculationRuleQualify calculation methods are only called if the qualification
flag attribute of the calculation rule is set to 1.
How calculation rules are used
The default
CalculationCodeCalculate calculation method implementation uses calculation
rules to calculate monetary amounts for each item to which it applies. The
default CalculationCodeCalculate implementation calls the
CalculationRuleCombine calculation method and passes it the list of applicable
OrderItems. The default implementation of CalculationRuleCombine performs the
following steps:
1. Determines the list of calculation rules that are effective for
the calculation code by checking the CALRULE.FLAGS attribute and calling a
CalculationRuleQualify calculation method if the flag is set.
2. For each effective calculation rule, performs the calculation that
is defined by the rule for each order item to which the rule applies. If the
calculation to be performed is based on finding a value in a scale, calculation
scales are used to obtain the monetary amount.
3. When all rules have been calculated for all items, combines the
results of the calculation for each item. The combination attribute of the
calculation rule controls how the results are combined.
4. The CalculationRuleCombine calculation method returns a list of
calculation rules that were applied, the order items to which they were
applied, and the resulting monetary amount for each order item. This list is
returned to the calling CalculationCodeCalculate calculation method.
Tables related to Calculation Rule:
· CALRULE
· CALRULEMGP
· SHPJCRULE
· TAXJCRULE
· STENCALUSG
Calculation scales and
calculation ranges
Many calculations in
WebSphere Commerce involve looking up a value from a table. For example, a
store has shipping charges based on the number of items shipped in an order.
The table of shipping
charges looks like this:
Number of items in
order
|
Shipping charge
(local currency)
|
< 5
|
3.00
|
5 - 10
|
10.00
|
11 - 15
|
22.00
|
> 15
|
50.00
|
To calculate the
shipping charge, a clerk counts the number of items in the order and uses the
total number of items to find the shipping charge in the table.
WebSphere Commerce
provides a similar function as part of the calculation framework, in the form
of calculation scales. Think of calculation scales as two-column tables, where the
values in the first column are compared with a known value to find a row in the
table. The value in the second column is then applied to a calculation
associated with the original known value.
The process of finding
the value from the table is called a scale look-up. The calculation scale consists of a list of calculation ranges and associated look-up results. The known value that is compared to the
calculation ranges is called a look-up number. For example, when calculating shipping charges for an order that
contains eight items, the look-up number is 8, the calculation range that the look-up number matches is 5 - 10, and the look-up result is 10.00.
A calculation scale can
be used to calculate monetary amounts, one for each order item in a list. The
default implementation of the CalculationRuleCalculate calculation method uses
calculation scales. The amounts that are calculated are determined by the
calculation ranges and range values of the calculation scale, and by the
calculation methods they use. Calculation scales are associated with either a
MonetaryCalculationScaleLookup or a QuantityCalculationScaleLookup calculation
method. Calculation ranges are associated with a CalculationRange calculation
method.
Three subclasses of calculation methods are
associated with calculation scales:
· MonetaryCalculationScaleLookup
· QuantityCalculationScaleLookup
· CalculationRange
A
QuantityCalculationScaleLookup applies to quantity calculation scales, while a
MonetaryCalculationScaleLookup applies to monetary calculation scales.
Tables related to
Calculation Rule:
·
CALSCALE
– This table has the defined calculation scales
·
CALSCALEDS
–This table has the description for the calculation scale.
·
CRULESCALE
– This table has the mapping between a CALRULE and CALSCALE.
·
CALRANGE
– This table has the defined calculation ranges.
·
CALRLOOKUP-
This table will have the look-up value corresponding to the range.
Relate with the
following examples :
