Calculation rules

The WebSphere Commerce calculation framework separates the object that indicates the calculation to be performed for an order item (calculation code) from the object or objects responsible for doing the calculation, called a calculation rule.

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. These multiple calculation rules can be combined, given an order of precedence, and restricted to specific member groups. Calculation rules for shipping or tax calculations can also be restricted by jurisdictions.

For example, if you have a store that ships products to a number of jurisdictions in which 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 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:
    • A tax category
    • A tax jurisdiction.
    • 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 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.

The properties of calculation rules are defined in the CALRULE database table. The next section discusses this table and other database tables that affect the use of calculation rules.

Database tables for calculation rules

Information about calculation rules is provided in the following WebSphere Commerce database tables:

CALRULE

Defines calculation rules.

CALRULEMGP

Associates a calculation rule with a member group. The association of a member group with a calculation rule permits you to allow only certain member groups to use the calculation rule.

SHPJCRULE

Can be used by the ShippingCalculationRuleQualify calculation method to choose a calculation rule based on the shipping mode and fulfillment center when the shipping address matches one of the shipping jurisdictions in a particular shipping jurisdiction group.

STENCALUSG

Specifies the subclass of the CalculationRuleCombine calculation method that determines how to combine multiple calculation rules for an order item.

TAXJCRULE

Can be used by a TaxCalculationRuleQualify calculation method to choose a calculation rule when shipping from a fulfillment center to a shipping address that matches one of the tax jurisdictions in a particular tax jurisdiction group.

The following sections discuss key attributes of calculation rules that are stored in some of the database tables.

Calculation rule data model diagrams

The following data model diagrams illustrate the relationships between the database tables that are used to define generic calculation rules, discount calculation rules, shipping calculation rules, and tax calculation rules.

 

Calculation methods for calculation rules

Three subclasses of calculation methods are associated with calculation rules:

This section discusses these subclasses and the default implementations that WebSphere Commerce provides.

CalculationRuleCombine calculation method

CalculationRuleCombine determines which calculation rules are used to calculate monetary amounts for the list of order items that is passed to the CalculationRuleCombine calculation method by the CalculationCodeCalculate calculation method.

The CalculationRuleCombine method returns a list of items that consist of the following:

For tax calculations, the monetary amounts corresponding to each item can be separated into the amount for each applicable tax category.

Any commands used as CalculationRuleCombine calculation methods must implement the CalculationRuleCombineCmd interface.

The CalculationRuleCombineCmdImpl command, provided with WebSphere Commerce, implements the CalculationRuleCombineCmd interface.

CalculationRuleCombineCmdImpl

This is the default implementation of the CalculationRuleCombine command.

This command is called by the CalculationCodeCalculate calculation method to identify the calculation rules associated with the order items. Given a list of order items, a calculation code, and an optional list of tax categories, this command performs the following tasks:

  1. Using the calculation usage being processed, the calculation code, and the optional tax categories, the CalculationRuleCombineCmdImpl command creates a list of calculation rules that can be applied to the order items. The selection of the calculation rules is based on the calculation code and the optional tax categories.
  2. The command then sorts the calculation rules in ascending order by the calculation sequence attributes of their tax categories (TAXCGRY.CALCULATIONSEQ). Calculation rules with the same tax category are sorted in ascending order by their sequence attribute. Calculation rules without tax categories are sorted in ascending order by their sequence attribute.
  3. If the qualification flag attribute of the calculation rule is set to 1, the CalculationRuleQualify calculation method for each calculation rule is called to determine to which order items each calculation rule applies. The CalculationRuleQualify calculation method returns a list of OrderItems to which the calculation rule applies.
  4. For each calculation rule and each list of order items that is returned by the CalculationRuleQualify calculation method (or all the items if that method was not called), the command calls the CalculationRuleCalculate calculation method. CalculationRuleCalculate returns a monetary amount for each item.
  5. When all calculation rules have been processed, the monetary amounts from different calculation rules for each order item are combined as follows:
    1. The monetary amounts for calculation rules with an inAdditionTo combination attribute are added.
    2. For each calculation rule that has an inCombinationWith combination attribute, the sum of the calculated monetary amounts for the calculation rule and the total from step 5a. are added.
    3. All monetary amounts for calculation rules with an inCombinationWith combination attribute are added to the total from step 5a.
    4. All of the results obtained in step 5b (there is one result for each notInCombinationWith rule) and the result obtained in step 5c are compared. The lowest of these results is considered the valid monetary amount.
  6. The calculation rules that are used to calculate the valid monetary amount, the monetary amounts produced by each of these calculation rules, and their associated OrderItems are returned to the calling method.

CalculationRuleQualify calculation method

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.

Any commands that are used as a CalculationRuleQualify method must implement the CalculationRuleQualifyCmd interface.

The following commands implement the CalculationRuleQualifyCmd interface and are provided with WebSphere Commerce:

DiscountCalculationRuleQualifyCmdImpl

This is the version of the CalculationRuleQualify command for discounts. It implements the DiscountCalculationRuleQualifyCmd interface that extends the CalculationRuleQualifyCmd interface.

This command returns order items with a customer in one of the member groups that are associated with the calculation rule and recognized by the store. If the customer is not in any of these member groups, this command returns null.

Calculation rules are associated with member groups in the CALRULEMGP database table and member groups are recognized by stores in the STOREMBRGP database table.

ShippingCalculationRuleQualifyCmdImpl

This is the version of the CalculationRuleQualify command for shipping. It implements the ShippingCalculationRuleQualifyCmd interface that extends the CalculationRuleQualifyCmd interface.

This command compares the shipping jurisdictions, shipping modes, and fulfillment centers of the order items with those associated with a calculation rule. The ShippingCalculationRuleQualifyCmdImpl command returns only order items that share shipping jurisdictions, shipping modes, and fulfillment centers with the calculation rule.

When the shipping address of the OrderItem falls into more than one shipping jurisdiction group, for the same fulfillment center and shipping mode, the calculation rule with the highest precedence value defined in the SHPJCRULE database qualifies. If multiple calculation rules share the highest precedence value, then all calculation rules sharing the highest precedence values apply.

Calculation rules are associated with shipping jurisdictions, shipping modes, and fulfillment centers in the SHPJCRULE database table.

TaxCalculationRuleQualifyCmdImpl

This is the version of the CalculationRuleQualify command for taxes. It implements the TaxCalculationRuleQualifyCmd interface that extends the CalculationRuleQualifyCmd interface.

This command compares the tax jurisdictions and fulfillment centers of the order items with a calculation rule. The TaxCalculationRuleQualifyCmdImpl command returns only order items that share tax jurisdictions and fulfillment centers with a calculation rule.

When the shipping address of the OrderItem falls into more than one tax jurisdiction group for the same fulfillment center, the calculation rule with the highest precedence value defined in the TAXJCRULE database table applies. If multiple calculation rules share the highest precedence value, then all calculation rules sharing the highest precedence values apply.

Calculation rules are associated with tax jurisdictions and fulfillment centers in the TAXJCRULE database table.

CalculationRuleCalculate calculation method

This command is called by the CalculationRuleCombine calculation 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.

CalculationRuleCalculate calculation methods must implement the CalculationRuleCalculateCmd interface.

The CalculationRuleCalculateCmdImpl command, which is provided with WebSphere Commerce, implements the CalculationRuleCalculateCmd interface.

CalculationRuleCalculateCmdImpl

This is the default implementation of the CalculationRuleCalculate command.

Using a calculation rule and list of OrderItems, this command performs the following tasks:

  1. Clears the monetary amount associated with the order items being processed with the calculation rule.
  2. Determines the list of calculation scales associated with the calculation rule using the CRULESCALE database table.
  3. Processes calculation scales that are not associated with any currency by doing the following:
    1. Obtains a monetary result in the Order currency, for each order item, using the calculation scale. For more details on this step, see How calculation scales and calculation ranges are used.
    2. Adds the monetary amount result to the total result, for each item.
  4. Assembles a list of the currencies with which the remaining calculation scales are associated.
  5. Does one of the following steps:
    • If the list of calculation scale currencies contains the order currency:
      1. Starts with a candidate result of zero for each order item.
      2. For each calculation scale with the same currency as the order, does the following steps:
        1. Obtains a monetary amount for each order item. For more details on this step, see How calculation scales and calculation ranges are used.
        2. Adds each item's monetary amount to each item's candidate result.
      Calculation scales associated with currencies other than the order currency are ignored.
    • If the list of calculation scale currencies does not contain the order currency:
      1. For each currency in list:
        1. Starts with a candidate result of zero for each order item.
        2. For each calculation scale with the currency being processed, does the following:
          1. Obtains a monetary amount for each item. For more details on this step, see How calculation scales and calculation ranges are used.
          2. Adds each item's monetary amount to its candidate result.
        If the conversion from a currency in the list of calculation scale currencies to the order currency is not defined in WebSphere Commerce, then the calculation scales associated with that currency are ignored.
      2. Compares the sum of candidate results for each currency. The candidate results for the currency producing the lowest sum are considered valid. Candidate results from the other currencies are discarded.
  6. For each order item, adds the amount calculated in step 3 and the candidate result from step 5.
  7. Returns the results to the calling method.

Information about how to obtain monetary amounts from calculation scales and the calculation methods that apply to calculation scales is provided in How calculation scales and calculation ranges are used.

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. Calculation scales are covered in How calculation scales and calculation ranges are used.
  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.

Related concepts

(C) Copyright IBM Corporation 1996, 2006. All Rights Reserved.