Calculation Framework Guide

IBM WebSphere Commerce

Calculation Framework GuideVersion 5.4

Note:Before using this information and the product it supports, be sure to read the general information under Appendix E,Notices on page 113.

First Edition (May 2002).

This edition applies to version 5.4 of IBM WebSphere Commerce and to all subsequent releases and modificationsuntil otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product.

Order publications through your IBM representative or the IBM branch office serving your locality. Publications arenot stocked at the address given below.

IBM welcomes your comments. You can send your comments by any one of the following methods:1. Electronically to the E-mail address listed below. Be sure to include your entire network address if you wish a

reply.

Internet: [email protected]

2. By regular mail to the following address:

IBM Canada Ltd. LaboratoryB3/KB7/8200/MKM8200 Warden AvenueMarkham, ON L6G 1C7Canada

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in anyway it believes appropriate without incurring any obligation to you.

Copyright International Business Machines Corporation 2002. All rights reserved.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

ContentsBefore you begin . . . . . . . . . . . vConventions used in this book . . . . . . . . vKnowledge requirements . . . . . . . . . . viWhere to find new information . . . . . . . . vi

Chapter 1. Introduction to thecalculation framework . . . . . . . . 1WebSphere Commerce business objects and thecalculation framework . . . . . . . . . . . 1Calculation framework overview . . . . . . . 2

Chapter 2. Calculation methods . . . . 5Database tables for calculation methods . . . . . 7

Calculation method data model diagram . . . . 7How calculation methods work . . . . . . . . 8

General flow of calculation methods . . . . . 10

Chapter 3. Calculation usages. . . . . 13Database tables for calculation usage . . . . . . 13

CALUSAGE database table . . . . . . . . 14STENCALUSG database table . . . . . . . 14Calculation usage data model diagram . . . . 15

Calculation methods for calculation usages . . . . 15InitializeCalculationUsage calculation methods 16ApplyCalculationUsage calculation methods . . 17SummarizeCalculationUsage calculation methods 19FinalizeCalculationUsage calculation methods . . 20

How calculation usages work . . . . . . . . 20How calculation usages are applied . . . . . 21

Chapter 4. Calculation codes . . . . . 23Database tables for calculation codes . . . . . . 24

CALCODE database table . . . . . . . . 25STENCALUSG database table . . . . . . . 27Calculation code data model diagrams . . . . 27

Calculation methods for calculation codes . . . . 28CalculationCodeCombine calculation methods . . 29CalculationCodeQualify calculation methods . . 30CalculationCodeCalculate calculation methods. . 31CalculationCodeApply calculation methods. . . 31

How calculation codes work. . . . . . . . . 32

Chapter 5. Calculation rules . . . . . 35Database tables for calculation rules . . . . . . 35

CALRULE database table . . . . . . . . . 36SHPJCRULE database table . . . . . . . . 37STENCALUSG database table . . . . . . . 38TAXJCRULE database table . . . . . . . . 38Calculation rule data model diagrams . . . . 39

Calculation methods for calculation rules . . . . 41CalculationRuleCombine calculation method . . 41CalculationRuleQualify calculation method . . . 42CalculationRuleCalculate calculation method . . 44

How calculation rules are used . . . . . . . . 45

Chapter 6. Calculation scales andcalculation ranges . . . . . . . . . . 47Calculation scale properties . . . . . . . . . 47Calculation range properties . . . . . . . . . 49Database tables for calculation scales and calculationranges . . . . . . . . . . . . . . . . 50

CALSCALE database table . . . . . . . . 51CALRANGE database table . . . . . . . . 51CALRLOOKUP database table . . . . . . . 52Calculation scale and calculation range datamodel diagram . . . . . . . . . . . . 52

Calculation methods for calculation scales . . . . 53CalculationScaleLookup calculation methods . . 53MonetaryCalculationScaleLookup calculationmethods . . . . . . . . . . . . . . 55QuantityCalculationScaleLookup calculationmethods . . . . . . . . . . . . . . 60CalculationRange calculation method . . . . . 62

How calculation scales and calculation ranges areused . . . . . . . . . . . . . . . . . 64

Processing lookup results associated withcurrencies . . . . . . . . . . . . . . 65Processing lookup results not associated withcurrencies . . . . . . . . . . . . . . 66Calling a CalculationRange calculation method 66

Chapter 7. Examples: Applying thecalculation framework . . . . . . . . 67Discounts example . . . . . . . . . . . . 67

Discounts example description . . . . . . . 67Discounts example implementation . . . . . 67

Shipping charges example . . . . . . . . . 73Shipping charges example description . . . . 73Shipping charges example implementation . . . 73

Sales tax and shipping tax calculations example . . 87Sales tax and shipping tax calculation exampledescription . . . . . . . . . . . . . 87Sales tax and shipping tax calculation exampleimplementation . . . . . . . . . . . . 88

Appendix A. Additional UML objectmodel diagrams . . . . . . . . . . 101Calculation methods . . . . . . . . . . . 102Calculation usages. . . . . . . . . . . . 103Calculation code direct attachment . . . . . . 103Calculation code indirect attachment . . . . . 104Discounts implementation . . . . . . . . . 104Tax implementation . . . . . . . . . . . 105Shipping implementation . . . . . . . . . 106

Appendix B. UML legend . . . . . . 107

Appendix C. Data model legend . . . 109

Copyright IBM Corp. 2002 iii

Appendix D. Other sources ofinformation . . . . . . . . . . . . 111Online information . . . . . . . . . . . 111API documentation . . . . . . . . . . . 111Database schema . . . . . . . . . . . . 111Bootstrap files . . . . . . . . . . . . . 111

Loading calculation framework data. . . . . . 112Modifying, extending, or overriding existingcalculation logic . . . . . . . . . . . . 112

Appendix E. Notices . . . . . . . . 113Trademarks . . . . . . . . . . . . . . 115

iv WebSphere Commerce Calculation Framework Guide

Before you beginThe IBM WebSphere Commerce Calculation Framework Guide is intended to provide atechnical overview of the calculation framework for Store Developers that need toimplement calculations or extend the default implementation of calculations withinWebSphere Commerce. The IBM WebSphere Commerce Calculation Framework Guideprovides information about the framework and default implementations that areused to perform the calculation of monetary amounts in WebSphere Commerce. Inparticular, it provides details on the following topics:v Calculation methodsv Calculation usagesv Calculation codesv Calculation rulesv Calculation scales

Conventions used in this bookThis book uses the following highlighting conventions:

Boldface type indicates commands or graphical user interface (GUI) controls suchas names of fields, buttons, or menu choices.

Monospaced type indicates examples of text you enter exactly as shown, as well asdirectory paths.

Italic type is used for emphasis and variables for which you substitute your ownvalues.

This icon marks a Tip additional information that can help youcomplete a task.

AIX indicates information that is specific to WebSphere Commerce for AIX.

Linux indicates information that is specific to WebSphere Commerce for Linux.

400 indicates information specific to WebSphere Commerce for the IBMEserver iSeries 400 (formerly called AS/400)

Solaris indicates information that is specific to WebSphere Commerce forSolaris Operating Environment software.

2000 indicates information that is specific to WebSphere Commerce forWindows 2000.

NT indicates information that is specific to WebSphere Commerce forWindows NT.

Copyright IBM Corp. 2002 v

Knowledge requirementsThis book should be read by Store Developers that need to understand how tocreate or change calculations within WebSphere Commerce. Store Developers thatare implementing and customizing calculations should have knowledge in thefollowing areas:v Java programmingv Structured Query Language (SQL)v XMLv WebSphere Commerce store development

Where to find new informationThis book may be updated in the future. Check the following WebSphereCommerce Web sites for updates:

WebSphere Commerce Business Editionhttp://www.ibm.com/software/webservers/commerce/wc_be/lit-tech-general.html

WebSphere Commerce Professional Editionhttp://www.ibm.com/software/webservers/commerce/wc_pe/lit-tech-general.html

Updates may include new information and additional tutorials.

vi WebSphere Commerce Calculation Framework Guide

Chapter 1. Introduction to the calculation frameworkCommerce systems need to calculate monetary amounts, such as discounts,shipping charges, and taxes, and apply them to applicable business objects such asobjects representing line items in an order. Business rules and legal requirementsspecify how and under what conditions these monetary amounts should becalculated. When these rules and requirements change, a good commerce systemcan adapt to the changes with little or no programming changes.

WebSphere Commerce provides a flexible, generic framework that can be used toimplement different kinds of calculations and apply them to the applicablebusiness objects. The framework can handle a wide variety of business and legalrequirements without programming. WebSphere Commerce provides a number ofoverridable method implementations from which you can select to do thecalculations. If business or legal requirements require a programming change,many such changes can be limited to programming additional overridable methodimplementations without having to make any changes to existing programming.

The calculation framework is part of the WebSphere Commerce order subsystem.The order subsystem is a component of the WebSphere Commerce Server whichprovides shopping carts, order processing, and order management functionsupport. Related services, such as pricing, taxation, payment, inventory, andfulfillment, are also part of the order subsystem. For more information on the ordersubsystem, see the online information.

WebSphere Commerce business objects and the calculationframework

The WebSphere Commerce calculation framework calculates monetary amountsassociated with OrderItem business objects. An OrderItem represents somethingthat a customer has selected for purchase. Each OrderItem has a reference to anoffer, a contract, a shipping mode, and a fulfillment center. Monetary amountsdetermined by the calculation framework are stored with each OrderItem.

Each OrderItem also has a quantity attribute that is a unitless number. Thequantity attribute can be multiplied by the nominal quantity attribute of theCatalogEntryShippingInformation object associated with the CatalogEntry object toarrive at the actual quantity represented by the OrderItem. TheCatalogEntryShippingInformation object specifies the unit of measurement inwhich quantities are stated.

OrderItems can be grouped to make an Order. OrderItems that are part of anOrder can be grouped to form SubOrders. OrderItems in a SubOrder object havethe same shipping address, and can be used to display subtotals of their OrderItemamounts.

All OrderItems in an Order are associated with a single currency.

The total monetary amounts calculated for the discounts, shipping charges, andtaxes for the OrderItems in the Order are stored with the Order.

Copyright IBM Corp. 2002 1

Calculation framework overviewThere are five major components to the WebSphere Commerce calculationframework. They are:

Calculation methodsCalculation methods reference task commands to implement the parts ofthe calculation framework. Calculation methods are covered in more detailin Chapter 2, Calculation methods on page 5.

Calculation usagesCalculation usages are the categories of calculations that are performedusing the calculation framework. Examples of calculation usages includediscounts and sales tax. Calculation usages are covered in more detail inChapter 3, Calculation usages on page 13.

Calculation codesCalculation codes indicate the calculations to be performed for OrderItems.Calculation codes are covered in more detail in Chapter 4, Calculationcodes on page 23.

Calculation rulesCalculation rules calculate the monetary amounts for the calculation codesassociated with an OrderItem. Calculation rules are covered in more detailin Chapter 5, Calculation rules on page 35.

Calculation scales and calculation rangesCalculation scales allow a calculation rule to determine monetary amountsin a way similar to looking up a value from a table. Calculation rangesdefine the relationship between a lookup number and value to be locatedfor a calculation scale. Calculation scales and calculation ranges arecovered in more detail in Chapter 6, Calculation scales and calculationranges on page 47.

2 WebSphere Commerce Calculation Framework Guide

For more information on the conventions used in this diagram, seeAppendix B, UML legend on page 107.

Notes:

1. StoreEntityCalculationUsageRel describes the high-level behavior of acalculation usage within a store or store group.

2. The relationship indicated between CalculationRule and TaxCategory onlyapplies for sales tax and shipping tax calculation usages.

3. Additional UML object model diagrams for the calculation framework are inAppendix A, Additional UML object model diagrams on page 101. The UMLobject model diagrams are also available in the online information.

Some of the major relationships between the calculation framework components are shownin the following UML object model diagram. Calculation methods have been omitted tomake the illustration simpler.

CalculationCodeTaxExempt

+defaultCalculationCode +definedCalculationCode

+definedCalculationScale

1

1

11

0..1

0..1

0..1

0..1

0..1

CalculationCode

CalculationRule

CalculationScale

CalculationRange

CalculationRangeLookupResultCurrency

QuantityUnit

CalculationUsage

TaxCategory

StoreEntityCalculationUsageRel StoreEntity

Figure 1. UML object model showing major relationships between calculation frameworkcomponents (calculation methods omitted)

Chapter 1. Introduction to the calculation framework 3

Chapter 2. Calculation methodsA calculation method implements a piece of the calculation framework. Differentcalculation method classes are used for the different operations that are required tocomplete a calculation within the calculation framework.

Using a number of calculation methods to perform calculations instead of onelarge calculation method makes customizing calculations much simpler.Customizing a calculation can often only require modifying or overriding one ortwo of the calculation methods involved in performing the calculation.

Calculation methods use the information that is part of calculation usages,calculation codes, and calculation scales to determine monetary amounts forOrderItems. Calculation methods are categorized by the task they perform withinthe calculation framework and the part of the calculation framework thecalculation method belongs to. The following tasks are performed as part of thecalculation framework:

ApplicationApplication involves persisting the monetary amounts calculated forOrderItems to the WebSphere Commerce database so that the monetaryamounts can be used in later calculations.

InitializationInitialization involves resetting any variables used in calculations andclearing any previously calculated results.

CombinationCombination involves determining the relationships between OrderItemsand calculation codes, calculation rules, or calculation scales. Combinationcan also involve determining the order in which calculation codes areapplied to OrderItems.

QualificationQualification involves restricting the set of applicable calculation codes,calculation rules, or calculation scales using some criteria that existsoutside of the calculation framework. For example, certain calculationcodes may apply only to customers belonging to a specific member group.Qualification is a sub-task of combination.

CalculationCalculation involves the determination of a monetary amount that appliesto OrderItems.

LookupLookup involves using one value to determine another value.

SummarizationSummarization involves determining totals of the monetary amounts forOrderItems. An example of summarization is producing the total taxes foran order by adding the taxes calculated for each OrderItem in the order.

FinalizationFinalization involves any processing that occurs after application. Anexample of finalization is marking any coupons used in an order toprevent the coupons from being used in other orders.


Different methods are used for applying, combining, finalizing, qualifying, andsummarizing different pieces of the calculation framework. The calculationmethods are assigned a subclass to categorize how the calculation method will beused. WebSphere Commerce provides the following calculation method subclasses,listed in the order they are used within the calculation framework:v InitializeCalculationUsagev ApplyCalculationUsagev CalculationCodeApplyv CalculationCodeCombinev CalculationCodeQualifyv CalculationCodeCalculatev CalculationRuleCombinev CalculationRuleQualifyv CalculationRuleCalculatev MonetaryCalculationScaleLookupv QuantityCalculationScaleLookupv CalculationRangev SummarizeCalculationUsagev FinalizeCalculationUsage

The subclass of a calculation method indicates the interface from which itscorresponding command extends. The following table shows the calculationmethod subclasses and their related interfaces

Table 1. Calculation method subclasses and their related interfacesCalculation method subclass Interface

InitializeCalculationUsage com.ibm.commerce.order.calculation.InitializeCalculationUsageCmd

ApplyCalculationUsage com.ibm.commerce.order.calculation.ApplyCalculationUsageCmd

CalculationCodeApply com.ibm.commerce.order.calculation.CalculationCodeApplyCmd

CalculationCodeCombine com.ibm.commerce.order.calculation.CalculationCodeCombineCmd

CalculationCodeQualify com.ibm.commerce.order.calculation.CalculationCodeQualifyCmd

CalculationCodeCalculate com.ibm.commerce.order.calculation.CalculationCodeCalculateCmd

CalculationRuleCombine com.ibm.commerce.order.calculation.CalculationRuleCombineCmd

CalculationRuleQualify com.ibm.commerce.order.calculation.CalculationRuleQualifyCmd

CalculationRuleCalculate com.ibm.commerce.order.calculation.CalculationRuleCalculateCmd

MonetaryCalculationScaleLookup com.ibm.commerce.order.calculation.CalculationScaleLookupCmd

QuantityCalculationScaleLookup com.ibm.commerce.order.calculation.CalculationScaleLookupCmd

CalculationRange com.ibm.commerce.order.calculation.CalculationRangeCmd

SummarizeCalculationUsage com.ibm.commerce.order.calculation.SummarizeCalculationUsageCmd

FinalizeCalculationUsage com.ibm.commerce.order.calculation.FinalizeCalculationUsageCmd

The Java classes that make up the calculation framework are part of thecom.ibm.commerce.order.calculation package. See the online API documentationfor more information on this Java package.


Database tables for calculation methodsCalculation methods are defined in the CALMETHOD database table. TheCALMETHOD database table contains the following information about calculationmethods:

Calculation method ID (CALMETHOD_ID)This is a unique, numeric identifier for the calculation method.

Store entity ID (STOREENT_ID)This is the identifier for the store or store group to which the calculationmethod belongs.

Calculation usage ID (CALUSAGE_ID)This is the calculation usage to which the calculation method applies. Formore information on calculation usages, see Chapter 3, Calculationusages on page 13.

Subclass (SUBCLASS)This is a number that indicates the subclass of the calculation method. Thefollowing table shows the number assigned each subclass:

Table 2. Available subclassesSubclass number Subclass

1 CalculationCodeCombine

2 CalculationCodeQualify

3 CalculationCodeCalculate

4 CalculationCodeApply

5 CalculationRuleCombine

6 CalculationRuleQualify

7 CalculationRuleCalculate

8 QuantityCalculationScaleLookup

9 MonetaryCalculationScaleLookup

10 CalculationRange

11 InitializeCalculationUsage

12 ApplyCalculationUsage

13 SummarizeCalculationUsage

14 FinalizeCalculationUsage

Java interface name (TASKNAME)This is the complete name of the Java interface for a calculation method.For example,com.ibm.commerce.order.utils.CalculationCodeCodeCombineCmd. Thesame Java interface can be used for multiple calculation methods.

Calculation method data model diagramThe following data model diagram provides an illustration of the relationshipsbetween the database tables used to define calculation methods.

Chapter 2. Calculation methods 7

For more information on the conventions used in this diagram, seeAppendix C, Data model legend on page 109.

For details on the database tables in the diagram and other columns of theCALMETHOD database table, refer to the database schema documentation in theonline information.

How calculation methods workVarious calculation methods are called when WebSphere Commerce calculatesmonetary amounts. Each subclass of calculation method is used for the othercomponents of the calculation framework. The subclasses of calculation methodsare covered in the other chapters of this book as follows:

Chapter 3, Calculation usages on page 13

InitializeCalculationUsageThis calculation method can be called by the OrderPreparecommand to initialize the calculation of monetary amounts. Anexample of initialization is removing previously calculated values.

ApplyCalculationUsageThis calculation method can be called by the OrderPreparecommand to calculate monetary amounts and apply them to anorder. The ApplyCalculationUsage calculation method can also becalled by data beans to calculate monetary amounts for displaypurposes. Examples of calculated amounts include orderadjustments, shipping charges, and tax amounts. The defaultimplementations of this calculation method provided withWebSphere Commerce call the CalculationCodeCombine,CalculationCodeCalculate, and CalculationCodeApply calculationmethods.

SummarizeCalculationUsageThis calculation method can be called by the OrderPrepare

Figure 2. Calculation method data model diagram


command to summarize calculated values and apply them to anorder. Examples include populating SubOrderAdjustments orSubOrder shipping charges or tax amounts.

FinalizeCalculationUsageThis calculation method can be called by the OrderProcesscommand to mark consumed resources, such as coupons, as nolonger available.

Chapter 4, Calculation codes on page 23

CalculationCodeApplyThis calculation method can be called by theApplyCalculationUsage calculation method to apply the calculatedvalues for a list of OrderItems to an order.

CalculationCodeCombineThis calculation method can be called by theApplyCalculationUsage calculation method to identifyrelationships between OrderItems and calculation codes. Thedefault implementations of the CalculationCodeCombinecalculation method provided with WebSphere Commerce use theCATENCALCD, CATGPCALCD, ORDICALCD, and ORDCALCDdatabase tables, and call the CalculationCodeQualify calculationmethod.

CalculationCodeQualifyThis calculation method can be called by theCalculationCodeCombine calculation method to determine if acalculation code applies to a list of OrderItems.

CalculationCodeCalculateThis calculation method can be called by theApplyCalculationUsage calculation method to calculate values fora list of OrderItems for a particular CalculationCode.

Chapter 5, Calculation rules on page 35

CalculationRuleCombineThis calculation method can be called by theCalculationCodeCalculate calculation method to determine a list ofcalculation rules and associated OrderItems that should be appliedfor a calculation code. The default implementations of theCalculationRuleCombine calculation method provided withWebSphere Commerce call the CalculationRuleQualify calculationmethod and the CalculationRuleCalculate calculation method tofind the lowest values for each allowable combination ofcalculation rules.

CalculationRuleQualifyThis calculation method can be called by theCalculationRuleCombine calculation method to determine to whichof the OrderItems in a list a calculation rule applies.

CalculationRuleCalculateThis calculation method can be called by theCalculationRuleCombine calculation method to calculate values fora list of OrderItems.

Chapter 6, Calculation scales and calculation ranges on page 47


MonetaryCalculationScaleLookupThis calculation method can be called by theCalculationRuleCalculate calculation method to determine how amonetarybased calculation scale can be used to determine acalculation range for a list of OrderItems.

QuantityCalculationScaleLookupThis calculation method can be called by theCalculationRuleCalculate calculation method to determine how aquantitybased calculation scale can be used to determine acalculation range for a list of OrderItems.

CalculationRangeThis calculation method can be called by theCalculationRuleCalculate calculation method to determine acalculated value from a calculation range lookup result.

General flow of calculation methodsThe general flow of calculation methods, when they are used as part of the orderprocess, is as follows:1. InitializeCalculationUsage calculation method2. ApplyCalculationUsage calculation method calls:

a. CalculationCodeCombine calculation method calls:1) CalculationCodeQualify calculation method

b. CalculationCodeCalculate calculation method calls:1) CalculationRuleCombine calculation method calls:

a) CalculationRuleQualify calculation methodb) CalculationRuleCalculate calculation method calls:

i. CalculationScaleLookup calculation methodii. CalculationRange calculation method

c. CalculationCodeApply calculation method3. SummarizeCalculationUsage calculation method4. FinalizeCalculationUsage calculation method

The ApplyCalculationUsage calculation method can also be called by data beans tocalculate monetary amounts used for display purposes outside of order processing.

The following figure illustrates the flow of calculation methods called by theApplyCalculationUsage calculation method:


For information on the conventions used in this diagram, seeAppendix B, UML legend on page 107.

CalculationRuleCalculateCmd

CalculationRangeCmdCalculationScaleLookupCmd

CalculationRuleCombineCmd

CalculationCodeQualifyCmd

CalculationRuleQualifyCmd

CalculationCodeCombineCmd CalculationCodeCalculateCmd

ApplyCalculationUsageCmd

CalculationCodeApplyCmd

Figure 3. Calculation methods called by the ApplyCalculationUsage calculation method


Chapter 3. Calculation usagesThe WebSphere Commerce calculation framework is a generic framework forcalculations. When implementing a calculation using the calculation framework,the first thing that needs to be defined is the type of calculation to be performed.The types of calculations the calculation framework performs are called calculationusages. Calculation usages are assigned a calculation usage code.

WebSphere Commerce provides five predefined calculation usages. The predefinedusages are as follows:

Table 3. Predefined calculation usagesCalculation usage Calculation usage code

Discount -1

Shipping -2

Sales tax -3

Shipping tax -4

Coupon -5

WebSphere Commerce performs all calculations for one calculation usage at a time.The order of calculation usages is stored in the SEQUENCE column of theSTENCALUSG database table. The entries in this table are initially populated withinformation from the language-independent bootstrap file: wcs.bootstrap.xml. Formore information on bootstrap files, see Bootstrap files on page 111.

The default order in which calculation usages are processed, as defined inwcs.bootstrap.xml, is as follows:1. Coupon2. Discount3. Shipping4. Sales tax5. Shipping tax

Database tables for calculation usageInformation about calculation usages is stored in the following database tables:

CALUSAGEThis table contains a unique identifier for each calculation usage and adescription of the calculation usage.

Values in this table are defined in the languagedependent bootstrap file.For more information on bootstrap files, see Bootstrap files on page 111.

STENCALUSGThis table defines the highlevel behavior of a calculation usage for a storeor group of stores. If the implementation for a store is not defined, theimplementation for the store group that the store belongs to will be used.If different implementations are defined for both the store and the storegroup, the implementation for the store is used.


This database table is initially populated from the languageindependentbootstrap file. For more information on bootstrap files, see Bootstrap fileson page 111.

The following sections discuss key calculation usage attributes that are stored insome of the database tables. For details on all the columns of the calculation usagedatabase tables and other database tables, refer to the database schemadocumentation in the online help. All of the attributes discussed in the followingsections are required unless they are marked optional.

CALUSAGE database tableThe CALUSAGE database table contains the following information about acalculation usage:

Calculation usage ID (CALUSAGE_ID)This is a numeric, unique identifier for the calculation usage.

Calculation usage description (DESCRIPTION) (optional)This is a description of the calculation usage

STENCALUSG database tableThe STENCALUSG database table contains the information relating a store or storegroup to a calculation usage as follows:

Store or store group identifier (STOREENT_ID)This is the store or the store group for which the calculation usage isimplemented.

Calculation usage identifier (CALUSAGE_ID)This identifies the calculation usage being implemented for the store orstore group.

Sequence (SEQUENCE)Calculation usages are processed in ascending order based on this column.

Usage (USAGEFLAG)This is a bit flag that controls whether a calculation usage is enabled andhow WebSphere Commerce handles the results from an enabled calculationusage. Valid values for this attribute are as follows:

0 (default)This calculation usage is disabled in this store or store group.

1 This calculation usage is enabled and may return a value for anOrderItem. If no value is returned for an OrderItem, the value isassumed to be zero.

2 This calculation usage is enabled and must always return a valuefor an OrderItem. If no value is returned for an OrderItem, anECApplicationException is thrown.

InitializeCalculationUsage calculation method (CALMETHOD_ID_INI)(optional)

This is the calculation method used to initialize calculations. Initializingcalculations involves setting any initial values required to perform acalculation and clearing any previously calculated results.

ApplyCalculationUsage calculation method (CALMETHOD_ID_APP) (optional)This is the calculation method used to apply the calculation usage.


Applying a calculation usage involves persisting the calculated monetaryamounts to the WebSphere Commerce database.

SummarizeCalculationUsage calculation method (CALMETHOD_ID_SUM)(optional)

This is the calculation method used to summarize the calculation usage.Summarizing a calculation usage involves determining totals for order andsuborders based on the monetary amounts calculated for the OrderItemsin the order.

FinalizeCalculationUsage calculation method (CALMETHOD_ID_FIN)(optional)

This is the calculation method used to finalize the calculation usage.Finalizing a calculation involves any processing that must be completedafter the calculations are applied. An example of finalizing a calculationusage is marking any coupons used in an order to prevent the couponsfrom being applied to other orders.

Default calculation code (CALCODE_ID) (optional)If an OrderItem has no calculation code attached to it for this calculationusage, then the default calculation code is used.

Calculation usage data model diagramThe following data model diagram provides an illustration of the relationshipsbetween the database tables used to define calculation usages.

For information on the conventions used in the diagram, see Appendix C,Data model legend on page 109.

For details on the database tables in the diagram refer to the database schemadocumentation in the online information.

Calculation methods for calculation usagesThere are four calculation method subclasses associated with calculation usages:

Figure 4. Calculation usage data model diagram

Chapter 3. Calculation usages 15

InitializeCalculationUsageInitializeCalculationUsage calculation methods are called by theOrderPrepare command for each calculation usage specified in theUSAGEFLAGS column of the STENCALUSG database table prior to callingthe ApplyCalculationUsage calculation method.

ApplyCalculationUsageApplyCalculationUsage calculation methods are called by theOrderPrepard command for each calculation usage specified byUSAGEFLAGS column of the STENCALUSG database table. Thesemethods may also be called from data beans or other task commands tocalculate amounts for items not necessarily in an Order. For example, theGetReturnTaxes task command calls the ApplyCalculationUsage methodfor the sales tax calculation usage.

SummarizeCalculationUsageSummarizeCalculationUsage calculation methods are called by theOrderPrepare command for each calculation usage specified inUSAGEFLAGS column of the STENCALUSG database table after callingthe ApplyCalculationUsage calculation methods.SummarizeCalculationUsage calculation methods summarize the calculatedamounts. For example, the SummarizeCalculationUsage method for thesales tax calculation usage populates the SUBORDTAX database table andthe SUBORDERS.TOTALTAX columns. The SUBORDTAX database tablecontains tax information for the OrderItems in a SubOrder.

FinalizeCalculationUsageFinalizeCalculationUsage calculation methods are called by theProcessOrder task command for each calculation usage specified inUSAGEFLAGS column of the STENCALUSG database table. For example,the FinalizeCalculationUsage method for the coupon calculation usagemarks the coupons applied to an order to prevent the coupons from beingapplied to a different order.

The following section discusses these calculation method subclasses and thedefault implementations provided with WebSphere Commerce. Additionalinformation on the interfaces and commands that implement the calculationmethod subclasses can be found in the API documentation in the onlineinformation.

InitializeCalculationUsage calculation methodsInitializeCalculationUsage calculation methods do any processing required beforemonetary amounts for OrderItems are calculated. For example, anInitializeCalculationUsage calculation method can remove previously calculatedvalues from the OrderItems in the order.

Any commands that will be used as an InitializeCalculationUsage calculationmethod subclass must implement the InitializeCalculationUsageCmd interface. Formore information on the InitializeCalculationUsageCmd interface, see the APIdocumentation in the online information.

The following InitializeCalcluationUsage calculation methods are provided withWebSphere Commerce:v InitializeAdjustmentCmdImplv InitializeCouponUsageCmdImplv InitializeSalesTaxCmdImpl


v InitializeShippingCmdImplv InitializeShippingTaxCmdImpl

InitializeAdjustmentCmdImplThis command implements the InitializeAdjustmentCmd interface that extends theInitializeCalculationUsageCmd interface.

This is the discountspecific command used to initialize values for discountcalculations.

InitializeCouponUsageCmdImplThis command implements the InitializeCouponUsageCmd interface that extendsthe InitializeCalculationUsageCmd interface.

This is a coupon specific command.

InitializeSalesTaxCmdImplThis command implements the SalesTaxCmd interface that extends theInitializeCalculationUsageCmd interface.

This is the sales tax specific command used to initialize values for sales taxcalculations.

InitializeShippingCmdImplThis command implements the InitializeShippingCmd interface that extends theInitializeCalculationUsageCmd interface.

This is the shipping specific command used to initialize values for shipping chargecalculations.

InitializeShippingTaxCmdImplThis command implements the InitializeShippingTaxCmd interface that extends theInitializeCalculationUsageCmd interface.

This is the shipping tax specific command used to initialize values for shipping taxcalculations.

ApplyCalculationUsage calculation methodsApplyCalculationUsage calculation methods are used for both order processingand product display purposes. During order processing, an ApplyCalculationUsagecalculation method is called by the OrderPrepare command to calculate themonetary amounts for a list of OrderItems. A monetary amount is applied to eachOrderItem so the monetary amount is available for later calculations.

For display purposes, ApplyCalculationUsage calculation methods are called bydata beans to calculate monetary amounts. For example, taxes for a product can bedisplayed as part of the products display page. The data bean calling theApplyCalculationUsage calculation method must perform any initialization thatwould normally be performed by the InitializeCalculationUsage calculation methodfor the calculation usage being processed for the data bean. The data bean does nothave access to the InitializeCalculationUsage, SummarizeCalculationUsage, orFinalizeCalculationUsage calculation methods.

Additionally, the The GetReturnTaxes task command also calls theApplyCalculationUsage method for the sales tax calculation usage, without callingthe Initialize, Summarize, or Finalize methods.


Any commands that will be used as an ApplyCalculationUsage calculation methodsubclass must implement the ApplyCalculationUsageCmd interface. For moreinformation on the ApplyCalculationUsageCmd interface, see the APIdocumentation in the online information.

The following ApplyCalculationUsage calculation methods are provided withWebSphere Commerce:v ApplyCalculationUsageCmdImplv ApplyCalculationUsageTIKCmdImplv ApplyCouponUsageCmdImplv ApplyShippingCmdImpl

ApplyCalculationUsageCmdImplThis is the default implementation of the ApplyCalculationUsage command.

This command implementation does the following:1. Call the CalculationCodeCombine calculation method to get a list of calculation

codes. For each CalculationCode in the list, the CalculaitonCodeCombinecalculation method also provides a list of the OrderItems to be included in thecalculation.

2. For each calculation code in the list, ApplyCalculationUsageCmdImpl does thefollowing:a. Call the CalculationCodeCalculate calculation method, passing it the

associated list of OrderItems. The CalculationCodeCalculate calculationmethod returns a list of calculated monetary amounts for each OrderItem.The monetary amounts may be categorized by tax category.

b. Call the CalculationCodeApply calculation method, passing it thecalculation code, a list of OrderItems, and the monetary amount associatedwith each OrderItem.

ApplyCalculationUsageTIKCmdImplThis command implements the ApplyCalculationUsageTIKCmd interface, whichextends the ApplyCalculationUsageCmd interface.

The ApplyCalculationUsageTIKCmd interface and theApplyCalculationUsageTIKCmdImpl command are provided as an example toinvoke a set of interfaces supplied in the Tax Integration Interface Kit. IfWebSphere Commerce has been configured to use this interface, the OrderPreparecommand will call ApplyCalculationUsageTIKCmd which in turn invokes theTaxOrderCmd task command provided in the Tax Integration Interface Kit.

For more information on the ApplyCalculationUsageTIKCmd interface and theApplyCalculationUsageTIKCmdImpl command, see the API documentation in theonline information.

ApplyCouponUsageCmdImplThis command implements the ApplyCouponUsageCmd interface that extends theApplyCalculationUsageCmd interface.

This command adds the discount from a coupon promotion to the adjustments inthe ORDERS and ORDERITEMS database tables. The command is invoked when acustomer asks to redeem coupons before preparing an order.

The coupons to apply to an order are located in the ORCPMAP database table.This command finds the coupons to apply to an order in the ORCPMAP database


table and then removes the coupons from the ORCPMAP database table andCPITMAP database table. The found coupons are checked for expiry by callingCheckValidityTaskCmd command. Coupons that are not expired are checked forapplicability by calling the CheckApplicabilityTaskCmd command. The applicablecoupons are called by the CalculateDiscountAmountCmd task command and thediscount amount in the current order is incorporated.

For more information on coupon promotions, see the online information.

ApplyShippingCmdImplThis command is the default implementation of the ApplyShippingCmd interface.The ApplyShippingCmd interface extends the ApplyCalculationUsageCmdinterface.

This is a shipping specific version of the ApplyCalculationUsageCmdImplcommand.

SummarizeCalculationUsage calculation methodsThis calculation method subclass summarizes the results of calculations for displaypurposes.

Any commands that will be used as a SummarizeCalculationUsage calculationmethod subclass must implement the SummarizeCalculationUsageCmd interface.For more information on the SummarizeCalculationUsageCmd interface, see theAPI documentation in the online information.

The following SummarizeCalculationUsage calculation methods are provided withWebSphere Commerce:v SummarizeAdjustmentCmdImplv SummarizeCouponUsageCmdImplv SummarizeSalesTaxCmdImplv SummarizeShippingCmdImplv SummarizeShippingTaxCmdImpl

SummarizeAdjustmentCmdImplThis command implements the SummarizeAdjustmentCmd interface that extendsthe SummarizeCalculationUsageCmd interface.

This is the discount specific command used to summarize discount calculations.

SummarizeCouponUsageCmdImplThis command implements the SummarizeCouponUsageCmd interface thatextends the SummarizeCalculationUsageCmd interface.

This is the coupon specific command used to summarize coupon calculations.

SummarizeSalesTaxCmdImplThis command implements the SummarizeSalesTaxCmd interface that extends theSummarizeCalculationUsageCmd interface.

This is the sales tax specific command used to summarize sales tax calculations.

SummarizeShippingCmdImplThis command implements the SummarizeShippingCmd interface that extends theSummarizeCalculationUsageCmd interface.


This is the shipping specific command used to summarize shipping chargecalculations.

SummarizeShippingTaxCmdImplThis command implements the SummarizeShippingTaxCmd interface that extendsthe SummarizeCalculationUsageCmd interface.

This is the shipping tax specific command used to summarize shipping taxcalculations.

FinalizeCalculationUsage calculation methodsThis calculation usage subclass is used to do any processing required after theOrder has been processed by the ProcessOrder task command.

Any commands that will be used as a FinalizeCalculationUsage calculation methodsubclass must implement the FinalizeCalculationUsageCmd interface. For moreinformation on the FinalizeCalculationUsageCmd interface, see the APIdocumentation in the online information.

The FinalizeCouponUsageCmdImpl is the only FinalizeCalculationUsagecalculation method provided with WebSphere Commerce.

FinalizeCouponUsageCmdImplThis command implements the FinalizeCouponUsageCmd interface that extendsthe FinalizeCalculationUsageCmd interface.

The FinalizeCouponUsageCmdImpl command marks coupons used in the currentorder to prevent the coupons from being used in other orders.

How calculation usages workCalculation usages are invoked by the OrderPrepare command. The OrderPreparecommand creates a list of OrderItems for which monetary amounts will becalculated. The applicable calculation usages for the store or store group to whichthe order belongs are found and processed according to the sequence defined forthem in the STENCALUSG database table.

The OrderPrepare command processes the calculation usages as follows:1. All calculation usages are initialized using the InitializeCalculationUsage

calculation methods referenced in the CALMETHOD_ID_INI column of theSTENCALUSG database table.

2. All calculation usages are applied using the ApplyCalculationUsage calculationmethods referenced in the CALMETHOD_ID_APP column of theSTENCALUSG database table. For more information on how calculationmethods are applied, see How calculation usages are applied on page 21.

3. All calculation usages are summarized using the SummarizeCalculationUsagecalculation methods referenced in the CALMETHOD_ID_SUM column of theSTENCALUSG database table.

After the OrderPrepare controller command completes, the OrderProcess controllercommand is called. The OrderProcess controller command finalizes all calculationusages by calling the FinalizeCalculationUsage calculation methods referenced inthe CALMETHOD_ID_FIN column of the STENCALUSG database table entry foreach calculation usage.


How calculation usages are appliedWhen a calculation usage is applied the following steps occur:1. The ApplyCalculationUsage calculation method calls a

CalculationCodeCombine calculation method. The CalculationCodeCombinecalculation method returns a list. Each item in the returned list consists of acalculation code and the OrderItems in the order to which the calculation codeapplies.

2. The ApplyCalculationUsage calculation method calls aCalculationCodeCalculate calculation method for each item in the list returnedby the CalculationCodeCombine calculation method. TheCalculationCodeCalculate calculation method returns a list. Each item in thereturn list consists of each OrderItem and the monetary amount associated withthe OrderItem for the calculation usage. For tax calculation methods, there maybe 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 CalculationCodeApplycalculation method for each group of OrderItems.

For descriptions of calculation codes and associated calculation methods, includingthe CalculationCodeApply calculation method, see Chapter 4, Calculation codeson page 23.


Chapter 4. Calculation codesItems for sale in a retail store often have attached price tags indicating informationother than the price of the item. For example, if the item is on sale, the price tagindicates the percentage discount to apply to the item to calculate the sale price.Similarly, WebSphere Commerce attaches calculation codes to OrderItems toindicate the calculations to be performed for the OrderItem. The following figureshows a representation of price tags in a retail store compared with calculationcodes in WebSphere Commerce.

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 OrderItems. The attachment of acalculation code can be direct or indirect, depending on where the calculation codeis specified within WebSphere Commerce.

Direct attachment of a calculation code to an OrderItem is similar to a cashierproviding a one-time discount on one item or all items being purchased thecalculation code is specified as part of the order or as part of the OrderItem. Whena calculation code is specified as part of an order, it is attached to all of theOrderItems that make up the order. Information relating a calculation code to anorder is stored in the ORDCALCD database table. Information relating acalculation code to an OrderItem is store in the ORDICALCD database table.

Indirect attachment of a calculation code is similar to posting a sign in a retail storeindicating which items in the store are on sale the information about thediscount is not directly on the price tags of the individual items, but the cashierknows to apply the discount when calculating the cost of an order. Indirectattachment of a calculation code in WebSphere Commerce occurs when thecalculation code is specified as part of a catalog entry or catalog group.

Specifying a calculation code as attached to a catalog entry is similar to the sign inthe retail store indicating that a discount applies to a particular product. Specifyinga calculation code as part of a catalog group is similar to the sign in the retail store

Calculation Code:43

Calculation Code:51

Sales Tax:8%

Discount:10%

OrderItem

Figure 5. Calculation codes indicate the calculations that must performed.


indicating that a discount applies to all products in a particular department.Similarly, when a calculation code is specified as part of a catalog group, thecalculation code applies to all catalog entries in the catalog group. Informationrelating a calculation code to a catalog entry is stored in the CATENCALCDdatabase table. Information relating a calculation code to a catalog group is storedin the CATGPCALCD database table. The CATENCALCD database table is alsoused to attach a calculation code to all catalog entries.

Calculation codes can also be implicitly attached to order items by specifying thedefault calculation code for a calculation usage in the STENCALUSG databasetable. The default calculation code is used for those OrderItems in an order that donot have any directly or indirectly attached calculation codes of a particularcalculation usage. The default calculation code for a particular calculation usagecan be specified at the store level and at the store group level. The defaultcalculation code specified at the store group level is used only when the store leveldefault calculation code is not specified.

While attachment is defined outside of a calculation code, the following propertiesare defined as part of a calculation code:v A calculation usage. This specifies the calculation type for which a calculation

code can be used. Calculation usages are covered in Chapter 3, Calculationusages on page 13.

v Calculation methods used to qualify, calculate, and apply the calculation code.v A flag indicating if a calculation code must be qualified or not.v A flag indicating if the calculation code is active, inactive, or marked for

deletion.v The method of grouping OrderItems for calculations.v A sequence number. The sequence number is used to determine the order of

calculations when multiple calculation codes of the same calculation usage applyto an OrderItem.

v A time range during which the calculation code is in effect.

These properties are defined in the CALCODE database table. The CALCODEdatabase table and other database tables that affect the way calculation codes areused are discussed in the next section.

Database tables for calculation codesIn WebSphere Commerce, information about calculation codes is stored in thefollowing database tables:

CALCODEThis is the main database table that defines calculation codes.

CALCODEDSCThis database table contains national language descriptions of a calculationcode, allowing one calculation code to have a description in multiplelanguages.

CALCODEMGPThis database table associates a calculation code with a member group,restricting the use of a calculation code to members of a certain membergroup.

CALCODTXEXThis database table associates a calculation code with a tax category,


indicating that the monetary amounts determined by the calculation codeare exempt from the taxes associated with the tax category.

CATGPCALCDThis database table attaches a calculation code with catalog group in aspecific store and, optionally, for a specific trading agreement. An exampleof a trading agreement is a contract. Information about contracts andtrading agreements is provided in the online information.

All catalog entries belonging to the catalog group are associated with thecalculation code assigned to the catalog group.

CATENCALCDThis database table attaches a calculation code with one catalog entry or allcatalog entries in a specific store and, optionally, for a specific tradingagreement. An example of a trading agreement is a contract. Informationabout contracts and trading agreements is provided in the onlineinformation.

ORDCALCDThis database table attaches a calculation code to an order. This tableallows you to specify whether indirectly attached calculation codes shouldbe ignored.

ORDICALCDThe database table attaches a calculation code to an OrderItem. This tableallows you to specify whether indirectly attached calculation codes shouldbe ignored.

STENCALUSGThis database table defines the default calculation code for a calculationusage in a store or group of stores. This table also specifies theCalculationCodeCombine calculation method subclass that determines howmultiple calculation codes for an OrderItem are combined.

The following sections discuss key calculation code attributes that are stored insome of the database tables. For details on all the columns of the calculation codedatabase tables, refer to the database schema documentation in the onlineinformation. All of the attributes discussed in the following section are requiredunless they are marked optional.

CALCODE database tableThe CALCODE database table contains the following information about acalculation code:

Calculation code ID (CALCODE_ID)This is a numeric, unique identifier for the calculation code.

Identifying string (CODE)This is a character string that uniquely identifies this calculation code,given a particular calculation usage and store or store group.

CalculatonCodeCalculate calculation method (CALMETHOD_ID)This is the identifier of the calculation method that calculates the monetaryamounts for OrderItems for this calculation code.

CalculationCodeApply calculation method (CALMETHOD_ID_APP)This is the identifier of the calculation method that persists the calculatedmonetary amounts.

Chapter 4. Calculation codes 25

CalculationCodeQualify calculation method (CALMETHOD_ID_QFY)This is the identifier of the calculation method responsible for determiningwhich of the available calculation codes for the OrderItems should be used.

Calculation usage ID (CALUSAGE_ID)This is the identifier of the calculation usage to which the calculation codeapplies.

Effective time range (STARTDATE and ENDDATE) (optional)These two values define the time period the calculation rule is effective. Ifnone of the values is defined, the calculation code is always in effect. IfSTARTDATE is defined and ENDDATE is not, the calculation code isalways effective after the time and date defined in STARTDATE. IfSTARTDATE is not defined and ENDDATE is defined, the calculation codeis effective immediately and expires on the date and time defined inENDDATE.

The effective time range is checked by the CalculationCodeCombinecalculation method.

Grouping method (GROUPBY)This column is used to indicate how the CalculationCodeCombinecalculation method will group OrderItems for performing calculations. TheCalculationCodeCalculate and CalculationCodeApply calculation methodsare used repeatedly, once for each group of OrderItems, to calculate andapply monetary amounts to the OrderItems in each group. The defaultgrouping is no grouping all OrderItems are placed in one group and theCalculationCodeCalculate and CalculationCodeApply calculation methodsare called only once.

OrderItems can be grouped in the following ways:

By addressAll OrderItems with the same shipping address are placed in thesame group and the calculation code is evaluated once for eachdifferent shipping address.

By contractAll OrderItems with the same Contract are placed in the samegroup and the calculation code is evaluated once for each differentcontract.

By offerAll OrderItems with the same Offer are placed in the same groupand the calculation code is evaluated once for each different offer.

By productAll OrderItems with the same parent product are placed in thesame group and the calculation code is evaluated once for eachdifferent parent product.

These groups can also be combined so that OrderItems with the samecatalog entries and the same Contracts are grouped together or OrderItemswith the same Offer and the same Contract are grouped together. Whencombining groups, the calculation code is evaluated once for each differentcombination.

Sequence (SEQUENCE)When multiple calculation codes with the same calculation usage areprocessed, they are processed in ascending order based on the numericvalues of this property.


Store or store group identifier (STOREENT_ID)This is the store or the store group to which this calculation code belongs.A calculation code can only belong to one store or store group.

Tax code classification (TXCDCLASS_ID) (optional)If this calculation code is used to calculate taxes, then it can be groupedtogether with other tax calculation codes into a tax code classification.

Qualification flag (FLAGS)This flag allows you to specify whether a CalculationCodeQualifycalculation method should be invoked. The default setting is that theCalculationCodeQualify calculation method will not be invoked.

This flag does not affect whether the CalculationCodeCombine calculationmethod checks the effective time range of a calculation code; this checkcannot be prevented.

STENCALUSG database tableThe STENCALUSG database table contains the following information aboutcalculation codes:

CalculationCodeCombine calculation method (ACTCC_CALMETHOD_ID)(optional)

This is the identifier of the CalculationCodeCombine calculation method. Ifa CalculationCodeCombine calculation method is not specified for a store,then the CalculationCodeCombine calculation method defined for the storegroup is used.

The STENCALUSG database table also contains information about calculationusages. Calculation usages are covered in Chapter 3, Calculation usages onpage 13.

Calculation code data model diagramsThe following data model diagrams provide illustrations of the relationshipsbetween the database tables used to define calculation codes, the database tablesused to define direct attachment of calculation codes, and the database tables usedto define indirect attachment of calculation codes.

Figure 6. Calculation code data model diagram


For information on the conventions used in these diagrams, seeAppendix C, Data model legend on page 109.

For details on the database tables in the diagrams refer to the database schemadocumentation in the online information.

Calculation methods for calculation codesThere are four calculation method subclasses associated with calculation codes:v CalculationCodeCombinev CalculationCodeQualifyv CalculationCodeCalculatev CalculationCodeApplyThis section discusses these calculation method subclasses and the defaultimplementations provided with WebSphere Commerce. Additional information onthe interfaces and commands that implement the calculation method subclassescan be found in the API documentation in the online information.

Figure 7. Calculation code direct attachment data model diagram

Figure 8. Calculation code indirect attachment data model diagram


CalculationCodeCombine calculation methodsCalculationCodeCombine calculation methods determine which calculation codesare applied to which OrderItems and the sequence in which the calculation codesare applied. For tax calculation usages, a list of tax categories can also be specified.

A CalculationCodeCombine calculation method returns a list where each item inthe list consists of the following:v A calculation codev A list of OrderItems to which the calculation code appliesv A list of monetary amounts corresponding to each OrderItem. This list is only

provided if the monetary amounts have previously been calculated by aCalculationCodeCalculate calculation method to prevent theCalculationCodeCalculate calculation method from being called unnecessarily.

For tax calculations, the monetary amount corresponding to each OrderItem maybe separated into the amount for each tax category applicable to the OrderItem.

Any commands that will be used as a CalculationCodeCombine calculationmethod subclass must implement the CalculationCodeCombineCmd interface. Formore information on the CalculationCodeCombineCmd interface, see the APIdocumentation in the online information.

The following CalculationCodeCombine calculation methods are provided withWebSphere Commerce:v CalculationCodeCombineCmdImplv TaxCalculationCodeCombineCmdImpl

CalculationCodeCombineCmdImplThis is the default implementation of the CalculationCodeCombine calculationmethod.

This command does the following, given a calculation usage and a list ofOrderItems:1. Using the list of OrderItems, the CalculationCodeCombineCmdImpl command

creates a list of all calculation codes attached to the OrderItems. Onlycalculation codes belonging to the calculation usage being processed areconsidered. Calculation codes directly attached to OrderItems are found first,followed by indirectly attached calculation codes. If no directly or indirectlyattached calculation codes are found, the default calculation code is used.

2. For each calculation code found, the command does the following:a. If the qualification flag attribute of the calculation code is set to 1, then the

CalculationCodeQualify calculation method is called . A calculation codeand the list of OrderItems is passed to the CalculationCodeQualifycalculation method to check which OrderItems belong to the calculationcode. The CalculationCodeQualify calculation method returns a modifiedlist of OrderItems. The modified list of OrderItems consists only ofOrderItems to which the calculation code applies. OrderItems to which thecalculation code does not apply have been removed.

b. Groups the OrderItems according to the grouping method of the calculationcode. A group consists of one or more OrderItems. For information on howOrderItems are grouped, see CALCODE database table on page 25.

3. The CalculationCodeCombineCmdImpl command returns a list where each listitem consists of a calculation code and one or more groups of OrderItems. Thereturned list is sorted by the sequence attribute of the calculation code. The


calculation code with the lowest sequence attribute appears first on the list. Ifmultiple calculation codes have the same sequence number, the calculationcodes are also sorted by calculation code ID, with the lowest calculation codeID appearing first.

TaxCalculationCodeCombineCmdImplThis command implements the TaxCalculationCodeCombineCmd interface thatextends the CalculationCodeCombineCmd interface.

This command does the following, given a calculation usage and a list ofOrderItems:1. Using the list of OrderItems, the TaxCalculationCodeCombineCmdImpl

command creates a list of all calculation codes attached to the OrderItems. Onlycalculation codes belonging to the tax calculation usage being processed areconsidered. Calculation codes directly attached to OrderItems are found first,followed by indirectly attached calculation codes. If no directly or indirectlyattached calculation codes are found, the default calculation code is used.

Important: If multiple calculation codes are found, only the calculation codewith the highest sequence value is used.

2. For each calculation code found, the command does the following:a. If the qualification flag attribute of the calculation code is set to 1, then the

CalculationCodeQualify calculation method is called. A calculation code andthe list of OrderItems is passed to the CalculationCodeQualify calculationmethod to check which OrderItems belong to the calculation code. TheCalculationCodeQualify calculation method returns a modified list ofOrderItems. The modified list of OrderItems consists only of OrderItems towhich the calculation code applies. OrderItems to which the calculationcode does not apply have been removed.

b. Groups the OrderItems according to the grouping method of the calculationcode. A group consists of one or more OrderItems. For information on howOrderItems are grouped, see CALCODE database table on page 25.

3. Returns a list where each list item consists of a calculation code and one ormore groups of OrderItems. The returned list is sorted by the sequenceattribute of the calculation code. The calculation code with the lowest sequenceattribute appears first on the list. If multiple calculation codes have the samesequence number, the calculation codes are also sorted by calculation code ID,with the lowest calculation code ID appearing first.

CalculationCodeQualify calculation methodsCalculationCodeQualify calculation methods check if a calculation code applies toa list of OrderItems. This calculation method returns a list of OrderItems to whicha calculation code applies.

CalculationCodeQualify calculation methods are called only if the qualification flagattribute of the calculation code is set to 1.

Any commands used as a CalculationCodeQualify calculation method mustimplement the CalculationCodeQualifyCmd interface. For more information on theCalculationCodeQualifyCmd interface, see the API documentation in the onlineinformation.

The CalculationCodeQualifyCmdImpl command is provided with WebSphereCommerce and implements the CalculationCodeQualifyCmd interface.


CalculationCodeQualifyCmdImplThis is the default implementation of the CalculationCodeQualify command.

This command returns OrderItems with a customer in one of the member groupsassociated with the calculation code and recognized by the store. If the customer isnot in any of the member groups associated with the calculation code, thiscommand returns null.

Calculation codes are associated with member groups in the CALCODEMGPdatabase table and member groups are recognized by stores in the STOREMBRGPdatabase table.

CalculationCodeCalculate calculation methodsCalculationCodeCalculate calculation methods calculate a monetary amount foreach OrderItem when given a calculation code and a group of OrderItems.

If a CalculationCodeCalculate calculation method is provided with a list of taxcategories in addition to the calculation code and group of OrderItems, monetaryamounts for each tax category are calculated for each OrderItem in the group ofOrderItems.

Any commands used as a CalculationCodeCalculate calculation method mustimplement the CalculationCodeCalculateCmd interface. For more information onthe CalculationCodeCalculateCmd interface, see the API documentation in theonline information.

The CalculationCodeCalculateCmdImpl command is provided with WebSphereCommerce and implements the CalculationCodeCalculateCmd interface.

CalculationCodeCalculateCmdImplThis is the default implementation of the CalculationCodeCalculate command.

Give a calculation code, a group of OrderItems, and an optional list of taxcategories, this command does the following:1. Calls a CalculationRuleCombine calculation method to determine the list of

calculation rules and the OrderItems associated with the calculation rules. TheCalculationRuleCombine method returns a list of calculation rules, and for eachrule returned, a list of associated OrderItems and a calculated monetaryamount for each associated OrderItem. The monetary amounts are the result ofevaluating the calculation rule.

2. Adds the monetary amounts for each OrderItem to calculate the total monetaryamount for each OrderItem. If these calculations are being performed for a taxcalculation usage, the monetary amounts for each tax category are also addedto arrive at a total monetary amount for each tax category for each OrderItem.

Calculation rules and the associated calculation methods are covered in Chapter 5,Calculation rules on page 35.

CalculationCodeApply calculation methodsThe CalculationCodeApply calculation method applies the calculated monetaryamounts to the OrderItems. These amounts are then available to be used in latercalculations.


Any commands used as a CalculationCodeApply calculation method mustimplement the CalculationCodeApplyCmd interface. For more information on theCalculationCodeQualifyCmd interface, see the API documentation in the onlineinformation.

The following commands implementing the CalculationCodeApplyCmd interfaceare provided with WebSphere Commerce:v DiscountCalculationCodeApplyCmdImplv ShippingCalculationCodeApplyCmdImplv SalesTaxCalculationCodeApplyCmdImplv ShippingTaxCalculationCodeApplyCmdImpl

DiscountCalculationCodeApplyCmdImplThis command implements the DiscountCalculationCodeApplyCmd interface thatextends the CalculationCodeApplyCmd interface.

This command creates an OrderAdjustment object for the Order and creates anOrderItemAdjustment object for each of the OrderItems in the list using thespecified monetary amounts. If the calculation code producing the monetaryamounts is flagged as tax exempt, the OrderItemAdjustment objects are alsoflagged as tax exempt.

SalesTaxCalculationCodeApplyCmdImplThis command implements the SalesTaxCalculationCodeApplyCmd interface thatextends the CalculationCodeApplyCmd interface. It also extends the base classTaxCalculationCodeApplyCmdImpl.

This command adds the monetary amounts for each sales tax category to the taxesfor the specified OrderItems.

ShippingCalculationCodeApplyCmdImplThis command implements the ShippingCalculationCodeApplyCmd interface thatextends the CalculationCodeApplyCmd interface.

This command adds the monetary amounts for the OrderItems to the shippingcharges for the order.

ShippingTaxCalculationCodeApplyCmdImplThis command implements the ShippingTaxCalculationCodeApplyCmd interfacethat extends the CalculationCodeApplyCmd interface. It also extends the base classTaxCalculationCodeApplyCmdImpl.

This command adds the monetary amounts for each shipping tax category to thetaxes for the specified OrderItems.

How calculation codes workCalculation code calculation methods are called from an ApplyCalculationUsagecalculation method. The ApplyCalculationUsage calculation method does thefollowing:1. The ApplyCalculationUsage calculation method calls a

CalculationCodeCombine calculation method. The CalculationCodeCombinecalculation method returns a list. Each item in the returned list consists of acalculation code and the OrderItems in the order to which the calculation codeapplies.


2. The ApplyCalculationUsage calculation method calls aCalculationCodeCalculate calculation method for each OrderItem in the listreturned by the CalculationCodeCombine calculation method.If the CalculationCodeCalculate calculation method needs calculation rules todetermine a monetary amount for each OrderItem in the list, theCalculationCodeCalculate calculation method calls a CalculationRuleCombinecalculation method to evaluate the calculation rules and to determine whichcalculation rules should be applied to which of the OrderItems. For adescription of calculation rules and associated calculation methods, seeChapter 5, Calculation rules on page 35.The CalculationCodeCalculate calculation method returns a list. Each item inthe list consists of an OrderItem and the monetary amount associated with theOrderItem for the calculation usage. For tax calculation methods, there may bemultiple monetary amounts for different tax categories that apply to theOrderItem. In this case, the tax categories are returned as part of the list aswell.

3. The ApplyCalculationUsage calculation method calls a CalculationCodeApplycalculation method for each calculation code and group of OrderItems.


Chapter 5. Calculation rulesThe WebSphere Commerce calculation framework separates the object thatindicates the calculation to be performed for an OrderItem (calculation code) fromthe object or objects responsible for doing the calculation. The object responsiblefor the calculation of the monetary amount associated with an OrderItem is calleda calculation rule.

Separating the calculation rule from the calculation code offers more flexibility andeasier customization than having the calculation code perform calculations directly.By separating calculation rules from calculation codes, one calculation code canhave many calculation rules. These multiple calculation rules can be combined,given an order of precedence, and restricted to members of specific membergroups. Calculation rules used for shipping or tax calculations can also berestricted by jurisdictions.

For example, if you have a store that ships products to a number of jurisdictions inwhich you must collect sales tax and there are various different sales taxes in eachjurisdiction, you would do the following: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 calculationrule must be associated with the following:v A tax categoryv A tax jurisdiction.v The sales tax calculation code

The sales tax calculation code calculates amounts for all tax categories, by havingseveral calculation rules, one for each tax category. A calculation rule calculates anamount for a particular tax category.

If you want your store to ship products into a new jurisdiction in which you mustcollect sales taxes, you do not have to create a new calculation code and attach itto the OrderItem. You can create new calculation rules and associate them with theappropriate tax categories, the new tax jurisdiction, and the existing calculationcode.

The properties of calculation rules are defined in the CALRULE database table. TheCALRULE database table and other database tables that affect the way calculationrules are used are discussed in the next section.

Database tables for calculation rulesInformation about calculation rules is provided in the following WebSphereCommerce database tables:

CALRULEThis is the main database table that defines calculation rules.

CALRULEMGPThis database table associates a calculation rule with a member group. The


association of a member group with a calculation rule permits therestriction of a calculation rule to certain member groups.

SHPJCRULEThis database table can be used by the ShippingCalculationRuleQualifycalculation method to choose a calculation rule based on the shippingmode and fulfillment center when the shipping address matches one of theshipping jurisdictions in a particular shipping jurisdiction group.

STENCALUSGThis database table specifies the CalculationRuleCombine calculationmethod subclass that determines how multiple calculation rules for anOrderItem are combined.

TAXJCRULEThis table can be used by a TaxCalculationRuleQualify calculation methodto choose a calculation rule when shipping from a fulfillment center to ashipping address that matches one of the tax jurisdictions in a particulartax jurisdiction group.

The following sections discuss key calculation rule attributes that are stored insome of the database tables. For details on all the columns of the calculation ruledatabase tables, refer to the database schema documentation in the onlineinformation. All of the attributes discussed in the following section are requiredunless they are marked optional.

CALRULE database tableThe CALRULE database table stores the following information about calculationrules:

Calculation rule ID (CALRULE_ID)This is a unique identifier for the calculation rule, assigned by WebSphereCommerce.

Identifying number (IDENTIFIER)This is an integer number that, along with the calculation code ID,uniquely identifies this calculation rule. The default value is 1.

Calculation code ID (CALCODE_ID)This is the calculation code to which the calculation rule belongs. Acalculation rule can only belong to one calculation code.

Start and end dates (STARTDATE, ENDDATE) (optional)These optional attributes set the time range for which a calculation rule iseffective. The start and end dates have the following effects on acalculation rule:v If a calculation rule is called on a date outside of the defined range, the

rule will be ignored.v If only the start date is set, the rule is ignored until the start date.v If only the end date is set, the rule is effective until the end date.v If neither date is set, the rule is always effective.

Combination (COMBINATION)The combination attribute of a calculation rule defines how the resultsfrom a calculation rule are combined with the results from other rules foran OrderItem. A calculation rule has one of the following combinationattributes:


inAdditionToThe results from a calculation rule with an inAdditionTocombination attribute can be combined with the results from anyother rules.

notInCombinationWithThe results from a calculation rule with a notInCombinationWithcombination attribute can only be combined with results from ruleswith an inAdditionTo combination attribute. The results cannot becombined with results from an inCombinationWith rule.

inCombinationWithThe results from a calculation rule with an InCombinationWithcombination attribute can be only combined with results from ruleswith either an inAdditionTo combination attribute or anInCombinationWith combination attribute. The results cannot becombined with results from a notInCombinationWith rule.

Qualification flag (FLAGS)This attribute contains a bit flag that is used to indicate whether or not theCalculationRuleQualify calculation method for this calculation rule shouldbe called by the CalculationRuleCombine calculation method. If the bit flagis 1, the CalculationRuleQualify calculation method is called to determinefor which OrderItems the rule qualifies. If the bit flag is 0, the method isnot called, and the rule always qualifies for all OrderItems. The defaultsetting for this attribute is 0.

Sequence (SEQUENCE)Sequence is a number used to specify the order in which calculation rulesfor the same calculation codes are processed. Calculation rules areprocessed from lowest sequence number to highest sequence number. Inthe event that two calculation rules have the same sequence number, thecalculation rule with the lower calculation rule ID is processed first.

Tax category ID (TAXCGRY_ID) (optional)The tax category ID specifies the tax category for which this calculationrule is effective.

CalculationRuleQualify calculation method ID (CALMETHOD_ID_QFY)This is the identifier of the calculation method, as defined in theCALMETHOD database table, that determines to which OrderItems thiscalculation rule applies.

CalculationRuleCalculate calculation method ID (CALMETHOD_ID)This is the identifier of the calculation method, as defined in theCALMETHOD database table, that calculates a monetary result for a set ofOrderItems.

SHPJCRULE database tableThe SHPJCRULE database table defines relationships between calculation rules,fulfillment centers, shipping jurisdiction groups and shipping modes. Theserelationships can be used by shipping CalculationRuleQualify calculation methodsto choose which calculation rule to use. The decision is based on the shippingmode and fulfillment center when shipping address matches one of the shippingjurisdictions in a shipping jurisdiction group.

The SHPJCRULE database table contains the following information used whenqualifying calculation rules:

Chapter 5. Calculation rules 37

Calculation rule ID (CALRULE_ID)This is the identifier of the calculation rule to which this relationshipapplies.

Fulfillment center ID (FFMCENTER_ID) (optional)This is the identifier of the fulfillment center to which this relationshipapplies. If this is null, then this relationship applies to all fulfillmentcenters.

Shipping jurisdiction group ID (JURSTGROUP_ID) (optional)This is the identifier of the shipping jurisdiction group to which thisrelationship applies. If this is null, then this relationship applies to allshipping jurisdiction groups.

Shipping mode ID (SHIPMODE_ID) (optional)This is the identifier of the shipping mode to which this relationshipapplies. If this is null, then this relationship applies to all shipping modes.

Precedence (PRECEDENCE)This attribute is used by a CalculationRuleQualify calculation method toqualify a calculation rule when the shipping address of an OrderItem fallsinto more than one shipping jurisdiction group for the same fulfillmentcenter and shipping mode associated with a calculation rule. When theshipping address of the OrderItem falls into more than one shippingjurisdiction group, for the same fulfillment center and shipping mode, thecalculation rule with the highest precedence value qualifies. If theprecedence values for multiple calculations rules are the same, then all ofthe calculation rules sharing the same highest precedence value areapplied.

STENCALUSG database tableThe STENCALUSG database table contains the following information aboutcalculation rules:

CalculationRuleCombine calculation method (ACTRC_CALMETHOD_ID)(optional)

This is the identifier of the CalculationRuleCombine calculation method. Ifa CalculationRuleCombine calculation method is not specified for a store,then the CalculationRuleCombine calculation method defined for the storegroup is used.

The STENCALUSG database table also contains information about calculationusages. Calculation usages are covered in Chapter 3, Calculation usages onpage 13.

TAXJCRULE database tableThe TAXJCRULE database table defines the relationships between calculation rules,fulfillment centers and tax jurisdiction groups. These relationships can be used bysales tax and shipping tax CalculationRuleQualify calculation methods to choosewhich calculation rule to use. The decision is based on the fulfillment center whenshipping address matches one of the tax jurisdictions in a tax jurisdiction group.

The TAXJCRULE database table contains the following information used whenqualifying calculation rules:

Calculation rule ID (CALRULE_ID)This is the identifier of the calculation rule to which this relationshipapplies.


Fulfillment center ID (FFMCENTER_ID) (optional)This is the identifier of the fulfillment center to which this relationshipapplies. If this is null, then this relationship applies to all fulfillmentcenters.

Tax jurisdiction group ID (JURSTGROUP_ID) (optional)This is the identifier of the tax jurisdiction group to which this relationshipapplies. If this is null, then this relationship applies to all tax jurisdictiongroups.

Precedence (PRECEDENCE)This attribute is used by a CalculationRuleQualify calculation method toqualify a calculation rule when the shipping address of an OrderItem fallsinto more than one tax jurisdiction group for the same fulfillment centerassociated with a calculation rule. When the shipping address of theOrderItem falls into more than one tax jurisdiction group, for the samefulfillment center, the calculation rule with the highest precedence valuequalifies. If the precedence values for multiple calculations rules are thesame, then all of the calculation rules sharing the same highest precedencevalue are applied.

Calculation rule data model diagramsThe following data model diagrams provide illustrations of the relationshipsbetween the database tables used to define generic calculation rules, discountcalculation rules, shipping calculation rules, and tax calculation rules.

Figure 9. Generic calculation rule data model diagram

Chapter 5. Calculation rules 39

Figure 10. Discount calculation rule data model diagram

Figure 11. Shipping calculation rule data model diagram

Figure 12. Tax calculation rule data model diagram


For information on the conventions used in these diagrams, seeAppendix C, Data model legend on page 109.

For details on the database tables in the diagrams refer to the database schemadocumentation in the online information.

Calculation methods for calculation rulesThere are three calculation method subclasses associated with calculation rules:v CalculationRuleCombinev CalculationRuleQualifyv CalculationRuleCalculateThis section discusses these calculation method subclasses and the defaultimplementations provided with WebSphere Commerce. Additional information onthe interfaces and commands that implement the calculation method subclassescan be found in the API documentation in the online information.

CalculationRuleCombine calculation methodThe CalculationRuleCombine calculation method determines which calculationrules are used to calculate monetary amounts for the list of OrderItems passed tothe CalculationRuleCombine calculation method by the CalculationCodeCalculatecalculation method.

The CalculationRuleCombine method returns a list where each item in the listconsists of the following:v A calculation rulev A list of OrderItems to which the calculation rule appliesv A list of monetary amounts corresponding to each OrderItem

For tax calculations, the monetary amounts corresponding to each OrderItem maybe separated into the amount for each tax category applicable to the OrderItem.

Any commands used as CalculationRuleCombine calculation methods mustimplement the CalculationRuleCombineCmd interface. For more inform

Documents

Calculation Framework Guide