IBM® WebSphere® Commerce Customer Profile Sample

IBM® WebSphere® Commerce
Business Edition

Version 5.4

Last Updated: May 22, 2002

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
  customer_profile_sample
    beverageEJB.ear
      META-INF
    beverageEJB.jar
      META-INF
        Schema
    driver
      ear
        lib
        wctools.war
          tools
            segmentation
      META-INF
      wcs
        bin
        schema
          db2
          oracle
          xml
        xml
          tools
            segmentation
    java
      com
        ibm
          mycompany
            ejbs
            install
            membergroup
              commands
            tools
              segmentation
    packagedDriver

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
customer_profile_sample 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

customer_profile_sample This is the root directory for the sample application. beverageEJB.ear directory
beverageEJB.jar directory
driver directory
java directory
build.xml

beverageEJB.ear This directory contains the assets that will be built into the beverage enterprise archive. This archive is used to deploy the beverage enterprise bean. META-INF directory

beverageEJB.ear/META-INF This directory contains XML and XMI documents that contain meta information for the enterprise application. application.xml
ibm-application-bnd.xmi
ibm-application-ext.xmi

beverageEJB.jar This directory contains the assets that will be built into the beverage enterprise bean JAR. META-INF directory

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

beverageEJB.jar/META-INF/Schema This directory contains the Schema.dbxmi document that contains schema information for the beverage enterprise bean JAR. Schema.dbxmi

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

lib The compiled class files are contained in this directory. JSPs 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.
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.

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. Java source files are located in directories that model their package names.

packagedDriver This directory contains the packaged driver. The driver-yyyymmdd.jar file is located in this directory.

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 payed 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 customer_profile_sample 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. Then the beverageEJB.jar is packaged up into the beverageEJB.ear directory. Next, the beverageEJB.ear archive is packaged up into the driver directory. 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 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. Issue java -jar driver-yyyymmdd.jar 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. At a high level the utility performs the following tasks:

Unpackages the driver assets into their appropriate directories.
Modifies the commerce database schema to include any changes required by this application.
Updates the commerce database with configuration information.
Updates the instance configuration XML.
Updates the properties files.
Updates the classpath used by the application to include the new enterprise bean JAR.
Installs the enterprise application that contains the new enterprise bean JAR required by this application.

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.

MyResources.xml
MySegmentNotebook.xml
MySegmentNotebookB2B.xml

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. The enterprise bean is built and packaged into its own EAR file called beverageEJB.ear. During installation the deployed code for this enterprise bean is generated and the new enterprise application is installed. 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 VisualAge(R) for Java WebSphere

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.

Directory	Description	Contents
`WCS_Ref_Apps`	This directory corresponds to the VOB name. This is the root directory.	`buildjars` directory `customer_profile_sample` 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`
`customer_profile_sample`	This is the root directory for the sample application.	`beverageEJB.ear` directory `beverageEJB.jar` directory `driver` directory `java` directory `build.xml`
`beverageEJB.ear`	This directory contains the assets that will be built into the beverage enterprise archive. This archive is used to deploy the beverage enterprise bean.	`META-INF` directory
`beverageEJB.ear/META-INF`	This directory contains XML and XMI documents that contain meta information for the enterprise application.	`application.xml` `ibm-application-bnd.xmi` `ibm-application-ext.xmi`
`beverageEJB.jar`	This directory contains the assets that will be built into the beverage enterprise bean JAR.	`META-INF` directory
`beverageEJB.jar/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`
`beverageEJB.jar/META-INF/Schema`	This directory contains the Schema.dbxmi document that contains schema information for the beverage enterprise bean JAR.	`Schema.dbxmi`
`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
`lib`	The compiled class files are contained in this directory.	JSPs 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. `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.
`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.	Java source files are located in directories that model their package names.
`packagedDriver`	This directory contains the packaged driver.	The `driver-yyyymmdd.jar` file is located in this directory.