|
|
|
|
|
|
Taxation Services
The taxation functionality provided in the Managing Purchases and Processing Orders services 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 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.
Note: For a description of the complete set of JSPs used in the WebLogic Commerce Server Web application and a listing of their locations in the directory structure, see the E-Commerce JSP Template Summary.
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 Select Tax Jurisdiction region 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.
Note: For information on other elements in the selecttaxaddress.jsp template, see Common JSP Template Elements.
Figure 5-1 Annotated selecttaxaddress.jsp Template
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\ Tag Library Imports The selecttaxaddress.jsp template uses existing WebLogic Server and Pipeline JSP tags. Therefore, the template includes the following JSP tag libraries: Note: For more information on the WebLogic Server JSP tags, see "JSP Tag Reference" in the Guide to Building Personalized Applications. For more information about the Pipeline JSP tags, see the Guide to Managing Presentation and Business Logic: Using Webflow and Pipeline. These files reside in the following directory for the WebLogic Commerce Server Web application: %WL_COMMERCE_HOME%\server\webapps\wlcs\WEB-INF (Windows) Java Package Imports The selecttaxaddress.jsp template uses Java classes in the following packages and therefore includes these import statements: 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 Managing Purchases and Processing Orders. Included JSP Templates The following JSP templates are included in the selecttaxaddress.jsp template:
selecttaxaddress.jsp (Windows)
$WL_COMMERCE_HOME/server/webapps/wlcs/commerce/order/
selecttaxaddress.jsp (UNIX)<%@ taglib uri="weblogic.tld" prefix="wl" %>
<%@ taglib uri="pipeline.tld" prefix="pipeline" %>
$WL_COMMERCE_HOME/server/webapps/wlcs/WEB-INF (UNIX)<%@ 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.*" %>
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.
|
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.
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 the Guide to Managing Presentation and Business Logic: Using Webflow and Pipeline.
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.
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 Guide to Building Personalized Applications.
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.
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
UpdateShippingAddressIP
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
TaxCalculateAndCommitLineLevelPC
TaxVerifyShippingAddressPC
Integration with TAXWARE
To ensure that the Taxation Services properly determine taxes for the items in your product catalog, the WebLogic Commerce Server product integrates with the following TAXWARE International Inc.'s commercial tax products.
Note: For more information about TAXWARE International, Inc. and TAXWARE products, visit the company's Web site at http://www.taxware.com.
Important TAXWARE Considerations
The following are important factors regarding the 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, Universal Tax Link (UTL), and WORLDTAX systems are shipped with the WebLogic Commerce Server product to provide out-of-the-box TAXWARE functionality. The WebLogic Commerce Server's installation program will install these TAXWARE products along with the WebLogic Commerce Server, and will also uninstall them during uninstallation of the WebLogic Commerce Server.
The versions of the TAXWARE products installed with the WebLogic Commerce Server product are as follows:
Note: Utilization of WebLogic Commerce Server in the connection to and operation of third-party software, services and applications including, but not limited to, Cybercash credit card services and TAXWARE tax calculation services, is entirely at the user's risk. BEA Systems, Inc. disclaims all liability and responsibility for the operation, accuracy and results of such software, services and applications.
Installation Directory Structure
The TAXWARE product files installed with the 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, DLLs, and preloaded data files needed for Win32 installation reside in subdirectories beneath WL_COMMERCE_HOME\eval\win32\Taxware, except for Java classes, which reside in WL_COMMERCE_HOME\eval\common\Taxware. 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.
Additionally, the WL_COMMERCE_HOME\eval\win32\Taxware directory (where WL_COMMERCE_HOME is where you installed the WebLogic Commerce Server) contains the following three ini files:
Notes: The WebLogic Commerce Server product's installation program automatically moves these files from the WL_COMMERCE_HOME directory to the C:\Winnt directory.
For more information about the ini files, see Run-Time Configuration.
UNIX
All TAXWARE audit files, shared objects, and preloaded data files needed for UNIX installation reside in subdirectories beneath WL_COMMERCE_HOME/eval/solaris2/Taxware, except for Java classes, which reside in WL_COMMERCE_HOME/eval/common/Taxware. 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.
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:
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:
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 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 WebLogic Commerce Server ships with a working version of TAXWARE, complete with the correct DLLs and sample data files. If your organization has purchased TAXWARE products and installed these files in a different location, you must point the WebLogic Commerce Server product's Taxation Services to the correct directories. 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 WebLogic Commerce Server product via our programmatic interface (API). 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 need to consider when using TAXWARE products. The information described here focuses on the configuration properties in the weblogiccommerce.properties file, which enables tax calculations.
Addresses and Taxation
In many cases, the proper calculation of taxes requires that you specify a number of addresses, including the location where 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.
For Canadian postal codes, the official format is one space between the first three and last three characters. For TAXWARE, omit the space.
The Pipeline components that ship with the WebLogic Commerce Server product support specifying a single location of these addresses for each instance of the WebLogic Commerce Server. This information is specified and read from the tax section of weblogiccommerce.properties file, located in WL_COMMERCE_HOME. WL_COMMERCE_HOME is the directory in which you installed the WebLogic 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 information that you are required to specify is described in the following list:
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
#
taxware.shipFrom.country=US
taxware.shipFrom.state=TX
taxware.shipFrom.city=Round Rock
taxware.shipFrom.zip=78682
taxware.shipFrom.county=WILLIAMSON
taxware.shipFrom.geoCode=00
#################################################################
# Order Origin Address
#---------------------------------------------------------------
# Order Origin is the address where orders are Originated
# Please review Taxware documentation when setting these properties
#
taxware.orderOrigin.countycode=000
taxware.orderOrigin.state=MA
taxware.orderOrigin.city=SALEM
taxware.orderOrigin.zip=01970
taxware.orderOrigin.geocode=00
taxware.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
#taxware.titlePassage=shipto
taxware.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.
The TAXWARE specific parameters are all prepended by the string taxware. The general format of the weblogiccommerce.properties file is key=value, where key tells the WebLogic Commerce Server which parameter is being configured and value is what is set by the end user. Any amount of white space may separate the key from the equals sign and from the value. This file is read using java.util.Properties.load(InputStream) and subsequently key is case sensitive.
Specifying a Currency
It is important that the ISO 4217 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 at least one 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.currency = USD
Specifying Your Company's ID and Business Location
When you configure TAXWARE in order to calculate taxes, you need to provide identification information for your company. 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 shows a sample configuration.
You may also need to specify your business location for WORLDTAX reporting. If the seller registration number is not set, WORLDTAX uses the business location and company ID to look up the seller registration number. This mapping is set up using TAXWARE tools. If neither the business location nor the seller registration number are set, WORLDTAX cannot properly calculate the tax. If the seller registration is not set, you must modify this property in the weblogiccommerce.properties file, as shown in Listing 5-6.
Listing 5-6 Specifying Company ID and Business Location in the weblogiccommerce.properties File
#################################################################
#---------------------------------------------------------------
# User Defined company identification to access information
# for tax calculating and reporting
taxware.companyId=BEA Systems
taxware.businessLocation=London Office
Specifying Your Seller Registration Number
If you have accounts outside of the U.S. or Canada, you may need to set the registration number of the seller. This parameter works with the businessLocation parameter. Please see Specifying Your Company's ID and Business Location. If you need to specify the Seller Registration Number, you must modify this property in the weblogiccommerce.properties file. For an example, see Listing 5-7. Table 5-7 lists the Registration Number Formats for the countries supported by the WebLogic Commerce Server.
Listing 5-7 Specifying Seller Registration Number in the weblogiccommerce.properties File
#################################################################
# Seller registration number is used outside the US and Canada
# It's format is country specific. Please see the WorldTax
# docs for more information
#
taxware.sellerRegistrationNumber=123 4567 89
Specifying Your Tax Type
Depending on the nature of your business, you may need to select the type of taxes you want to calculate. The WebLogic Commerce Server product defaults to calculating sales tax for hard and soft goods. The SALES/USE module 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-8.
Listing 5-8 Specifying TaxType in the weblogiccommerce.properties File
#################################################################
# TaxType
#----------------------------------------------------------------
# Type of tax to be calculated
#taxware.taxType=use
#taxware.taxType=rental
#taxware.taxType=consumeruse
#taxware.taxType=services
taxware.taxType=sales
Note: The tax calculation Pipeline components that ship with WebLogic 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 taxType parameters.
Specifying Calculation of Jurisdiction
Setting the TaxSelParm property (shown in Listing 5-9) 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 and orderOrigin address properties from the weblogiccommerce.properties file, as they will not be required (see Listing 5-3).
Listing 5-9 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.
Adding Countries to the WebLogic Commerce Server
As previously mentioned, the WebLogic Commerce Server supports nine countries, including the U.S. and Canada. BEA has tested only these countries for accuracy. However, WORLDTAX supports many more countries. If you have the capability to test the countries supported by WORLDTAX but not the WebLogic Commerce Server, this section provides the necessary information for adding countries.
To add countries, two files need to be updated to the out-of-the-box installation of WebLogic Commerce Server. The first file is %WL_COMMERCE_HOME%\server\webapps\wlcs\commerce\includes\countries.jsp (Windows) or $WL_COMMERCE_HOME/server/webapps/wlcs/commerce/includes/countries.jsp (UNIX).
These files have entries like those shown in Listing 5-10.
Listing 5-10 Sample countries.jsp File Entries
<option valueanada>Canada
<option value="United Kingdom">United Kingdom
<option value="France">France
<option value="Spain">Spain
<option value="Italy">Italy
The second file is $WL_COMMERCE_HOME/classes/com/beasys/commerce/util/country.properties (UNIX) or %WL_COMMERCE_HOME%\classes\com\beasys\commerce\util\country.properties (Windows). These files contains entries like those shown in Listing 5-11.
Listing 5-11 Sample country.properties File Entries
country1.iso3166Code=840
country1.twoCharAbbr=US
country1.threeCharAbbr=USA
country1.englishLabel=United States
country1.iso4217CurrencyCode=USD
country1.currencyEnglishLabel=United States Dollar
The country.properties file contains information about a particular country and is referenced once at startup.
The country.properties file contain a list of countries. Each country stanza is prepended with the word country and a number from 0 to 10000. You can skip numbers and there is not a requirement that the numbers be in order. All fields displayed in Listing 5-11 are required. The following list describes these fields in detail:
To add an additional country you must add it in both countries.jsp and country.properties.
Note: The value in the option HTML tag in countries.jsp must match one of iso3166Code, twoCharAbbr, threeCharAbbr, or englishLabel in the properties file for the country to be added. An unknown country in the JSP file throws an exception.
Adding and Modifying Provinces and States
The WebLogic Commerce Server uses two files to generate province information. For this discussion, a state is considered a province. The first file is $WL_COMMERCE_HOME/server/webapps/wlcs/commerce/includes/states.jsp (UNIX) or %WL_COMMERCE_HOME%\server\webapps\wlcs\commerce\includes\states.jsp (Windows). These files have entries like those shown in Listing 5-12.
Listing 5-12 Sample states.jsp File Entries
<option>WV
<option>WY
<option>Alberta
<option>British Columbia
The second file is country dependent. The WebLogic Commerce Server ships with two files, one for the U.S. and one for Canada. The U.S. file is %WL_COMMERCE_HOME%\classes\com\beasys\commerce\util\us.province.properties (Windows) or $WL_COMMERCE_HOME/classes/com/beasys/commerce/util/us.province.properties (UNIX).
In general, these files have the name format of the lowercase, two-character country code followed by the .province.properties suffix. The province.properties files contains entries that look like those in Listing 5-13.
Listing 5-13 Sample province.properties File Entries
province7.name=Colorado
province7.abbr=CO
province8.name=Connecticut
province8.abbr=CT
province9.name=Delaware
province9.abbr=DE
province10.name=District of Columbia
province10.abbr=DC
province11.name=Federated States of Micronesia
province11.abbr=FM
The province.properties file contains a list of the specified country's provinces. Each province stanza is prepended with the word province and a number from 0 to 10000. You can skip numbers and there is not a requirement that the numbers be in order. All fields displayed in Listing 5-12 are required. The following list describes these fields in detail:
It is important to note that there is no requirement that you use all of the provinces of a country. For example, in the United States a supplier may ship only to addresses within the continental United States. In this case, the supplier needs only to modify the states.jsp and us.province.properties to include only the 48 contiguous states.
Note: The value in the option HTML tag in the states.jsp must match either the name or abbr in the properties file for the province to be added. An unknown province in the JSP file will throw an exception.
Configuration Parameters
The weblogiccommerce.properties holds many configuration parameters that configure the operation of the WebLogic Commerce Server's interaction with TAXWARE. It's important to understand how these fields are used in order to configure them correctly.
The general format of this file is key = value, where key tells WebLogic Commerce Server which parameter is being configured and value is that set by the end user. Any number of spaces may separate the key from the equals sign and from the value. This file is read using java.util.Properties.load(InputStream) and therefore the key is case sensitive.
The TAXWARE specific parameters are all prepended by the string taxware. The following lists describes each value in detail:
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-8.
On Windows systems, pointing to the correct file locations is accomplished by making the following changes:
Note: For these changes to take effect, you need to restart your server.
The default WebLogic Commerce Server run-time configuration is shown in Listing 5-14.
Listing 5-14 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:
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-15 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-16 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.
Configuring the HTTP Server for TAXWARE
The TAXWARE service uses one or more separate Java Virtual Machines (JVM) to run an HTTP server. This HTTP server handles TAXWARE requests and returns the TAXWARE data.
Implementing and Configuring the HTTP Server
The TAXWARE service is implemented as a generic multithreaded HTTP server. The server dynamically loads Java classes for servicing a particular type of request. Additionally, so that a sufficient number of file descriptors are available to TAXWARE, it implements a governor that limits the number of simultaneous connections. For one possible implementation, see Figure 5-2.
Figure 5-2 A Possible TAXWARE Configuration
A TAXWARE specific handler is part of the standard distribution. Other handlers include a ping handler, a handler to serve statistics, a shutdown handler, and a generic get handler. Only the TAXWARE and the ping handlers are required. Server Configuration Two configuration files are needed for the HTTP server. One for the server side and one for the client side. Both configuration files are Java properties files. The server configuration file is discussed in this section and the client configuration file is discussed in Connection Manager. The server configuration file, named SimpleHTTPServer.properties, is in %WLCS_HOME%\classes\com\beasys\commerce\netservice\http\server (Windows) or $WLCS_HOME/classes/com/beasys/commerce/netservice/http/server (UNIX) and has the following parameters:
Note: Except for Solaris, no operating system has limits set by the server. However, limits are still imposed by operating systems. If this parameter doesn't exist, regardless of operating system, a warning is printed. If this number is set too high, you run the risk of hitting a file descriptor limit.
POST /uri HTTP/1.1
where /uri is the Universal Resource Identifier for the requested resource.
The server uses the URI to determine which handler is used for the requested resource. For example, the TAXWARE handler provided with WebLogic Commerce Server looks like:
postHandler.URI./taxware=com.beasys.commerce.ebusiness.tax.taxware.TaxwareNetServiceHandler
This means that for post requests asking for /taxware as the URI, the server loads and calls the class com.beasys.commerce.ebusiness.tax.taxware.TaxwareNetServiceHandler to service the request.
When the server cannot find another handler for a requested URI, it uses a default handler, which is a special handler of type "*". No requirement exists for a default handler; however, if it doesn't exist and a URI comes in without a handler, the client receives a 400 Bad Request message.
getHandler.URI./ping=com.beasys.commerce.netservice.http.server.PingHandler
Additionally, by default, two other get handlers are included: the Shutdown handler and the Statistics handler. The Shutdown handler allows remote shutdown of a server. The Statistics handler returns status information about the server to the requesting client. Although these handlers are useful, you are not required to have them installed.
Note: The default get handler acts as a web server. It returns files in the same way as a normal web server. This handler is useful for testing but it should probably not be deployed in a production environment.
http://hostname:portnum/file_name.html
reads the file /usr/local/file_name.html and sends it back to the client. If your configuration does not have a generic get handler, this parameter is not required.
Connection Manager
Clients talk to the server using a special connection manager. The file for the connection manager, named HTTPConnectionManager.properties, is in %WLCS_HOME%\classes\com\beasys\commerce\netservice\http\client (Windows) or $WLCS_HOME/classes/com/beasys/commerce/netservice/http/client. (UNIX).
The connection manager is configured by two parameters, which are discussed in the following list:
host:port:connection_count, host:port:connection_count
where
Note: Regardless of how many connections the client wants to make, the server still controls the maximum number of connections that it can handle.
There can be any number of service specifications for a particular type. Separate each triplet by a comma. When the connection manager needs to get a connection, it looks into the pool of available connections and returns the one that was used least recently. Consequently, the load is spread out across all available connections.
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.
Viewing Debugging Information in TAXWARE
Use the taxware.debug.tax property to help you debug TAXWARE. When this property exists, regardless of its value, it turns on debugging output for the SALES/USE and WORLDTAX components.
Listing 5-17 Enable taxware.debug.tax
# Debug Sale/Use and Worldtax
#taxware.debug.tax=bug
Removing Tax Calculations
This section describes the process by which you might remove 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:
Listing 5-18 Default CommitOrder Pipeline
# CommitOrder
CommitOrder.componentList=CommitOrderPC, AuthorizePaymentPC, TaxCalculateAndCommitLineLevelPC
CommitOrder.isTransactional=true
Listing 5-19 CommitOrder Pipeline Without Tax Pipeline Component
# CommitOrder
CommitOrder.componentList=CommitOrderPC, AuthorizePaymentPC
CommitOrder.isTransactional=true
Modifying the Webflow Properties File
Listing 5-20 Default Shipping Address Page in the webflow.properties File
...
SelectShippingAddress_UpdateShippingAddress.inputprocessor.
success=TaxVerifyShippingAddress.pipeline
...
Listing 5-21 Shipping Address Page Without Tax Pipeline
...
SelectShippingAddress_UpdateShippingAddress.inputprocessor.
success=CalculateShippingCost.pipeline
...
Listing 5-22 Default Success Path for CalculateShippingCost Pipeline
...
CalculateShippingCost.pipeline.success=TaxCalculateLineLevel.
pipeline
...
Listing 5-23 Success Path for CalculateShippingCost Pipeline Without Tax Pipeline
...
CalculateShippingCost.pipeline.success=PriceOrder.pipeline
...
What if I Don't Want to Use TAXWARE to Calculate My Taxes?
Although the 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 calculations 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.
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|