Taxation Services

 

WebLogic Portal includes a flexible taxation service that lets you connect to a third-party tax calculation product for determine the accurate tax rates imposed on the sale or use of each item at the state, country, city, and district levels. This topic describes the Taxation Service in detail.

This topic includes the following sections:

• Introduction to Web Services

• How the Taxation Service Works

• JavaServer Pages (JSPs)

  • selecttaxaddress.jsp Template

• Input Processors

  • DecideShippingAddressPageIP

  • UpdateShippingAddressIP

• Pipeline Components

  • TaxCalculateLineLevelPC

  • TaxCalculateAndCommitLineLevelPC

  • TaxVerifyShippingAddressPC

• Integrating with a Taxation Service

  • If the Third-Party Vendor Hosts the Web Service

  • If Your Organization Hosts the Web Service

 

---

Introduction to Web Services

Web services are stand-alone software components, available over the Internet, that you can bind into your enterprise applications for immediate functionality. Web services are self-describing, self-contained, modular applications that can be mixed and matched with other Web services. You do not need to understand the internal workings of the Web services. You only need to know how to connect your enterprise applications to these services.

Web services can be visible or invisible to your site visitors. For example, a visible Web service can be a stock ticker that appears in a portlet on your site; or, to use two examples of invisible Web services, used in e-commerce (and shipped with WebLogic Portal), Web services that facilitate the handling of online payment and taxation for purchases. This chapter and the next cover these two payment and taxation Web services.

The main reason that Web services are plug-and-play is because they use standard, proven Internet technologies such as HTTP, HTML, and XML. The characteristics of Web services include the following:

• Accessibility via the Web

• Exposure of an XML interface

• Ability to be located via a registry

• Use of XML messages over standard Web protocols

• Support of loosely coupled connections between systems

Ultimately, Web services allow companies and individuals to rapidly and economically make their services available worldwide.

The following sections describe the core standards of Web services. These standards are used in the WebLogic Portal Payment and Taxation services.

Simple Object Access Protocol (SOAP)

Simple Object Access Protocol (SOAP) is an XML-based standard for sending and receiving messages over the Internet, using transports like HTTP. A service request is embodied in a SOAP message and HTTP posted to a Service Provider. The response is then synchronously returned via the same HTTP session, embodied in a SOAP response message.

For more information, go to www.w3.org/TR/SOAP/.

Web Services Description Language (WSDL)

Web Services Description Language (WSDL) is an XML-based standard that describes the services a business offers and provides a way for individuals and other businesses to access those services electronically. In more technical terms, WSDL describes the programmatic interface of a Web service, allowing companies who use a Web service to craft the program statements that invoke the Web service.

WSDL is the cornerstone of the Universal Description, Discovery, and Integration (UDDI) initiative. UDDI is an XML-based registry for businesses worldwide that enables businesses to list themselves and their services on the Internet. WSDL is the language used to do this.

 

---

How the Taxation Service Works

Figure 5-1 shows the basic architecture of WebLogic Portal's taxation service. The key component of this architecture is the Tax Web Service, which is the connection point between WebLogic Portal and any third-party tax calculation product.

Figure 5-1 taxation Service Architecture

 

Following is a description of each piece of the architecture.

1	The TaxPC Pipeline component controls the taxation sequence in the Webflow and instantiates the TaxCalculator EJB. For information on Webflow, see the Guide to Managing Presentation and Business Logic: Using Webflow and Pipeline.
2	The TaxCalculator EJB handles the business logic for the tax calculation. The EJB converts its taxation service calls to XML for transporting SOAP messages to the Tax Web service.
3	The TaxCalculator EJB in WebLogic Portal sends SOAP messages to the Web service, where those SOAP messages are converted to the language of the third-party product's API. The third-party taxation service applies taxes to orders and sends calculated tax amounts or exceptions back to the enterprise application. Caution: The default Tax Web service that ships with WebLogic Portal automatically applies a 5% tax to an order. This default application of taxes is not designed for production use. You must integrate with your third-party vendor's tax service to calculate taxes properly.

 

There are two keys to connecting an enterprise application with a Tax Web service:

• Sending the proper SOAP messages from the TaxCalculator EJB to the Tax Web Service

• In the Tax Web Service, translating the SOAP messages into the language of the third-party product's API

For information on connecting an enterprise application to a Web service, see Integrating with a Taxation Service.

 

---

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 Portal 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 Tax Web service code that is used to determine taxes based on jurisdiction), the selecttaxaddress.jsp template (shown in Figure 5-2) allows the customer to select from a list of more specific shipping addresses.

Sample Browser View

Figure 5-2 shows 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-2 Annotated selecttaxaddress.jsp Template

 
 

Location in the WebLogic Portal Directory Structure

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

%PORTAL_HOME%\applications\wlcsApp\wlcs\commerce\order\
selecttaxaddress.jsp (Windows)
$PORTAL_HOME/applications/wlcsApp/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="es.tld" prefix="es" %>
<%@ taglib uri="weblogic.tld" prefix="wl" %>
<%@ taglib uri="webflow.tld" prefix="webflow" %>

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 lib directory within PORTAL_HOME.

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.axiom.contact.*" %>

<%@ page import="com.beasys.commerce.ebusiness.shipping.*" %>

<%@ page import="com.beasys.commerce.webflow.HttpRequestConstants" %>

<%@ page import="com.beasys.commerce.webflow.PipelineSessionConstants" %>

<%@ page import="com.bea.p13n.appflow.webflow.WebflowJSPHelper" %>

<%@ page import="com.bea.p13n.appflow.webflow.SessionManagerFactory" %>

<%@ page import="com.bea.p13n.appflow.common.PipelineSession" %>

<%@ page import="com.bea.p13n.appflow.common.internal.AppflowConstants" %>

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).

The template is in the sampleapp_order namespace.

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:

• header.inc, which creates the top banner.

• admin.inc, which is used on all pages and presents the top red-and-black banner with links to the main WLCS Administration screen, to this template index, and to a *.jsp.html file for the current template. You should remove this from the JSP when you deploy it.

• leftside.inc, which presents quick look-up and a promotional ad; for authenticated users, it also presents a personalized message to the user, customer profile link, order history link, and payment history link.

• footer.inc, which creates a horizontal footer at the bottom of the page.

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.checkout	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 getProperty JSP tag retrieves the AVS_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. AVS_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

<webflow:getProperty id="addressesObject" property="<%=PipelineSessionConstants.AVS_SHIPPING_ADDRESSES%>" type="java.lang.Object" scope="session" namespace="sampleapp_main" />

Note: For more information on the getProperty 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.

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> and Accessor Methods in selecttaxaddress.jsp

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

<%

  String extraParams = HttpRequestConstants.TAX_SHIPPING_ADDRESS + "=" + address.getGeoCode();

%>

  <table width="90%" border="0" cellpadding="3" cellspacing="0">

    <tr>

      <td align="left" valign="top" width="15%">

        <a href="<webflow:createWebflowURL event="button.checkout" httpsInd="calculate"  

         namespace="sampleapp_order" extraParams="<%= extraParams %>" />">

         <img border=0 src="<webflow:createResourceURL resource="/commerce/images/btn_use.gif" />">

       </a>

      <td align="left" valign="top">

        <div class="tabletext"><%= address.getStreet1() %><br>

      <% if(address.getStreet2().length() != 0) { %>

      <%=address.getStreet2()%><br>

      <% } %>

      <b>County  <%= address.getCounty() %></b><br>

      <%= address.getCity() %><br>

      <%= address.getState() %> <%= address.getPostalCode() %><br>

      <%= address.getCountry() %><br>

      &nbsp;</div>

      </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.

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	examples.wlcs.sampleapp.tax.webflow. DecideShippingAddressPageIP
Description	Makes the decision about whether to display selecttaxaddress.jsp based on the number of address variations returned from the Tax Web 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.AVS_SHIPPING_ADDRESSES
Updated Pipeline Session Attributes	PipelineSessionConstants.SHIPPING_ADDRESS (in the case of a single address)
Removed Pipeline Session Attributes	None
Validation	None
Exceptions	None

 

UpdateShippingAddressIP

Class Name	examples.wlcs.sampleapp.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.AVS_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	examples.wlcs.sampleapp.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	examples.wlcs.sampleapp.tax.pipeline. TaxCalculateAndCommitLineLevelPC
Description	Calculates the tax and provides line-level information about the taxability of an item. The results are logged to the Tax Web service 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	examples.wlcs.sampleapp.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.AVS_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). TaxUserException, thrown if processing could not occur due to invalid user input.

 

 

---

Integrating with a Taxation Service

The Tax Web Service that is installed with WebLogic Portal provides a default framework for handling tax calculations on transactions received from the default TaxCalculator EJB. The business methods within the TaxCalculator EJB implement a standard workflow that is associated with the completion of order taxation. (The Tax Web service, by comparison, is a stateless session EJB wrapped in code that makes it a Web service.)

Integrating your enterprise applications with the Tax Web Service involves modifying either the TaxCalculator EJB or the Tax Web Service, depending on who will host the Web service: your organization or the third-party tax calculation vendor.

In either case, it helps to understand the connection relationship between the pieces in the WebLogic Portal taxation services and the pieces in the Tax Web Service. Figure 5-3 illustrates the connection between the two.

Figure 5-3 The Relationship Between the Tax Web Service and the TaxCalculator EJB

 

Caution: The default Tax Web service that is shipped with WebLogic Portal automatically applies a 5% tax to an order. This default application of taxes is not designed for production use. You must integrate with your third-party vendor's tax service to calculate taxes properly.

If the Third-Party Vendor Hosts the Web Service

If the third-party vendor hosts the Tax Web Service, the vendor will integrate the Web service with their product's API.

Here is what your organization must do to connect to the vendor-hosted Web service:

1. If the vendor has modified any of AVS*.class or Tax*.class files in the Web service's tax.jar file, copy those modifications into your enterprise application. You can find the source code in:

   PORTAL_HOME\applications\wlcsApp\src\examples\wlcs\
   sampleapp\tax\

   Compile the source files.

2. Make any vendor-required modifications to the TaxCalculator EJB in your enterprise application so that it makes appropriate SOAP calls to the vendor's tax Web service. You can find the source code for the TaxCalculator EJB in the following files:

   PORTAL_HOME\applications\wlcsApp\src\examples\wlcs\
   sampleapp\tax\TaxCalculator*.java

   Compile the source files.

3. After you compile your source code, add the class files to the wlcsSample.jar in the wlcsApp application directory. When you add the class files to the JAR, make sure you maintain their relative directory structure.

4. Run the EJB compiler (ejbc) on the wlcsSample.jar file.

5. In the WebLogic Server Console for portalServer, select Deployments > Applications > wlcsApp > Service Configuration > Tax Service Client, and in the Tax Calculator WSDL field, modify the URL to the tax vendor's WSDL file. Click Apply in the Console to apply the new URL. The new URL is written to the following file: PORTAL_HOME\applications\wlcsApp\META-INF\
   application-config.xml.

   Note: At startup, WebLogic Server reads the application-config.xml file, so it knows where to find the Web service.

If Your Organization Hosts the Web Service

If your organization hosts the Tax Web Service, we strongly recommend that you deploy the Web service on a separate instance of WebLogic Server (that is, use a separate Java Virtual Machine [JVM]) than what your enterprise applications are running on. This way, your enterprise applications are insulated from failures or incidents in the Web service.

Here is what you must do if your organization hosts the Tax Web Service:

Caution: These are general, simplified guidelines for integrating with a vendor's API. In actual practice, such integration requires close collaboration with your vendor. We strongly recommend you contact your vendor for assistance.

1. Obtain your third-party vendor's tax calculation product API.

2. Modify the TaxWebService EJB (the Web service EJB) so that it translates SOAP calls into the language of the third-party product's API. You can find the source code for the TaxWebService EJB in the following files:

   PORTAL_HOME\applications\taxWSApp\src\examples\wlcs\
   sampleapp\tax\TaxWebService*.java

   Compile the source files.

3. After you have compiled the source code, replace the class files in tax.jar, located in the taxWSApp directory. When you add the class files to the JAR, make sure you maintain their relative directory structure.

4. Use the Web service generator (wsgen) on the tax.jar file to build a file called tax-webservice.war, as shown in Figure 5-3.

   For information on using wsgen, see Programming WebLogic Server Web Services at http://download.oracle.com/docs/cd/E13222_01/wls/docs61/webServices/index.html.

5. Make any necessary modifications to the TaxCalculator EJB in the wlcsApp application so that it makes appropriate SOAP calls to the TaxWebService EJB. You can find the source code for the TaxCalculator EJB in the following files:

   PORTAL_HOME\applications\wlcsApp\src\examples\wlcs\
   sampleapp\tax\TaxCalculator*.java

   Compile the source files.

6. After you compile your source code, add the class files to wlcsSample.jar in the wlcsApp application directory. When you add the class files to the JAR, make sure you maintain their relative directory structure.

7. Run the EJB compiler (ejbc) on the wlcsSample.jar file.

8. In the WebLogic Server Console for portalServer, select Deployments > Applications > wlcsApp > Service Configuration > Tax Service Client, and in the Tax Calculator WSDL field, modify the URL to the WSDL file. Click Apply in the Console to apply the new URL. The new URL is written to the following file: PORTAL_HOME\applications\wlcsApp\META-INF\
   application-config.xml.

   Note: At startup, WebLogic Server reads the application-config.xml file, so it knows where to find the Web service.