Calculation usages

The WebSphere Commerce calculation framework is a generic framework for calculations. When implementing a calculation using this framework, first define the type of calculation to be performed. The types of calculations you can perform are called calculation usages. Calculation usages are assigned a calculation usage code.

WebSphere Commerce provides the following predefined calculation usages:

Predefined calculation usages
Calculation usage Calculation usage code
Discount -1
Shipping -2
Sales tax -3
Shipping tax -4
Coupon -5
Surcharge -6
Shipping Adjustment -7

WebSphere Commerce performs all calculations for one calculation usage at a time. The order of calculation usages is stored in the SEQUENCE column of the STENCALUSG database table. The entries in this table are initially populated with information from the language-independent bootstrap file: wcs.bootstrap.xml.

The default order in which calculation usages are processed, as defined in wcs.bootstrap.xml, is as follows:

  1. Coupon
  2. Discount
  3. Shipping
  4. Sales tax
  5. Shipping tax
  6. Surcharge
  7. Shipping adjustment

Note: Surcharge should always be the final process. Shipping adjustment calculation usage should always be processed after the shipping calculation usage.

Database tables for calculation usage

Information about calculation usages is stored in the following database tables:

CALUSAGE

This table contains a unique identifier for each calculation usage and a description of the calculation usage. Values in this table are defined in the language-dependent bootstrap file.

STENCALUSG

This table defines the high-level behavior of a calculation usage for a store or group of stores. If the implementation for a store is not defined, the implementation for the store group is used. If different implementations are defined for the store and the store group, the implementation for the store is used. This database table is initially populated from the language-independent bootstrap file.

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

Calculation usage data model diagram

The following data model diagram illustrates the relationships between the database tables that are used to define calculation usages.

 

Calculation methods for calculation usages

There are four calculation method subclasses associated with calculation usages:

InitializeCalculationUsage

These calculation methods are called by the OrderPrepare command for each calculation usage that you specify in the USAGEFLAGS column of the STENCALUSG database table prior to calling the ApplyCalculationUsage calculation method.

ApplyCalculationUsage

These calculation methods are called by the OrderPrepard command for each calculation usage that you specify in the USAGEFLAGS column of the STENCALUSG database table. These methods may also be called from data beans or other task commands to calculate amounts for items not necessarily in an Order. For example, the GetReturnTaxes task command calls the ApplyCalculationUsage method for the sales tax calculation usage.

SummarizeCalculationUsage

These calculation methods are called by the OrderPrepare command for each calculation usage that you specify in the USAGEFLAGS column of the STENCALUSG database table after calling the ApplyCalculationUsage calculation methods. SummarizeCalculationUsage calculation methods summarize the calculated amounts. For example, the SummarizeCalculationUsage method for the sales tax calculation usage populates the SUBORDTAX database table and the SUBORDERS.TOTALTAX columns. The SUBORDTAX database table contains tax information for the OrderItems in a SubOrder.

FinalizeCalculationUsage

These calculation methods are called by the ProcessOrder task command for each calculation usage that you specify in the USAGEFLAGS column of the STENCALUSG database table. For example, the FinalizeCalculationUsage method for the coupon calculation usage marks the coupons that are applied to an order to prevent the coupons from being applied to a different order.

The following section discusses these calculation method subclasses and the default implementations that are provided with WebSphere Commerce.

InitializeCalculationUsage calculation methods

InitializeCalculationUsage calculation methods do any processing that is required before monetary amounts for OrderItems are calculated. For example, they can remove previously calculated values from the OrderItems in the order.

Any commands that will be used as an InitializeCalculationUsage calculation method subclass must implement the InitializeCalculationUsageCmd interface.

The following InitializeCalculationUsage calculation methods are provided with WebSphere Commerce:

InitializeAdjustmentCmdImpl

This command implements the InitializeAdjustmentCmd interface that extends the InitializeCalculationUsageCmd interface.

This is the common calculation usage initialization method for discount, surcharge, and shipping adjustment calculation usages.

InitializeCouponUsageCmdImpl

This command implements the InitializeCouponUsageCmd interface that extends the InitializeCalculationUsageCmd interface.

This command is used for coupons.

InitializeSalesTaxCmdImpl

This command implements the SalesTaxCmd interface that extends the InitializeCalculationUsageCmd interface.

This command initializes values for sales tax calculations.

InitializeShippingCmdImpl

This command implements the InitializeShippingCmd interface that extends the InitializeCalculationUsageCmd interface.

This command initializes values for shipping charge calculations.

InitializeShippingTaxCmdImpl

This command implements the InitializeShippingTaxCmd interface that extends the InitializeCalculationUsageCmd interface.

This command initializes values for shipping tax calculations.

ApplyCalculationUsage calculation methods

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

For display purposes, ApplyCalculationUsage calculation methods are called by data beans to calculate monetary amounts. For example, taxes for a product can be displayed as part of the product's display page. The data bean that calls the ApplyCalculationUsage calculation method must perform any initialization that would normally be performed by the InitializeCalculationUsage calculation method for the calculation usage that is processed for the data bean. The data bean does not have access to the InitializeCalculationUsage, SummarizeCalculationUsage, or FinalizeCalculationUsage calculation methods.

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

Any commands that will be used as an ApplyCalculationUsage calculation method subclass must implement the ApplyCalculationUsageCmd interface.

The following ApplyCalculationUsage calculation methods are provided with WebSphere Commerce:

ApplyCalculationUsageCmdImpl

This is the default implementation of the ApplyCalculationUsage command. It makes the following calls:

  1. Call the CalculationCodeCombine calculation method to get a list of calculation codes. For each CalculationCode in the list, CalculationCodeCombine also provides a list of the OrderItems to be included in the calculation.
  2. For each calculation code in the list, ApplyCalculationUsageCmdImpl makes the following calls:
    1. Call the CalculationCodeCalculate calculation method, passing it the associated list of OrderItems. The CalculationCodeCalculate calculation method returns a list of calculated monetary amounts for each OrderItem. The monetary amounts can be categorized by tax category.
    2. Call the CalculationCodeApply calculation method, passing it the calculation code, a list of OrderItems, and the monetary amount associated with each OrderItem.

ApplyCalculationUsageTIKCmdImpl

This command implements the ApplyCalculationUsageTIKCmd interface, which extends the ApplyCalculationUsageCmd interface.

The ApplyCalculationUsageTIKCmd interface and the ApplyCalculationUsageTIKCmdImpl command are provided as an example to invoke a set of interfaces that are supplied in the Tax Integration Interface Kit. If WebSphere Commerce has been configured to use this interface, the OrderPrepare command will call ApplyCalculationUsageTIKCmd which in turn invokes the TaxIntegrationOrderCmd task command that is provided in the Tax Integration Interface Kit.

ApplyCouponUsageCmdImpl

This command implements the ApplyCouponUsageCmd interface that extends the ApplyCalculationUsageCmd interface.

This command adds the discount from a coupon promotion to the adjustments in the ORDERS and ORDERITEMS database tables. The command is invoked when a customer 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 and CPITMAP database table. CheckValidityTaskCmd checks the coupons for expiry. If they are not expired, CheckApplicabilityTaskCmd checks them for applicability. If they are applicable, CalculateDiscountAmountCmd incorporates the discount amount in the current order.

ApplyShippingCmdImpl

This command is the default implementation of the ApplyShippingCmd interface, which extends the ApplyCalculationUsageCmd interface. This command governs the adjustments, promotions, shipping and contract based adjustments and IBM Sales Center (CSR)-based adjustments. Promotions are based on base charges. Contracts are based on base charges plus promotion, so designate them as cumulative or non-cumulative.

The default precedence strategy is as follows:

  1. Contract based shipping adjustments
  2. Promotions
  3. Service representative adjustments

A non-cumulative adjustment applies directly to the base charge; a cumulative discount applies to the result of a previous adjustment. For example: An order has a $10 base shipping charge, a 10% contract adjustment, and a 10% promotional adjustment. The application is cumulative. The contracts adjustment is applied first with a $9 cost (with a $1 discount), then the 10% promotion is applied to the discounted amount of $9 (and will be a .90 discount). So the total would be $8.10.

In a non-cumulative scenario the first adjustment will be $9 cost (with a $1 discount) as in the first case, but when the 10% promotion is applied this time it is applied on the original amount of $10. So this adjustment has a $1 discount. This brings the shipping total to $8 for the order.

By default, the application of adjustments should be as follows:

  1. Contracts - non-cumulative
  2. Promotions - non-cumulative
  3. Service representative - cumulative

This is a version of the ApplyCalculationUsageCmdImpl command for shipping.

SummarizeCalculationUsage calculation methods

This calculation method subclass summarizes the results of calculations for display purposes.

Any commands that will be used as a subclass of SummarizeCalculationUsage must implement the SummarizeCalculationUsageCmd interface.

The following SummarizeCalculationUsage calculation methods are provided with WebSphere Commerce:

SummarizeAdjustmentCmdImpl

This command implements the SummarizeAdjustmentCmd interface that extends the SummarizeCalculationUsageCmd interface.

This command is used to summarize discount calculations. This is also the common summarization method for calculation usages for discounts, surcharges, and shipping adjustments.

SummarizeCouponUsageCmdImpl

This command implements the SummarizeCouponUsageCmd interface that extends the SummarizeCalculationUsageCmd interface.

This command is used to summarize coupon calculations.

SummarizeSalesTaxCmdImpl

This command implements the SummarizeSalesTaxCmd interface that extends the SummarizeCalculationUsageCmd interface.

This command is used to summarize sales tax calculations.

SummarizeShippingCmdImpl

This command implements the SummarizeShippingCmd interface that extends the SummarizeCalculationUsageCmd interface.

This command is used to summarize shipping charge calculations.

SummarizeShippingTaxCmdImpl

This command implements the SummarizeShippingTaxCmd interface that extends the SummarizeCalculationUsageCmd interface.

This command is used to summarize shipping tax calculations.

FinalizeCalculationUsage calculation methods

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

Any commands that are used as a subclass of FinalizeCalculationUsage must implement the FinalizeCalculationUsageCmd interface.

The FinalizeCouponUsageCmdImpl is the only FinalizeCalculationUsage calculation method that is provided with WebSphere Commerce.

FinalizeCouponUsageCmdImpl

This command implements the FinalizeCouponUsageCmd interface that extends the FinalizeCalculationUsageCmd interface.

The FinalizeCouponUsageCmdImpl command marks coupons that are used in the current order, to prevent the coupons from being used in other orders.

How calculation usages work

Calculation usages are invoked by the OrderPrepare command. This command creates a list of OrderItems for which monetary amounts will be calculated. The applicable calculation usages for the store or store group to which the order belongs are processed according to the sequence that you define for them in the STENCALUSG database table.

The OrderPrepare command processes the calculation usages as follows:

  1. All calculation usages are initialized using the InitializeCalculationUsage calculation methods referenced in the CALMETHOD_ID_INI column of the STENCALUSG database table.
  2. All calculation usages are applied using the ApplyCalculationUsage calculation methods referenced in the CALMETHOD_ID_APP column of the STENCALUSG database table. For more information about how calculation methods are applied, see How calculation usages are applied.
  3. All calculation usages are summarized using the SummarizeCalculationUsage calculation methods referenced in the CALMETHOD_ID_SUM column of the STENCALUSG database table.

After the OrderPrepare controller command completes, the OrderProcess controller command is called. The OrderProcess controller command finalizes all calculation usages by calling the FinalizeCalculationUsage calculation methods referenced in the CALMETHOD_ID_FIN column of the STENCALUSG database table entry for each calculation usage.

How calculation usages are applied

When a calculation usage is applied, the following steps occur:

  1. The ApplyCalculationUsage calculation method calls a CalculationCodeCombine calculation method. The CalculationCodeCombine calculation method returns a list. Each item in the list consists of a calculation code and the OrderItems in the order to which the calculation code applies.
  2. The ApplyCalculationUsage calculation method calls a CalculationCodeCalculate calculation method for each item in the list that is returned by CalculationCodeCombine. CalculationCodeCalculate returns a list. Each item in the list consists of each OrderItem and the monetary amount associated with the OrderItem for the calculation usage. For tax calculation methods, there might be multiple monetary amounts for different taxes that apply to the OrderItem. In this case, the tax categories are returned as part of the list as well.
  3. The ApplyCalculationUsage calculation method calls a CalculationCodeApply calculation method for each group of OrderItems.

Related concepts

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