IBM® WebSphere® Commerce Customer Profile Sample


IBM® WebSphere® Commerce
Business Edition

Version 5.4 3Q Enhancement Pack


Last Updated: Jan 22, 2003

Introduction

This sample demonstrates how a new attribute can be added to the customer profile component. The new attribute is "beverage preference". This attribute is stored in a new table called "beverage" and a new enterprise bean is used to access this attribute. Once installed, marketing managers can use IBM WebSphere Commerce Accelerator to create and modify customer profiles that include the "beverage preference" attribute. A new panel called "Preferred beverage" will be added under the "Miscellaneous" tab in the "Customer Profiles" notebook.

There are two parts to adding a new attribute to the customer profiles component. The customer profile tool must be extended to allow the marketing manager to add the new attribute. This means that the Customer Profile Notebook in the IBM WebSphere Commerce Accelerator must be modified to have a new panel where the details of the new attribute can be specified. The second part to adding a new attribute is to customize the runtime evaluation of customer profiles so that the new attribute is recognized.

Building the sample

Here is the directory structure for the build tree for this sample:

WCS_Ref_Apps
  buildjars
  tools
  wsad_customer_profile
    driver
      ear
        lib
        wctools.war
          tools
            segmentation
      META-INF
      wcs
        bin
        schema
          db2
          oracle
          xml
        xml
          tools
            segmentation
    java
      com
        ibm
          mycompany
            install
    oracle
    os400
    packagedDriver
    workspace
      wcs.examples
        src
          java
            com
              mycompany
                membergroup
                  commands
                tools
                  segmentation
      WCSExample-ejb
        ejbModule
          com
            mycompany
              ejbs
          META-INF
            Schema

The following table describes the build tree directories in more detail.

Directory

Description

Contents

WCS_Ref_Apps

This directory corresponds to the VOB name. This is the root directory.

buildjars directory

wsad_customer_profile directory

buildjars

This directory contains dependency JAR files that are used to build the Java™ source in this project. These JARs are taken from the current version of IBM WebSphere Application Server and IBM WebSphere Commerce.

ivjejb35.jar
j2ee.jar
wcsejbimpl.jar
wcsejsclient.jar
wcslogging.jar
wcsmcruntime.jar
wcsruntime.jar
wcssfc.jar

tools

This directory contains tools files that are used to convert the EJB metadata files for Oracle and iSeries. These files are taken from the current version of IBM WebSphere Commerce. 

wcsconvert.jar

oracle.mapping

os400.mapping

wsad_customer_profile

This is the root directory for the sample application.

driver directory
java directory
oracle directory
packagedDriver directory
workspace directory
build.xml

driver

This directory contains the assets that will be built into the installable archive.

ear directory
META-INF directory
wcs directory

ear

This directory contains the assets that will be copied to the installed commerce enterprise archive directory.

lib directory
wctools.war directory
beverageEJB.DB2.jar
beverageEJB.Oracle.jar

lib

The compiled class files are contained in this directory.

Compiled class files used by this application.

wctools.war

This directory contains the assets that should be installed in the wctools.war directory in the installed enterprise archive directory.

JSPs used by this application.

driver/META-INF

This directory contains the MANIFEST.MF file for the driver JAR file.

MANIFEST.MF - indicates the Java class that should be invoked when the driver JAR is executed.

wcs

This directory contains assets that need to be installed in the root directory of IBM WebSphere Commerce.

xml directory
bin directory
schema directory

xml

This directory contains XML assets required by this application.

xml assets

bin

Executables required to install and configure this application.

profileSampleCreatedb.db2.bat - This script alters the commerce database schema for this application. This script is used if the database is DB2™ and the operating system is Windows™.

profileSampleCreatedb.db2.sh - This script alters the commerce database schema for this application. This script is used if the database is DB2 and the operating system is UNIX™.

profileSampleCreatedb.oracle.bat - This script alters the commerce database schema for this application. This script is used if the database is Oracle™ and the operating system is Windows.

profileSampleCreatedb.oracle.sh - This script alters the commerce database schema for this application. This script is used if the database is Oracle and the operating system is UNIX.

profileSampleDeploy.bat - This script generates the deployed code for the enterprise bean JAR and installs the application into the IBM WebSphere Application Server. This script is used if the operating system is Windows.

profileSampleDeploy.sh - This script generates the deployed code for the enterprise bean JAR and installs the application into the IBM WebSphere Application Server. This script is used if the operating system is UNIX.

profileSampleDeploy.os400.sh - This script generates the deployed code for the enterprise bean JAR and installs the application into the IBM WebSphere Application Server. This script is used if the operating system is iSeries.

profileSamplePopulatedb.db2.bat - This script populates the commerce database with configuration information. This script is used if the database is DB2 and the operating system is Windows.

profileSamplePopulatedb.db2.sh - This script populates the commerce database with configuration information. This script is used if the database is DB2 and the operating system is UNIX.

profileSamplePopulatedb.oracle.bat - This script populates the commerce database with configuration information. This script is used if the database is Oracle and the operating system is Windows.

profileSamplePopulatedb.oracle.sh - This script populates the commerce database with configuration information. This script is used if the database is Oracle and the operating system is UNIX.

profileSamplePopulatedb.os400.sh - This script populates the commerce database with configuration information. This script is used if the operating system is iSeries.

schema

Assets required to alter and populate the database.

db2 directory.
oracle directory.
xml directory.

schema/db2

SQL scripts specific to DB2.

profileSample.schema.sql - SQL script used to alter the commerce database schema.

schema/oracle

SQL scripts specific to Oracle.

profileSample.schema.sql - SQL script used to alter the commerce database schema.

schema/xml

Massloader XML documents.

profileSample.xml - Massloader import document used to populate the commerce database with configuration information for this application.

java

This directory contains the Java source for install utility.

Java source files are located in directories that model their package names.

oracle

This directory contains EJB meta information specifically for oracle.

The Oracle specific metadata files are located in this directory under workspace/WCSExample-ejb/ejbModule/META-INF:

Schema directory
ejb-jar.xml
ibm-ejb-jar-bnd.xmi
ibm-ejb-jar-ext.xmi
Map.mapxmi
Table.ddl

os400

This directory contains EJB meta information specifically for iSeries.

 

The iSeries specific metadata files are located in this directory under workspace/WCSExample-ejb/ejbModule/META-INF:

Schema directory
ejb-jar.xml
ibm-ejb-jar-bnd.xmi
ibm-ejb-jar-ext.xmi
Map.mapxmi
Table.ddl

packagedDriver

This directory contains the packaged driver.

The driver-yyyymmdd.jar file is located in this directory.

workspace

This directory contains the WebSphere Studio Application Developer workspace projects.

wcs.examples directory
WCSExample-ejb directory

workspace/wcs.examples

This directory is the WebSphere Studio Application Developer workspace for java project wcs.examples.

Java source files are located under src/java in directories that model their package names in WebSphere Studio Application Developer workspace.
.classpath
.project

workspace/WCSExample-ejb

This directory is the WebSphere Studio Application Developer workspace for ejb project WCSExample-ejb.

ejbModule directory
.classpath
.project

workspace/WCSExample-ejb/ejbModule

This directory contains the Java source and the assets that will be built into the beverage enterprise bean JAR.

Java source files are located in directories that model their package names in WebSphere Studio Application Developer workspace.
META-INF directory

workspace/WCSExample-ejb/ejbModule/META-INF

This directory contains XML and XMI documents that contain meta information for the enterprise bean JAR.

Schema directory
ejb-jar.xml
ibm-ejb-jar-bnd.xmi
ibm-ejb-jar-ext.xmi
Map.mapxmi
Table.ddl

workspace/WCSExample-ejb/ejbModule/META-INF/Schema

This directory contains the Schema.dbxmi document that contains schema information for the beverage enterprise bean JAR.

Schema.dbxmi

The contents of this source tree are available in the attached CustomerProfileSample.zip file. This zip file excludes dependency jars found in the buildjars directory. In order to run the build, you will need to copy these jars from your installation of IBM WebSphere Commerce Business Edition and IBM WebSphere Application Server and place them in the buildjars directory. The first two can be found in the IBM WebSphere Application Server lib directory. The other jars can be found in the lib and wc.ear/lib directories in the IBM WebSphere Commerce root directory.
ivjejb35.jar
j2ee.jar
wcsejbimpl.jar
wcsejsclient.jar
wcslogging.jar
wcsmcruntime.jar
wcsruntime.jar
wcssfc.jar

Special attention should be paid to the build.xml document. This example uses Apache Ant to perform the build. Ant is a Java-based build tool like the make tool. The build.xml document contains the instructions that Ant uses to build the application. To run this build you will need to download a copy of Ant and ensure that the ant/bin directory is in your path. Then make the wsad_customer_profile directory your current directory and issue ant. (For more information about Ant refer to http://jakarta.apache.org/ant/index.html.) The build.xml document contains additional documentation on the build process. The basic build process is to compile all of the Java source into a lib directory in the driver/ear directory. In this example, to demonstrate the flexibility, three different EJB jar files (beverageEJB.DB2.jar, beverageEJB.Oracle.jar and beverageEJB.OS400.jar) are packaged up into the driver/ear directory. The EJB metadata files and isolation level have been converted respectively before the generation of the EJB JAR. During your real development, considering the amount and size of EJBs, you may optionally generate only one EJB Jar file for your environment. The final step is to package the driver up into a jar file and place the jar in a directory called packagedDriver. Before you start the build you will need to ensure that java executable is in your path. You should ensure that the JDK you are using is the same as the one shipped with your version of IBM WebSphere Application Server.

Installing the sample

To install this sample, you must first install and configure IBM WebSphere Commerce V5.4 with 3Q Enhancement Pak and publish at least one store. Next, locate the driver-yyyymmdd.jar file in the packagedDriver directory and copy it to the system that has IBM WebSphere Commerce installed. Open a command prompt and ensure that java executable is in your path. This sample can be installed into either WAS or WSAD environment. Issue java -jar driver-yyyymmdd.jar was|wsad and provide the information that is requested.

To test that the application was successfully installed, log onto the IBM WebSphere Commerce Accelerator and click the "Customer Profiles" menu item under the "Marketing" menu. When the "Customer Profiles" list appears, click the "New..." button. When the notebook appears, click on the "Miscellaneous" tab. The new "Beverage preferences" tab should be visible under "Job function". Click the new tab to see the new panel. You should also refer to the log files that were created in the logs directory in the IBM WebSphere Commerce root directory for any problems during the install.

The install utility is part of the driver. It is packaged into the driver jar file and can be run by issuing java -jar driver-yyyymmdd.jar. The install utility source can be found in java/com/mycompany/install/InstallDriver.java.

To install the sample to WAS runtime environment, start WebSphere Application Server and stop Commerce Enterprise Application.

For Windows and UNIX, from command line, issue

java -jar driver-yyyymmdd.jar was

For iSeries,

Open an iSeries green session. Start QSHELL session by running: QSH. In QSH shell session, issue

java -Dos400.runtime.exec=QSHELL -jar driver-20030114.jar was

*Notes:* OS400 should be V5R2 and make sure PTF S107040 is applied. For V5R1 system, you have to run the SQL script manually to alter the schema before you run the above install command.

At a high level the utility performs the following tasks:

To install the sample to WSAD development environment, stop WebSphere Studio Application Developer. From command line, issue

java -jar driver-yyyymmdd.jar wsad

At a high level the utility performs the following tasks:

Examine this document for further information about what it does.

Customizations to the Customer Profile Notebook

The Customer Profile Notebook in the IBM WebSphere Commerce Accelerator is modified by this sample to allow the new "beverage preference" attribute to be specified by the marketing manager. A new panel called "Beverage preference" is added under the "Miscellaneous" tab on the left side of the Customer Profile Notebook. This new panel is implemented as a JSP. The name of the JSP is BeveragePanel.jsp. During the installation of this sample, the jsp is registered in the view registry and appropriate access control is assigned to the new view. For more details on this registration, refer to schema/xml/profileSample.xml.

Once the new view is registered, the XML document that describes the Customer Profile Notebook must be modified to add the new panel. The installation of this sample put three new XML documents in the xml/tools/segmentation directory in the IBM WebSphere Commerce root directory.

Compare these documents to Resources.xml, SegmentNotebook.xml, and SegmentNotebookB2B.xml which can be found in the same directory. You should see how the new panel was added to the Customer Profiles Notebook. The installation program also modified your instances/instanceName/xml/instanceName.xml document to point the segmentation component to the new MyResources.xml document instead of the original Resources.xml document.

The installation utility also modified the properties/com/ibm/commerce/tools/segmentation/Resources.properties file in the installed enterprise application to include the segmentNotebookBeveragePanel resource.

Customizations to SegmentSaveControllerCmd

SegmentSaveControllerCmd is the name of the controller command that saves a customer profile. This controller command was modified by extending the original implementation class and registering the new implementation class in the command registry. Refer to java/com/mycompany/tools/segmentation/MySegmentSaveControllerCmdImpl.java for details on how the controller command was customized. Refer to schema/xml/profileSample.xml for details on how the new implemenation was registered in the command registry.

Customizations to SegmentNotebookDataBean

SegmentNotebookDataBean is the name of the databean that is used to describe a customer profile. This data bean was modified by extending the original databean. Refer to java/com/mycompany/tools/segmentation/MySegmentNotebookDataBean for details on how this data bean was customized.

Customizations to SegmentConstraintListCmd

SegmentConstraintListCmd is a task command that provides the list of implicit constraints that make up a customer profile. This list is in HTML format and is displayed on the Customer Profile Summary page. The task command was modified be extending the original implementation class and registering the new implementation class in the command registry. Refer to java/com/mycompany/tools/segmentation/MySegmentConstraintListCmdImpl.java for details on how this task command was customized. Refer to schema/xml/profilsSample.xml for details on how the new implementation was registered in the command registry.

Customizations to CheckUserInMemberGroupCmd

CheckUserInMemberGroupCmd is a task command that checks to see if a user is in a member group. It is responsible for evaluating the implicit criteria for the member group to see if the user belongs to the member group. This task command was modified by extending the original implementation class and registering the new implementation class in the command registry. Refer to java/com/mycompany/membergroup/commands/MyCheckUserInMemberGroupCmdImpl.java for details on how this task command was customized. Refer to schema/xml/profilsSample.xml for details on how the new implementation was registered in the command registry.

The new Beverage enterprise bean

The new "beverage preference" attribute is to be stored in a table called "beverage". For details on how this table is defined refer to schema/db2/profileSample.schema.sql. This table is accessed by a new enterprise bean called Beverage. The source can be found in the java/com/mycompany/ejbs directory. During installation the deployed code for this enterprise bean is generated and added to the existing enterprise application. In order to assign beverage preferences to users, you will need to insert new rows into this table.


Trademarks and Service Marks

The following are trademarks or registered trademarks of IBM Corporation in the United States and other countries:

AIX      DB2      IBM     WebSphere      WebSphere Studio Application Developer   

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Windows, Windows NT and  Windows 2000 are trademarks of Microsoft Corporation in the United States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.

**************************************************************************
 
** © COPYRIGHT INTERNATIONAL BUSINESS MACHINES CORPORATION 2002
 
** ALL RIGHTS RESERVED.
 
**************************************************************************

Note to US Government Users -- Documentation related to restricted rights -- Use, duplication, or disclosure is subject to restriction set forth in GSA ADP Schedule Contract with IBM Corp.

End of document.