BEA Logo BEA WebLogic Commerce Server Release 3.1.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

 

   WebLogic Commerce Server Doc Home   |   Order Processing Package   |   Previous Topic   |   Next Topic   |   Contents   |   Index

Taxation Services

 

The Taxation Services provided in the Order Processing package are used to calculate the taxes associated with your customer's order. They enable you to determine the accurate tax rates imposed on the sale or use of each item at the state, country, city, and district levels by interfacing with TAXWARE International, Inc. products. This topic describes the Taxation Service in detail.

This topic includes the following sections:

 


JavaServer Pages (JSPs)

The Order Processing package's Taxation Services consist of one JavaServer Page (JSP) that you can use as is, or customize to meet your business requirements. This section describes this page in detail.

selecttaxaddress.jsp Template

In cases where a customer provides a shipping address that does not resolve to a unique GeoCode (a TAXWARE code used to determine taxes based on jurisdiction), the selecttaxaddress.jsp template (shown in Figure 5-1) allows the customer to select from a list of more specific shipping addresses.

Sample Browser View

Figure 5-1 shows an annotated version of the selecttaxaddress.jsp template. The dashed lines and numbers in the diagram are not part of the template; they are referenced in the explanation that follows the screen shot.

Figure 5-1 Annotated selecttaxaddress.jsp Template

The numbers in the following list refer to the numbered regions in the figure:

  1. The page header (top banner) is created from an import of the innerheader.jsp template. This is standard across many of the JSP templates provided by WebLogic Commerce Server. The import call is:

    <%@ include file="/commerce/includes/innerheader.jsp" %>

  2. Region 2 uses a combination of WebLogic Server and Pipeline JSP tags to obtain and display a list of more detailed addresses, from which the customer can select.

  3. The selecttaxaddress.jsp template's content in region 3 contains the included innerfooter.jsp template. The include call in selecttaxaddress.jsp is:

    <%@ include file="/commerce/includes/innerfooter.jsp" %>

    innerfooter.jsp consists of the horizontal footer at the bottom of the page, plus the right-side vertical column that describes (for the benefit of you and your development team) the name of the current template and links to its About information. In the innerfooter.jsp file, the right-side vertical column is an include file:

    <%@ include file="/commerce/includes/rightside.jsp" %> 

Location in the WebLogic Commerce Server Directory Structure

You can find the selecttaxaddress.jsp template file at the following location, where WL_COMMERCE_HOME is the directory in which you installed WebLogic Commerce Server:

%WL_COMMERCE_HOME%\server\webapps\wlcs\commerce\order\
selecttaxaddress.jsp
(Windows)
$WL_COMMERCE_HOME/server/webapps/wlcs/commerce/order/
selecttaxaddress.jsp
(UNIX)

Tag Library Imports

The selecttaxaddress.jsp template uses existing WebLogic Server and Pipeline JSP tags. Therefore, the template includes the following JSP tag libraries:

<%@ taglib uri="weblogic.tld" prefix="wl" %>
<%@ taglib uri="pipeline.tld" prefix="pipeline" %>

Note: For more information on the WebLogic Server JSP tags, see "JSP Tag Reference" in the BEA WebLogic Personalization Server documentation. For more information about the Pipeline JSP tags, see BEA WebLogic Commerce Server Webflow and Pipeline Management.

These files reside in the following directory for the WebLogic Commerce Server Web application:

%WL_COMMERCE_HOME%\server\webapps\wlcs\WEB-INF (Windows)
$WL_COMMERCE_HOME/server/webapps/wlcs/WEB-INF (UNIX)

Java Package Imports

The selecttaxaddress.jsp template uses Java classes in the following packages and therefore includes these import statements:

<%@ page import="java.util.*" %>
<%@ page import="java.text.*" %>
<%@ page import="com.beasys.commerce.foundation.pipeline.*" %>
<%@ page import="com.beasys.commerce.axiom.contact.*" %>
<%@ page import="com.beasys.commerce.ebusiness.shipping.*" %>
<%@ page import="com.beasys.commerce.webflow.*" %>

Location in Default Webflow

Note: The selecttaxaddress.jsp template is only displayed if the customer provides a shipping address that is not specific enough. Otherwise, it is bypassed.

The page prior to the selecttaxaddress.jsp template in the default Webflow is the page where the customer selects a shipping address (selectaddress.jsp). After the customer has selected an address from the list of choices presented on selecttaxaddress.jsp, they proceed to the payment information page (payment.jsp).

Note: For more information about the default Webflow, see Overview of the Order Processing Package.

Included JSP Templates

The following JSP templates are included in the selecttaxaddress.jsp template:

Events

The selecttaxaddress.jsp template presents a customer with two buttons, each of which is considered an event. These events trigger a particular response in the default Webflow that allows customers to continue. While this response can be to load another JSP, it is usually the case that an input processor or Pipeline is invoked first. Table 5-1 provides information about these events and the business logic they invoke.

Table 5-1 selecttaxaddress.jsp Events

Event

Webflow Response(s)

button(use)

UpdateTaxShippingAddressIP

Dynamic Data Display

The only purpose of the selecttaxaddress.jsp template is to display variations on a shipping address that the customer has already entered. This is accomplished on selecttaxaddress.jsp using a combination of WebLogic Server and Pipeline JSP tags, and accessor methods/attributes.

First, the getPipelineProperty JSP tag retrieves the VERIZIP_SHIPPING_ADDRESSES attribute from the Pipeline session. Table 5-2 shows more detailed information about this attribute.

Table 5-2 selecttaxaddress.jsp Pipeline Session Attributes

Attribute

Type

Description

PipelineSessionConstants.

VERIZIP_SHIPPING_ADDRESSES

List of com.beasys.commerce.axiom.contact.Address

List of the possibilities for the more detailed shipping address.

Listing 5-1 illustrates how this attribute is retrieved from the Pipeline session.

Listing 5-1 Retrieving the Address Selection Attribute


<pipeline:getPipelineProperty 
propertyName="<%=PipelineSessionConstants.VERAZIP_SHIPPING_ADDRESSES%>"
returnName="addressesObject" returnType="java.lang.Object"/>


Note: For more information on the getPipelineProperty JSP tag, see BEA WebLogic Commerce Server Webflow and Pipeline Management.

The data stored within this attribute is then accessed by using accessor methods/attributes within Java scriptlets. Table 5-3 provides more detailed information on these methods/attributes for Address.

Table 5-3 Address Accessor Methods/Attributes

Method/Attribute

Description

getStreet1()

The first line of the street in the shipping address.

getStreet2()

The second line of the street in the shipping address.

getCity()

The city in the shipping address.

getCounty()

The county in the shipping address.

getState()

The state in the shipping address.

getPostalCode()

The zip/postal code in the shipping address.

getCountry()

The country in the shipping address.

Since there are multiple addresses, you must also use the WebLogic Server JSP tag to iterate through each of the addresses, as shown in Listing 5-2.

Listing 5-2 Using <wl> Tags and Accessor Methods in selecttaxaddress.jsp


<wl:repeat set="<%=addressesObject%>" id="address" type="Address" count="100">

<table>
<tr>
<td><b>County</b></td>
<td><%=address.getCounty()%><br>
<%=address.getCity()%><br>
<%=address.getState()%><br>
<%=address.getPostalCode()%><br>
<%=address.getCountry()%>
</td>
</tr>
</table>

</wl:repeat>


Note: For more information on the WebLogic Server JSP tags, see "JSP Tag Reference" in the BEA WebLogic Personalization Server documentation.

Form Field Specification

Besides allowing a customer to select a more detailed shipping address, the selecttaxaddress.jsp template also passes hidden information to the Webflow. The form fields used in the selecttaxaddress.jsp template, and a description for each of these form fields are listed in Table 5-4.

Table 5-4 selectataxddress.jsp Form Fields

Parameter Name

Type

Description

"event"

Hidden

Indicates which event has been triggered. It is used by the Webflow to determine what happens next.

"origin"

Hidden

The name of the current page (selecttaxaddress.jsp), used by the Webflow.

PipelineSessionConstants.
TAX_SHIPPING_ADDRESS

Hidden

Identifies the more specific address selected by the customer.

Note: Parameters that are literals in the JSP code are shown in quotes, while non-literals will require JSP scriptlet syntax (such as
<%= PipelineSessionConstants.TAX_SHIPPING_ADDRESS %>) for use in the JSP.

 


Input Processors

This section provides a brief description of each input processor associated with the Taxation Services JSP template(s).

DecideShippingAddressPageIP

Class Name

com.beasys.commerce.ebusiness.tax.webflow.

DecideShippingAddressPageIP

Description

Makes the decision about whether to display selecttaxaddress.jsp based on the number of address variations returned from the TAXWARE VERAZIP service. If a single address is found, this input processor updates the shipping address, returns successfully, and allows the Webflow to proceed to payment.jsp. Otherwise, this input processor redirects the Webflow to selecttaxaddress.jsp.

Required HTTPServletRequest Parameters

None

Required Pipeline
Session Attributes

PipelineSessionConstants.SHIPPING_ADDRESS

PipelineSessionConstants.VERIZIP_SHIPPING_ADDRESSES

Updated Pipeline
Session Attributes

PipelineSessionConstants.SHIPPING_ADDRESS (in the case of a single address)

Removed Pipeline
Session Attributes

None

Validation

None

Exceptions

MultipleAddressFoundException, thrown if the VERAZIP service returns more than one address.

UpdateShippingAddressIP

Class Name

com.beasys.commerce.ebusiness.shipping.webflow.

UpdateShippingAddressIP

Description

Updates the shipping address attribute in the Pipeline session based on the tax address the customer selects.

Required HTTPServletRequest Parameters

HTTPRequestConstants.TAX_SHIPPING_ADDRESS

Required Pipeline
Session Attributes

PipelineSessionConstants.SHIPPING_ADDRESS

PipelineSessionConstants.VERIZIP_SHIPPING_ADDRESSES

Updated Pipeline
Session Attributes

PipelineSessionConstants.SHIPPING_ADDRESS

Removed Pipeline
Session Attributes

None

Validation

None

Exceptions

None

 


Pipeline Components

This section provides a brief description of each Pipeline component associated with the Taxation Services JSP template(s).

Note: Some Pipeline components extend other, base Pipeline components. For more information on the base classes, see the Javadoc.

TaxCalculateLineLevelPC

Class Name

com.beasys.commerce.ebusiness.tax.pipeline. TaxCalculateLineLevelPC

Description

Calculates the tax and provides line-level information about the taxability of an item. This Pipeline component is used to display the tax information to the customer.

Required Pipeline
Session Attributes

PipelineSessionConstants.SHOPPING_CART

PipelineSessionConstants.SHIPPING_ADDRESS

Updated Pipeline
Session Attributes

PipelineSessionConstants.SHOPPING_CART

Removed Pipeline
Session Attributes

None

Type

Java class

JNDI Name

None

Exceptions

None

TaxCalculateAndCommitLineLevelPC

Class Name

com.beasys.commerce.ebusiness.tax.pipeline.

TaxCalculateAndCommitLineLevelPC

Description

Calculates the tax and provides line-level information about the taxability of an item. The results are logged to the TAXWARE audit file so that correct payment can be made to taxing jurisdictions, or to generate tax reports.

Required Pipeline
Session Attributes

PipelineSessionConstants.SHOPPING_CART

PipelineSessionConstants.SHIPPING_ADDRESS

Updated Pipeline
Session Attributes

PipelineSessionConstants.SHOPPING_CART

Removed Pipeline
Session Attributes

None

Type

Java class

JNDI Name

None

Exceptions

None

TaxVerifyShippingAddressPC

Class Name

com.beasys.commerce.ebusiness.tax.pipeline.

TaxVerifyShippingAddressPC

Description

Ensures that the shipping address is descriptive enough to properly calculate taxation for an order based on jurisdiction.

Required Pipeline
Session Attributes

PipelineSessionConstants.SHIPPING_ADDRESS

Updated Pipeline
Session Attributes

PipelineSessionConstants.VERAZIP_SHIPPING_ADDRESSES

Removed Pipeline
Session Attributes

None

Type

Java class

JNDI Name

None

Exceptions

TaxSystemException, thrown if processing could not occur due to system level problems (for example, some data files are missing or there is an installation problem in TAXWARE).

TaxUserException, thrown if processing could not occur due to invalid user input.

 


Integration with TAXWARE

To ensure that the Taxation Services properly determine taxes for the items in your product catalog, the BEA WebLogic Commerce Server product integrates with TAXWARE International Inc.'s commercial tax products. Specifically:

Important TAXWARE Considerations

The following are important factors regarding the BEA WebLogic Commerce Server product's integration with TAXWARE that should be considered prior to launching your e-business Web site:

TAXWARE Installation

TAXWARE International's SALES/USE, VERAZIP, and Universal Tax Link (UTL) systems are shipped within the BEA Weblogic Commerce Server product to provide out-of-the-box TAXWARE functionality. The Commerce Server's installation program will install these TAXWARE products along with the Commerce Server, and will also uninstall them upon uninstallation of the Commerce Server.

The versions of the TAXWARE products installed with the BEA WebLogic Commerce Server product are as follows:

Installation Directory Structure

The TAXWARE product files installed with the BEA WebLogic Commerce Server product are organized into particular directories based on the system platform. This section describes the directory structures for both the Windows and UNIX installations of the TAXWARE products.

Windows

All TAXWARE audit files, Java classes, DLLs, and preloaded data files needed for Win32 installation reside in subdirectories beneath WL_COMMERCE_HOME\eval\win32\Taxware, where WL_COMMERCE_HOME is the directory in which you installed WebLogic Commerce Server.

Table 5-5 lists the subdirectories where you would find these TAXWARE files.

Table 5-5 Location of TAXWARE Files

Subdirectory

Description

\audit

Contains audit files for all tax transactions.

\bin

Contains DLLs for SALES/USE, VERIZIP, and UTL, including avptax.dll, avpzip.dll, taxcommon.dll, and taxcommon0.dll.

\classes

Contains Java classes for UTL, including taxmain.class and taxcommon.class.

\data

Contains preloaded data files for SALES/USE and VERAZIP such as INDATA (which includes all run-time, test and parameter, tax master, product sequential, and update files) and OUTDATA (which includes all generated data files when tax data is loaded or updated).

\temp

Contains temporary files generated by TAXWARE while processing a transaction.

Additionally, the WL_COMMERCE_HOME\eval\win32\Taxware directory (where WL_COMMERCE_HOME is where you installed the WebLogic Commerce Server) contains the following two ini files:

UNIX

All TAXWARE audit files, Java classes, shared objects, and preloaded data files needed for UNIX installation reside in subdirectories beneath WL_COMMERCE_HOME\eval\solaris2\Taxware, where WL_COMMERCE_HOME is the directory in which you installed WebLogic Commerce Server.

Table 5-6 lists the subdirectories where you would find these TAXWARE files.

Table 5-6 Location of TAXWARE Files

Subdirectory

Description

\audit

Contains audit files for all tax transactions.

\classes

Contains UTL Java classes, including taxmain.class and taxcommon.class.

\data

Contains preloaded data files for SALES/USE and VERAZIP such as INDATA (which includes all run-time, test and parameter, tax master, product sequential, and update files) and OUTDATA (which includes all generated data files when tax data is loaded or updated).

\lib

Contains shared objects, including libsalesusetax.so, libstep.so, libtaxcommon.so, libtaxcommono.so, and libverazip.so.

\temp

Contains temporary files generated by TAXWARE while processing a transaction.

Testing the TAXWARE Installation

You can test the installation of the WebLogic Commerce Server-provided TAXWARE products on both Windows and UNIX platforms using some predefined test scripts. Refer to the appropriate section for details.

Windows

To run the test scripts in a Windows environment, follow these steps:

  1. From a DOS prompt, set up the home directory for WebLogic Commerce Server by typing: SET WL_COMMERCE_HOME=<directory_where_you_installed_
    WebLogic_Commerce_Server>
    .

  2. Navigate to the WL_COMMERCE_HOME\eval\win32\Taxware\bin directory, where WL_COMMERCE_HOME is the directory in which you installed WebLogic Commerce Server.

  3. To test the SALES/USE component of TAXWARE, type runsample.bat commonsu.in.

  4. To test the VERAZIP component of TAXWARE, type runsample.bat vzip.in. The result should be a long line that begins with: 0000010000.

  5. Check that output string has the expected completion code.

    Note: Refer to the TAXWARE SALES/USE and VERAZIP product documentation for more details about the output string fields and their values.

UNIX

To test installation of TAXWARE in a UNIX environment, follow these steps:

  1. From a command window, set up the home directory for WebLogic Commerce Server by typing: SET WL_COMMERCE_HOME=<directory_where_you_
    installed_WebLogic_Commerce_Server>
    .

  2. Navigate to the WL_COMMERCE_HOME\eval\solaris2\Taxware\bin directory, where WL_COMMERCE_HOME is the directory in which you installed WebLogic Commerce Server.

  3. To test the SALES/USE component of TAXWARE, type runsample.sh commonsu.in.

  4. To test the VERAZIP component of TAXWARE, type runsample.sh vzip.in. The result should be a long line that begins with: 00000542No I/O Error.

  5. Check that output string has the expected completion code.

    Note: Refer to the TAXWARE SALES/USE and VERAZIP product documentation for more details about the output string fields and their values.

Changing the TAXWARE Directory Structure

TAXWARE products are integrated with the BEA WebLogic Commerce Server product through the Java Native Interface (JNI). This means that a specially prepared shared object or DLL must be made available for loading during server startup. The Commerce Server ships with a working version of TAXWARE, complete with the correct DLLs and sample data files. If your organization already makes use of TAXWARE products and has installed these files in a different location, you may want to point the BEA WebLogic Commerce Server product's Taxation Services to a different directory structure. For more information about changing the TAXWARE directory structure, see Run-Time Configuration.

TAXWARE Configuration and Deployment

The correct calculation of taxes requires that a number of important pieces of information come together. The bulk of the information needed to calculate taxes is stored in the data structures provided by TAXWARE, and can be loaded using TAXWARE utilities. Additional tax information (from the product catalog, ship to address, and so on) is made available to the BEA WebLogic Commerce Server product via our programmatic interface (API). Finally, the information that cannot be obtained from the data structures or specified using the API must be configured using property files.

This section describes all of the configuration and deployment issues that you will need to take into consideration when using TAXWARE products. The information described focuses on the configuration properties in the weblogiccommerce.properties file that enable tax calculations.

Addresses and Taxation

In many cases, the proper calculation of taxes requires that you specify a number of addresses, including the location from which the order is accepted, where the order originated, where the order shipped from, and where the title is exchanged.

Note: For a detailed explanation of the tax implications associated with these addresses, you will need to consult with TAXWARE International, Inc. and the attorneys in your organization's Legal Department.

The Pipeline components that ship with the BEA WebLogic Commerce Server product support specifying a single location of these addresses for each instance of the Commerce Server. This information is specified and read from the tax section of weblogiccommerce.properties file, located in WL_COMMERCE_HOME, where WL_COMMERCE_HOME is the directory in which you installed the Commerce Server.

For each of the relevant address fields (street, city, state, and so on), there is a separate line in the properties file (see Listing 5-3). The minimum information that you are required to specify is the city, state, zip, and country. If the TAXWARE products determine that this information is enough to identify a unique tax jurisdiction, then it is possible to default the county code and GeoCode by commenting out these properties in the weblogiccommerce.properties file. In some cases, however, it may be necessary to provide a specific county and GeoCode. This is something that you will need to confirm when installing the additional TAXWARE components.

Listing 5-3 Specifying Addresses in the weblogiccommerce.properties File


#################################################################
# ShipFrom Address
# ----------------------------------------------------------------

# ShipFrom Address is address from where goods are shipped 
# Please review Taxware documentation when setting these properties
#

shipfrom.countycode=000
shipfrom.state=MA
shipfrom.city=SALEM
shipfrom.zip=01970
shipfrom.geocode=00
shipfrom.country=USA

################################################################

# Order Acceptance Address 
#----------------------------------------------------------------

# OrderAcceptance is the address where orders are accepted
# Please review Taxware documentation when setting these properties
#

orderacceptance.countycode=000
orderacceptance.state=MA
orderacceptance.city=SALEM
orderacceptance.zip=01970
orderacceptance.geocode=00
orderacceptance.country=USA

#################################################################

# Order Origin Address 
#---------------------------------------------------------------

# Order Origin is the address where orders are Originated
# Please review Taxware documentation when setting these properties
#

orderorigin.countycode=000
orderorigin.state=MA
orderorigin.city=SALEM
orderorigin.zip=01970
orderorigin.geocode=00
orderorigin.country=USA


The point of title passage may be defaulted to be either the ship from or the ship to address. The most common case is to use the shipfrom address. Changing this involves replacing the title passage line by uncommenting one line and replacing it with the other, as shown in Listing 5-4.

Listing 5-4 Specifying Point of Title Passage in the weblogiccommerce.properties File


################################################################

# Point of title passage
# ---------------------------------------------------------------

# Location at which legal title has transferred to purchaser

#titlepassage=shipto 
titlepassage=shipfrom


Note: It is possible to modify the tax calculation Pipeline component to obtain the Address and Taxation properties from a source other than the weblogiccommerce.properties file. Alternative sources may be input from the customer or from a pre-existing inventory or product delivery system. Obtaining the addresses from alternative sources may require prompting the customer for an address, or obtaining the address from your other systems on a per-order basis. Regardless of the method used to obtain the addresses, the addresses must be placed in the Pipeline session, and set in the TaxParameters object prior to calculating tax.

TAXWARE-specific Properties

Because TAXWARE is an external product, there are some properties specific to TAXWARE that must also be configured in the weblogiccommerce.properties file. This section describes each of these properties in detail.

Specifying a Currency

It is important that the ISO currency code be provided to TAXWARE products. In the shipped WebLogic Commerce Server product, the currency field in the shopping cart lines have been defaulted or are empty. It is therefore necessary for you to specify a single currency for use in calculating tax in the weblogiccommerce.properties file, as shown in Listing 5-5. This currency will be used for all tax calculation amounts, and enables future localization of tax calculations.

Listing 5-5 Specifying Currency in the weblogiccommerce.properties File


#################################################################

# Currency for Tax Calculation (Taxware only supports USD)
# ----------------------------------------------------------------

tax.currency = USD


Specifying Your Company's ID

When you configure TAXWARE, you will also need to provide some indentification information for your company to calculate taxes. Because it is possible for multiple corporate entities to share a set of TAXWARE configuration files, your CompanyId must be specified with each request to TAXWARE. This property is the identifier for your company as configured in your TAXWARE deployment. The demonstration configuration uses companyId as the default for this property, so it must be changed for a production environment.

Listing 5-6 Specifying Company ID in the weblogiccommerce.properties File


#################################################################

#---------------------------------------------------------------
# User Defined company identification to access information
# for tax calculating and reporting

companyId=CompanyId


Specifying Your Tax Type

Depending on the nature of your business, you will need to select the type of taxes you want to calculate. The BEA WebLogic Commerce Server product defaults to calculating sales tax for hard and soft goods. TAXWARE also supports calculation of taxes for usage, commercial usage, rental, and services. If your organization requires any of these other models, you will need to modify this property in the weblogiccommerce.properties file, as shown in Listing 5-7.

Listing 5-7 Specifying TaxType in the weblogiccommerce.properties File


#################################################################

# TaxType
#----------------------------------------------------------------
# Type of tax to be calculated

#taxtype=use
#taxtype=rental
#taxtype=consumeruse
#taxtype=services
taxtype=sales


Note: The tax calculation Pipeline components that ship with Commerce Server only allow you to choose one tax type. If your organization requires multiple tax types, you will need to modify the appropriate Pipeline component(s) (TaxCalculateLineLevelPC, TaxCalculateAndCommitLineLevelPC, and TaxVerifyShippingAddressPC) to specify this to the Taxation Service via the Tax Type parameters.

Specifying Calculation of Jurisdiction

Setting the TaxSelParm property (shown in Listing 5-8) will indicate to the TAXWARE product whether or not you must fully calculate jurisdiction. If you set this option to 2, TAXWARE will not determine the jurisdiction. If you do not need to determine jurisdiction, you may also remove the shipfrom, orderacceptance, and orderorigin address properties from the weblogiccommerce.properties file, as they will not be required (see Listing 5-3).

Listing 5-8 Specifying Jurisdiction Calculations in the weblogiccommerce.properties File


################################################################

# TaxSelParm
#--------------------------------------------------------------
# Taxselparm to decide jurisdiction while calculating
# if value is 2 Calculate tax only
# if value is 3 Determine jurisdiction and calculate taxes

#taxselparm=2
taxselparm=3


Note: Setting the TaxSelParm property is a business decision that will require input from your Legal Department and TAXWARE International, Inc.

Run-Time Configuration

TAXWARE products are integrated with the WebLogic Commerce Server product through the Java Native Interface (JNI). This means that a specially prepared shared object or DLL must be made available for loading during server startup. Additionally, there are a number of files containing the address verification data and tax tables that are accessed at run time. The WebLogic Commerce Server ships with a working version of TAXWARE, complete with the correct DLLs and sample data files. If you have installed TAXWARE in a different location, you must change the location from which these files are loaded. The differences between the default WebLogic Commerce Server and the sample TAXWARE directory structure are shown in Table 5-7.

Table 5-7 Differences in WebLogic Commerce Server and TAXWARE Directory Structures

Default WebLogic Commerce Server Structure

Sample TAXWARE Structure

Subdirectories:

\data

\audit

\temp

\bin

Subdirectories:

\indata

\outdata

\audit

\temp

\bin

On Windows systems, pointing to the correct file locations is accomplished by making the following changes:

The default WebLogic Commerce Server run-time configuration is shown in Listing 5-9.

Listing 5-9 WebLogic Commerce Server Run-Time Configuration on Windows Systems


REM ---- Add WebLogic, CyberCash, and Taxware bin directories to the path  ----

SETLOCAL
SET PATH=%PATH%;%WEBLOGIC_HOME%\bin;%WL_COMMERCE_HOME%\eval\win32\CyberCash\bin;%WL_COMMERCE_HOME%\eval\win32\Taxware\bin


On UNIX systems, pointing to the correct file locations is accomplished by making the following changes in the file bin/unix/set-environment.sh:

  1. Set the environment variable TAXWARE_HOME to point to the location of your TAXWARE installation. The default WLCS run-time configuration is shown in Listing 5-10.

  2. Set the TAXWARE-specific environment variables to the correct data directories. For an example, see Listing 5-11.

  3. Check the environment variable WLCS_CLASSPATH to make sure it includes the directory in which taxcommon.class lives.

  4. Verify that the environment variable for your TAXWARE shared libraries (.so or .sl files) are correct. For example, under Solaris, the default environment variable LD_LIBRARY_PATH includes $TAXWARE_HOME/lib. It might change to $TAXWARE_HOME/utl or similar depending on your TAXWARE installation.

    Notes: The actual variable name varies depending on the type of UNIX platform.

    For theses changes to take effect, you need to restart your server.

    Listing 5-10 The WebLogic Commerce Server Run-Time Configuration on UNIX Systems


    #--------- WLCS Taxware Environment variables ----------
    TAXWARE_HOME=$WL_COMMERCE_HOME/eval/solaris2/Taxware


    #---------- Taxware and CyberCash shared objects
    LD_LIBRARY_PATH=$TAXWARE_HOME/lib:$WL_COMMERCE_HOME/eval/solaris2/CyberCash/lib:$JDK_HOME/jre/lib/sparc
    export LD_LIBRARY_PATH


    Listing 5-11 TAXWARE Environment Variables on UNIX Systems (Sample TAXWARE Installation)


    #----------Taxware Environment variables -------------

    TAXWARE_HOME=$WL_COMMERCE_HOME/eval/solaris2/Taxware
    AVPIN=$TAXWARE_HOME/indata
    export AVPIN
    AVPOUT=$TAXWARE_HOME/outdata
    export AVPOUT
    AVPTEMP=$TAXWARE_HOME/temp
    export AVPTEMP
    AVPAUDIT=$TAXWARE_HOME/audit
    export AVPAUDIT

    STEPIN=$TAXWARE_HOME/indata
    export STEPIN
    STEPOUT=$TAXWARE_HOME/outdata
    export STEPOUT
    STEPTEMP=$TAXWARE_HOME/temp
    export STEPOUT

    ZIPIN=$TAXWARE_HOME/indata
    export ZIPIN
    ZIPOUT=$TAXWARE_HOME/outdata
    export ZIPOUT
    ZIPTEMP=$TAXWARE_HOME/temp
    export ZIPTEMP

    BT_SHARE=N 
    export BT_SHARE


    Notes: The use of these directories is described in more detail in the TAXWARE product documentation.

    The most important of these directories is the AVPAUDIT directory. This is where the audit information used by TAXWARE to generate tax reports is stored. You will need to establish a process for your production environment whereby a given server is taken offline while the audit files are copied and replaced. The details of this process will depend largely on whether or not you deploy TAXWARE in a cluster.

Tax Codes and the Product Catalog

Another important factor in the calculation of taxes is that the items in your product catalog must have properly assigned tax codes. Specifically, the tax codes assigned to items in your product catalog must match the tax codes configured in TAXWARE. Ensuring this match involves either manually updating the tax codes using the product catalog administration tool, or creating bulk loading scripts.

Note: To obtain the appropriate tax codes for your product items, refer to the TAXWARE product documentation.

Updating TAXWARE Tax Data

As previously described, TAXWARE periodically provides updates to the tax data used in tax calculations. This update process is handled by TAXWARE tools, for which TAXWARE International, Inc. provides the installation and usage procedures. However, you will need to establish a process for your production environment to handle the server being taken offline and the tax data files updated. This procedure will depend largely on whether or not you deploy TAXWARE in a cluster.

TAXWARE Checklist

Based on the information described in this section, you should be able to configure and deploy the TAXWARE products. The following checklist will help ensure that you have followed all the necessary steps for accurate tax calculations.

Removing Tax Calculations

This section describes the process by which you might remove the Order Processing package's Taxation Services from your customized Web application. Removing these tax calculation entails modifying the Pipeline and Webflow properties files to bypass the Taxation Services currently provided in the Order Pipeline.

Modifying the Pipeline Properties File

To remove the Taxation Services from the Pipeline, follow these steps:

  1. Copy the WL_COMMERCE_HOME/pipeline.properties file to WL_COMMERCE_HOME/pipeline.properties.stock, where WL_COMMERCE_HOME is the directory in which you installed WebLogic Commerce Server. This is done in case you want to revert back to the original file content.

  2. Open the pipeline.properties file and locate the CommitOrder Pipeline, as shown in Listing 5-12.

    Listing 5-12 Default CommitOrder Pipeline


    # CommitOrder 

    CommitOrder.componentList=CommitOrderPC, AuthorizePaymentPC, TaxCalculateAndCommitLineLevelPC
    CommitOrder.isTransactional=true


  3. Remove the TaxCalculateAndCommitLineLevelPC Pipeline component from the first line of the CommitOrder Pipeline definition, so the CommitOrder Pipeline is as shown in Listing 5-13.

    Listing 5-13 CommitOrder Pipeline Without Tax Pipeline Component


    # CommitOrder 

    CommitOrder.componentList=CommitOrderPC, AuthorizePaymentPC
    CommitOrder.isTransactional=true


  4. Save the modified file. You do not need to restart the server to view your changes if you have set the pipeline.hotdeploy.enable property to true in the weblogiccommerce.properties file.

Modifying the Webflow Properties File

  1. Copy the WL_COMMERCE_HOME/webflow.properties file to WL_COMMERCE_HOME/webflow.properties.stock, where WL_COMMERCE_HOME is the directory in which you installed WebLogic Commerce Server. This is done in case you want to revert back to the original file content.

  2. Locate and remove (or comment out) all lines in the webflow.properties file that reference the following Pipeline components:

  3. Locate the Select Shipping Address Page section of the webflow.properties file, as shown in Listing 5-14. Notice that in the default configuration, the TaxVerifyShippingAddress Pipeline is invoked upon successful execution of the UpdateShippingAddressIP input processor.

    Listing 5-14 Default Shipping Address Page in the webflow.properties File


    # Select Shipping Address Page
    ...
    ...

    SelectShippingAddress_UpdateShippingAddress.inputprocessor.
    success=TaxVerifyShippingAddress.pipeline

    ...


  4. Replace the TaxVerifyShippingAddress.pipeline with CalculateShippingCost.pipeline, so the Select Shipping Address Page section in the webflow.properties file is as shown in Listing 5-15.

    Listing 5-15 Shipping Address Page Without Tax Pipeline


    # Select Shipping Address Page
    ...
    ...

    SelectShippingAddress_UpdateShippingAddress.inputprocessor.
    success=CalculateShippingCost.pipeline

    ...


  5. Locate the success path for the CalculateShippingCost Pipeline in the webflow.properties file, as shown in Listing 5-16.

    Listing 5-16 Default Success Path for CalculateShippingCost Pipeline


    # Decide to prompt selecttaxaddress.jsp on basis of number of 
    # addresses retuned by verazip

    ...
    ...

    CalculateShippingCost.pipeline.success=TaxCalculateLineLevel.
    pipeline

    ...


  6. Replace the TaxCalculateLineLevel Pipeline with commerce/order/payment.jsp, so the success path for the CalculateShippingCost Pipeline is as shown in Listing 5-17.

    Listing 5-17 Success Path for CalculateShippingCost Pipeline without Tax Pipeline


    # Decide to prompt selecttaxaddress.jsp on basis of number of 
    # addresses retuned by verazip

    ...
    ...

    CalculateShippingCost.pipeline.success=commerce/order/payment.jsp

    ...


  7. Locate and remove (or comment out) all lines in the webflow.properties file that reference the following:

  8. Save the modified file. You do not need to restart the server to view your changes if you have set the webflow.hotdeploy.enable property to true in the weblogiccommerce.properties file.

What if I Don't Want to Use TAXWARE to Calculate My Taxes?

Although the BEA WebLogic Commerce Server product utilizes products from TAXWARE International, Inc. to calculate taxes, you may choose to use another provider of tax services. If you do not wish to use TAXWARE, you will need to remove TAXWARE from the Pipeline (see Removing Tax Calculations), write new Pipeline components to handle tax calculations using the new tax provider, and integrate these Pipeline components into the Webflow/Pipeline infrastructure.

Note: The existing TAXWARE Pipeline components are delivered as source and provide an excellent starting point for anyone wanting to use another provider of tax services. The integration point for tax calcuations is the Tax attribute of the ShoppingCartLine, for which you can use the set() and get() methods to set the tax for each line in a customer's shopping cart. For more information, see the Javadoc.