Setting Up Commerce Services

Among the important commerce services available with WebLogic Portal are those that pertain to such business transaction services as taxation and payment and the product catalog service. Development tasks associated with these services include integrating both local and third-party taxation services and integrating local and third-party payment services. For the product catalog service, development tasks include loading data into the catalog database and creating and enhancing a custom catalog service.

This section includes information on the following subjects:

Integrating a Portal with Business Transaction Services

WebLogic Portal can be integrated with such business transaction services as taxation and payment services. Adding these services to a portal extends the functionality of the portal by allowing it to leverage external services for use locally. Integrating these services is a development function, requiring you to update specific EJBs in the enterprise application and URLs specific configuration files. Those modifications are described in this document.

This section includes information on the following subjects:

Integrating with a Taxation Service

The Tax Web service installed with WebLogic Portal provides a default framework for handling tax calculations on transactions received from the default TaxCalculator EJB. The business methods implement a standard workflow that is associated with the completion of order taxation. (The Tax Web service is itself 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.

Important Notice 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.

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 program's API, and modify the TaxWebService EJB inside the Web service to translate the SOAP calls—the SOAP calls your enterprise application's TaxCalculator EJB sends it to the Web service—into messages their API can understand, and to create proper return SOAP calls to your TaxCalculator EJB.

To connect to the vendor-hosted Web service, use this procedure:

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, deploy the Web service on a separate Java Virtual Machine (JVM) than what your enterprise applications are running on. This way, if the Web service goes down and freezes the JVM it is running on, your enterprise application's JVM will continue to run.

To connect to a Tax Web service hosted by your organization, use this procedure:

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

Integrating with a Payment Service

The Credit Card Web service that is installed with WebLogic Portal provides a default framework for handling authorization, capture, and settlement of credit card transactions received from the default CreditCardService EJB. The business methods implement a standard workflow that is associated with the completion of credit card transactions. The current state of the transaction is maintained and each action is logged. (The Credit Card Web service is itself a stateless session EJB wrapped in code that makes it a Web service.)

Integrating your enterprise applications with the Payment Web service involves modifying either the CreditCardService EJB or the Credit Card Web service, depending on who will host the Web service: your organization or the third-party payment vendor.

Important Notice The default Payment Web service that ships with WebLogic Portal always sends payment information through without any errors, as if it were connected to and approved by a third-party payment service. This default processing of payment is not designed for production use. You must integrate with your third-party vendor's payment service to process payment correctly.

If the Third-Party Vendor Hosts the Web Service

If the third-party vendor hosts the Credit Card Web service, the vendor will integrate the Web service with their program's API, and modify the CreditCardWebService EJB inside the Web service to translate the SOAP calls—the SOAP calls your enterprise application's CreditCardService EJB sends to the Web service—into messages their API can understand, and to create proper return SOAP calls to your CreditCardService EJB.

To connect to the vendor-hosted Credit Card Web service, use this procedure:

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

Important Security Information

Since a Web services is SOAP (that is, XML over HTTP), you are passing credit card information over the Web in plain text. Hackers listening in can track this information for nefarious purposes. BEA strongly recommends that you set up a dedicated line to the credit card processing provider and add a Secure Socket Layer (SSL) to the HTTP communication taking place. You should also choose a credit card provider that encrypts all communications.

If Your Organization Hosts the Web Service

If your organization hosts the Credit Card Web service, we strongly recommend that you deploy the Web service on a separate Java Virtual Machine (JVM) than what your enterprise applications are running on. This way, if the Web service goes down and freezes the JVM it is running on, your enterprise application's JVM will continue to run.

To connect to a Credit Card Web service hosted by your organization, use this procedure:

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

Guidelines for Modifying the Credit Card Web Service EJB

The Payment service EJB is a stateless session bean that provides services related to the authorization, capture, and settlement of credit card transactions. The Credit Card Web service EJB serves as an interface behind which integrations with various payment solutions can be implemented. The current state of each transaction is maintained and each action is journaled. General characteristics of transactions are described in the following list:

Supporting a Product Catalog

This section includes information on the following subjects:

Loading Your Product Data Into the Product Catalog Database Schema

The most important development tasks is to get information about your products into a form that WebLogic can understand. Use the DBLoader program to do this. The DBLoader lets you load, all at once, any data into any table in a database.

Creating your product catalog by using the DBLoader requires these steps:

Step 1: Prepare to Use DBLoader

Before you can add your product information to the database, consider the following database issues, and prepare your input files.

Review Important Database Considerations

Some important database considerations that you should keep in mind while using the DBLoader program are:

Consider Referential Integrity and Constraints The schema for the Product Catalog enforces data and referential integrity between tables with the use of constraints. For example, the primary key constraint on WLCS_PRODUCT and WLCS_CATEGORY, or the foreign key constraint on WLCS_PRODUCT_CATEGORY.

Primary keys and unique indexes prevent the possibility of placing duplicate entries in the table. Foreign key constraints ensure referential integrity by making certain that the parent key already exists before allowing the child record to be written to the database.

Note: For every WLCS_PRODUCT and WLCS_CATEGORY table entry, a corresponding entry in the CATALOG_ENTITY table must also be made.

Consider Strings in Java All Strings in Java are represented as a series of Unicode 2.0 characters. Unicode 2.0 is a 16-bit character encoding that supports the world's major languages. Therefore, when reading text into and writing text out of the JVM, an encoding scheme must be used to convert the "native" encoding used by the operating system to or from Unicode 2.0. Data in text files is automatically converted to Unicode 2.0 when its encoding matches the default file encoding of the Java Virtual Machine (and that of the operating system).

Prepare Product Information Input Files to Load Into the Product Catalog Schema

Follow the rules in this section to create input files (text files) containing your product information that you want to use in your Web site. Create a separate file for every database table.

Verify Input File's File Structure The input data file is, by default, a comma-separated value (CSV) text file. The input file has the following structure:

Verify the dbloader.properties File Structure The dbloader.properties file has the following structure.

Listing 14-1 Simple dbloader.properties Input File

3,WLCS_PRODUCT
*SKU,NAME,IN_STOCK,EST_SHIP_TIME,SPECIAL_NOTES,CREATION_DATE
   VARCHAR,VARCHAR,VARCHAR,VARCHAR,VARCHAR,DATE
P123,CoolKid,N,Out of stock until further notice,Special order
   only,02-Oct-2000
P124,FastKid,Y,One week,No special order,02-Oct-2000
P125,RadSneakers,Y,,regular stock,02-Oct-2000

Note: DATE column values should always be entered in the format DD-MMM-YYYY. It cannot be an empty string. Its values are either NULL or a valid date.

Empty input strings Empty input strings from the data file are inserted into database as empty strings. You must account for each unspecified column in the input record by including the delimiter character (by default, a comma) in the correct position (matching the position of the columns you listed in line 2, the column names). For example:

P125,RadSneakers,Y,,regular stock,02-Oct-2000

Unspecified values for non-primary-key fields In the previous example a value for the fourth identified column (EST_SHIP_TIME) was not specified. This condition is acceptable because this column is not a primary key for the database record. The column's value is stored as an empty string.

Note: If you intend to store a null value in the database for a non-primary-key column, you should enter NULL in the correct position for the column in that record. Do not enclose NULL in quotes as that will cause the column to be stored as a string.

Step 2: Edit the dbloader.properties File

The DBLoader uses the information in the dbloader.properties file to determine information about the data and loading process, including what driver, database, or login to use. Locate the dbloader.properties file in the PORTAL_HOME directory and make sure it contains the right settings.

Any comment lines in the dbloader.properties file are prefixed with the # character. Both comment lines and blank lines are allowed.

Table 14-2

Now that you have created the input files and set up the dbloader.properties file correctly, run the loaddata script to start the DBLoader program.

Review loaddata Basics

The script is located at:

Note: PORTAL_HOME is the directory where you installed WebLogic Portal.

The loaddata script performs the tasks:

Prepare to Run the Script

Before you can run the loaddata script, make sure that the set-environment script specifies the same database as the dbloader.properties file. The set-environment script resides in the same directory as the loaddata script. For example, if the dbloader.properties file uses `jdbc:pointbase:Commerce' connections, then set-environment script should have SET DATABASE=POINTBASE.

As mentioned earlier, DBLoader runs independently of the WebLogic Portal server. Therefore you do not need to stop the server if you are planning to run the loader.

If you are running the WebLogic Portal server with Oracle, then the drawback might be a slower performance for the time the data is being loaded into the database.

Note: You might want to back up the particular tables that you are about to update before running DBLoader. The DBLoader program does not keep history records in the database.

Run the loaddata Script

The command to run the script has the following format:

>> loaddata { -insert | -update | -delete } input-file.csv

For example:

>> loaddata -update product_categories.csv

In the previous example, the DBLoader program will update rows in the product catalog database that match the primary keys specified in the category.csv input file.

Selecting the type of operation You must select one of the three possible operations: -insert, -update, or -delete.

UNIX and privileges On UNIX systems, the loaddata.sh file needs to have its default protections set to include execute privilege. A typical way to do this is with the command:

$ chmod +x loaddata.sh

Loading data into several tables To insert, update, or delete data in several tables, run the loaddata script separately for each table, providing the corresponding input filename as a parameter. The order of tables being updated should use the same data integrity rules as all other SQL statements. For example, insert rows into the parent table with the primary key constraint before inserting rows into the child table with the foreign key constraint.

Step 4: Troubleshoot Using the DBLoader Log Files

You can determine errors and other issues that occurred during any particular DBLoader operation by using the two audit trail log files:

This section contains the following information:

Determine When to Review the Files

You must check the files immediately after each operation; the files are overwritten by each DBLoader operation. Both files are created in the same directory where you run the loaddata script.

Review the dbloader.log File

The dbloader.log file contains the following information:

Review the dbloader.err File

If any errors occurred during the attempted database load operation, the dbloader.err file captures the following information:

All errors and exceptions are displayed in the console where the DBLoader program is running. Records with errors in them will be skipped, and the processing continues until the end of the file. (The program does not roll back a transaction if an error has occurred.)

Showing a Catalog in a JSP

The JavaServer Page (JSP) templates and JSP tags included in the Commerce services allow you to easily create the presentation part of the Product Catalog. The templates provide the mechanism for your visitors to view a catalog's categories and product items; the JSP tags in the templates implement that functionality.

JSP tag libraries allow you to easily retrieve the attributes of items and categories in the Product Catalog. You can then format these attributes using HTML tags. Any HTML editor can be used to create custom layouts. You can also include custom Java code within the JSPs to display categories and items.

To use the Catalog JSP tags, you need to import the cat.tld tag library into your JSP file by including the following code in the JSP:

<%@ taglib uri="cat.tld" prefix="catalog" %>

Three basic tags are used in the JSP templates that compose the default product catalog supplied by BEA. These tags are:

You can add additional tags as necessary to meet your business needs.

Using the <catalog:getProperty> Tag

Listing 14-2 Retrieving the Detail JSP Information From an Item

<%@ taglib uri="cat.tld" prefix="catalog" %>

<catalog:getProperty
object="<%= item %>"
   propertyName="Jsp"
   getterArgument=
   "<%= new Integer(ProductItem.DETAILED_DISPLAY_JSP_INDEX) %>"
   id="detailJspInfo"
returnType="com.beasys.commerce.ebusiness.catalog.JspInfo"
/>

Note: Because the getterArgument must be a run-time expression, we assign MyCatalog to a String variable and use the variable as the value to the getterArgument.

Listing 14-3 Using the getterArgument Attribute

<%@ taglib uri="cat.tld" prefix="catalog" %>

<% 
String myPropertySetName = "MyCatalog"; 
ProductItem myProductItem = .....; // reference to a ProductItem
%>
<catalog:getProperty
   object="<%=myProductItem%>
   propertyName="color"
   getterArgument="<%=myPropertySetName%>"
/>

Using the <catalog:iterateViewIterator> Tag

Listing 14-4 Displaying Keys of Categories in a ViewIterator

<%@ taglib uri="cat.tld" prefix="catalog" %>

<catalog:iterateViewIterator
   iterator="<%= myIterator %>"
   id="category"
   returnType="com.beasys.commerce.ebusiness.catalog.Category">
   <%= category.getKey().toString() %>
</catalog:iterateViewIterator>

Listing 14-5 Displaying all Views in a ViewIterator

<%@ taglib uri="cat.tld" prefix="catalog" %>

<catalog:iterateViewIterator 
   iterator="<%= myIterator %>" 
   id="view"
   returnType="com.beasys.commerce.ebusiness.catalog.ViewIterator"
   iterateByView="true">
   <%= view.toString() %>
</catalog:iterateViewIterator>

Using the <catalog:iterateThroughView> Tag

Listing 14-6 Displaying Keys of All ProductItems in Current View of ViewIterator

<%@ taglib uri="cat.tld" prefix="catalog" %>

<catalog:iterateThroughView
   iterator="<%= myIterator %>"
   id="item"
   returnType="com.beasys.commerce.ebusiness.catalog.ProductItem">
<%= item.getKey().toString() %>
</catalog:iterateThroughView>

Listing 14-7 Displaying Keys of All ProductItems in First View of ViewIterator

<%@ taglib uri="cat.tld" prefix="catalog" %>

<catalog:iterateThroughView
   iterator="<%= myIterator %>"
   id="item"
   returnType="com.beasys.commerce.ebusiness.catalog.ProductItem"
   viewIndex="new Integer(0)">
   <%= item.getKey().toString() %>
</catalog:iterateThroughView>

Hooking Up a Catalog to a Shopping Cart

To hook up a catalog to a shopping cart, you need to implement the shoppingcart.jsp template in the catalog. This template contains code that manages a shopping cart service, including implementations of the necessary input processors and pipeline components used to manage much of the business logic and back-end tasks required to successfully execute the shopping cart service. You can either implement this template as BEA provides it or you can tailor it to meet your specific needs.

Implementing shoppingcart.jsp

To implement shopppingcart.jsp, first, ensure that this JSP is stored in the appropraite portlets folder for the application. Then, do one of the following:

OR

How shoppingcart.jsp Works

Customers can arrive at shoppingcart.jsp template from any product catalog page by clicking View Cart (or its equivalent) on that page. The shoppingcart.jsp template displays the items currently in a customer's shopping cart. For each item the customer added to their cart (that is still actively part of the current purchase), the shoppingcart.jsp template displays the quantity, the item name, the list price, the actual price, a savings amount, and a subtotal. Following this information, a total price for the order is displayed.

The item quantity is shown in an editable field, allowing customers to change the quantity of the item simply by typing a new quantity and clicking Update. For your customers' convenience, the item name is hyperlinked back to its description in the product catalog. For each item in the shopping cart, there is also a Delete button and a Buy Later button. Clicking Delete removes the item from the shopping cart, while clicking Buy Later causes the item to be moved from the Shopping Cart to the Saved Items list. For each item shown in the Saved Items list, the hyperlinked item name and a brief description are displayed. Additionally, Delete and Add to Cart in this section allows your customers to remove the item altogether or to move it back to their active Shopping Cart.

If customers click a link to an individual product item to review detailed information about that product item, the next page is the appropriate product catalog page. If they click on Update, Empty Cart, Delete, or Save for Later, they are returned to the shopping cart page (shoppingcart.jsp) after the appropriate input processor or pipeline has been executed to record the modification.

If the customer is satisfied with the contents of their shopping cart as shown on this page, the customer can initiate the checkout process by clicking Check Out. If this is the case, the next page is the shipping information page (shipping.jsp).

Notes: If the customer has not yet logged into the site and clicks Check Out, the customer will be prompted to log in at the login.jsp template (prior to loading the shipping.jsp template).