e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

An IBM Redbook Publication
IBM Redbook Form Number: SG24-6180-00
ISBN: 073842367X
ISBN: 9780738423678
Publication Date: 04-Dec-2001
Find Similar Download

Related People

John Ganci - Author [+5] [-5]
Sanjoy Banik - Author
Fabrizio Boaglio - Author
Ashish Cowlagi - Author
Miroslav Holecy - Author
Siva Kumar - Author

Abstract

The Patterns for e-business are a group of proven, reusable assets that can be used to increase the speed of developing and deploying Web applications. The pattern discussed in this IBM Redbooks publication, Electronic Commerce composite pattern, identifies the interaction of users with enterprise B2C Web sites that sell goods and services.

Part 1 of the book guides you through the process of selecting an Application and Runtime pattern. Next, the platform-specific product mappings are identified based upon the selected Runtime pattern.

Part 2 of the book provides a set of guidelines for building your e-commerce application. These guidelines include e-business life cycle, technology options, application design, application development, systems management and security.

Part 3 of the book teaches you by example how to implement many common customizations needed by a B2C e-commerce Web site that requires back-end integration. The customization examples highlight the key technologies and features of a B2C e-commerce Web site, such as JSPs, commands, EJBs, security and user management (LDAP), MQSeries and e-mail messaging, order customizations, personalization, auctions, catalog management, and managing a store.

Language

English

Table of Content

Part 1. Electronic Commerce composite pattern
Ch 1. Introduction
Ch 2. Selecting the application pattern
Ch 3. Selecting the runtime pattern
Ch 4. Selecting the product mapping

Part 2. Electronic Commerce composite pattern: guidelines
Ch 5. e-business life cycle
Ch 6. Technology options
Ch 7. Application design guidelines
Ch 8. Application development guidelines
Ch 9. Systems management and security guidelines

Part 3. B2C working example
Ch 10. B2C store working example
Ch 11. User management and security
Ch 12. Catalog management
Ch 13. Order customizations
Ch 14. Messaging integration
Ch 15. Personalization
Ch 16. Auctions
Ch 17. Managing a store

Part 4. Appendix
Appendix A. Use cases
Appendix B. Loader package
Appendix C. WebSphere Commerce Analyzer


ibm.com/redbooks
e-commerce Patterns for
Building B2C Web Sites
Using IBM WebSphere Commerce Suite V5.1
John Ganci
Sanjoy Banik
Fabrizio Boaglio
Ashish Cowlagi
Miroslav Holecy
Siva Kumar
Selecting the application and runtime
patterns for your B2C Web site
Design, development and
deployment guidelines
B2C e-commerce
customization examples
Front cover


e-commerce Patterns for Building B2C Web Sites
Using IBM WebSphere Commerce Suite V5.1
November 2001
International Technical Support Organization
SG24-6180-00

© Copyright International Business Machines Corporation 2001. All rights reserved.
Note to U.S Government Users – Documentation related to restricted rights – Use, duplication or disclosure is subject to
restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
First Edition (November 2001)
This edition applies to WebSphere Commerce Suite V5.1, for use with Windows NT, Windows
2000, AIX, and Solaris.
Comments may be addressed to:
IBM Corporation, International Technical Support Organization
Dept. HZ8 Building 662
P.O. Box 12195
Research Triangle Park, NC 27709-2195
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the
information in any way it believes appropriate without incurring any obligation to you.
Take Note! Before using this information and the product it supports, be sure to read the
general information in “Special notices” on page 591.

© Copyright IBM Corp. 2001
iii
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiii
The team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiii
Notice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
IBM trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvi
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvi
Part 1. Electronic Commerce composite pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
Chapter 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 Electronic commerce overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
1.1.1 Concepts of e-commerce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.2 e-commerce models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 IBM Framework for e-business. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
1.2.1 Framework overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2.2 Framework architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2.3 Framework Web application programming model. . . . . . . . . . . . . . . . 9
1.2.4 Framework e-business domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3 Patterns for e-business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
1.3.1 Patterns for e-business overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.3.2 How to use the Patterns for e-business . . . . . . . . . . . . . . . . . . . . . . 14
1.3.3 Selecting the Business pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.3.4 Selecting the Application pattern. . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.3.5 Selecting the Runtime pattern. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.3.6 Selecting the product mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.3.7 Applying the guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.4 Electronic Commerce composite pattern . . . . . . . . . . . . . . . . . . . . . .18
Chapter 2. Selecting the Application pattern . . . . . . . . . . . . . . . . . . . . . . . 21
2.1 Application pattern 1 (Web-up). . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
2.1.1 Application pattern 1: business drivers. . . . . . . . . . . . . . . . . . . . . . . 22
2.1.2 Application pattern 1: key features . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.1.3 Application pattern 1: considerations . . . . . . . . . . . . . . . . . . . . . . . . 23
2.1.4 Application pattern 1: example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.2 Application pattern 2 (Enterprise-out). . . . . . . . . . . . . . . . . . . . . . . . .24
2.2.1 Application pattern 2: business drivers. . . . . . . . . . . . . . . . . . . . . . . 25
2.2.2 Application pattern 2: key features . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.2.3 Application pattern 2: considerations . . . . . . . . . . . . . . . . . . . . . . . . 26
2.2.4 Application pattern 2: example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

iv
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Chapter 3. Selecting the Runtime pattern. . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.1 Runtime pattern overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
3.2 Runtime pattern tiers and nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
3.2.1 Outside world . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.2.2 Demilitarized Zone (DMZ). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.2.3 Internal network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.3 Runtime pattern 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
3.3.1 Runtime pattern 1: example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.4 Runtime pattern 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
3.4.1 Runtime pattern 2: example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Chapter 4. Selecting the product mapping. . . . . . . . . . . . . . . . . . . . . . . . . 47
4.1 Runtime pattern 1: product mapping. . . . . . . . . . . . . . . . . . . . . . . . . .49
4.1.1 Runtime pattern 1: product mapping - Windows NT/2000 . . . . . . . . 49
4.1.2 Runtime pattern 1: product mapping - AIX . . . . . . . . . . . . . . . . . . . . 50
4.1.3 Runtime pattern 1: product mapping - Solaris. . . . . . . . . . . . . . . . . . 51
4.2 Runtime pattern 2: product mapping. . . . . . . . . . . . . . . . . . . . . . . . . .52
4.2.1 Runtime pattern 2: product mapping - Windows NT/2000 . . . . . . . . 53
4.2.2 Runtime pattern 2: product mapping - AIX . . . . . . . . . . . . . . . . . . . . 54
4.2.3 Runtime pattern 2: product mapping - Solaris. . . . . . . . . . . . . . . . . . 55
Part 2. Electronic Commerce composite pattern: guidelines . . . . . . . . . . . . . . . . . . .57
Chapter 5. e-business life cycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.1 IBM Global Services Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
5.1.1 Standard Work Product Descriptions . . . . . . . . . . . . . . . . . . . . . . . . 61
5.1.2 Engagement models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.1.3 Custom Application Development phases . . . . . . . . . . . . . . . . . . . . 62
5.2 Rational Unified Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
5.3 e-business life-cycle phases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
5.3.1 Requirements phase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
5.3.2 Solution outline phase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
5.3.3 High-level design phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
5.3.4 Low-level design phase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.3.5 Development phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
5.3.6 Test phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
5.3.7 Deployment phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
5.3.8 Operations phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Chapter 6. Technology options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
6.1 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
6.1.1 Web browser client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
6.1.2 Java applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
6.1.3 Application client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Contents
v
6.1.4 Mobile client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
6.2 Web application server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
6.2.1 Java Servlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.2.2 JavaServer Pages (JSPs). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.2.3 JavaBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.2.4 Enterprise JavaBeans (EJBs). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
6.3 Commerce Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
6.3.1 WebSphere Commerce Suite architecture . . . . . . . . . . . . . . . . . . . . 97
6.3.2 Development technology considerations . . . . . . . . . . . . . . . . . . . . 101
6.3.3 Runtime technology considerations . . . . . . . . . . . . . . . . . . . . . . . . 106
6.4 Connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
6.4.1 Java Database Connectivity (JDBC). . . . . . . . . . . . . . . . . . . . . . . . 108
6.4.2 Java Messaging Service (JMS). . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
6.4.3 Java Transaction API (JTA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
6.4.4 Java Naming and Directory Interface (JNDI) . . . . . . . . . . . . . . . . . 110
6.4.5 XML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
6.4.6 Common Connector Framework (CCF) . . . . . . . . . . . . . . . . . . . . . 111
6.4.7 Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
6.4.8 Electronic Commerce Markup Language (ECML) . . . . . . . . . . . . . 112
6.5 Where to find more information . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
Chapter 7. Application design guidelines. . . . . . . . . . . . . . . . . . . . . . . . . 115
7.1 WebSphere Commerce Suite programming model. . . . . . . . . . . . . .116
7.1.1 Enterprise JavaBeans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
7.1.2 Model-View-Controller application structure. . . . . . . . . . . . . . . . . . 117
7.1.3 Error handling and messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
7.1.4 Application session management. . . . . . . . . . . . . . . . . . . . . . . . . . 122
7.1.5 Access control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
7.2 Requirements specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
7.3 Use case model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
7.4 Navigation flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
7.5 Application component design . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
7.5.1 JSP design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
7.5.2 Controller command design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
7.5.3 Task command design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
7.5.4 Data bean design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
7.5.5 Entity bean design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Chapter 8. Application development guidelines . . . . . . . . . . . . . . . . . . . 147
8.1 Development tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
8.1.1 Development tools for customization needs. . . . . . . . . . . . . . . . . . 150
8.1.2 WebSphere Commerce Studio. . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
8.1.3 Other development tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

vi
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
8.2 Development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
8.2.1 Team development strategies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
8.2.2 Development environment installation . . . . . . . . . . . . . . . . . . . . . . 161
8.2.3 Team development environment with VisualAge for Java . . . . . . . 163
8.2.4 Team development with WebSphere Commerce Studio . . . . . . . . 163
8.2.5 Publishing targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
8.2.6 Packaging a SAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
8.2.7 Source Control Management and build guidelines. . . . . . . . . . . . . 168
8.2.8 Unit testing guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
8.3 Commerce application development. . . . . . . . . . . . . . . . . . . . . . . . .174
8.3.1 JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
8.3.2 Properties files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
8.3.3 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
8.3.4 Enterprise JavaBeans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
8.3.5 XML data files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
8.3.6 SQL scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
8.3.7 Where to start? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Chapter 9. Systems management and security guidelines. . . . . . . . . . . 203
9.1 Systems management guidelines overview . . . . . . . . . . . . . . . . . . .204
9.1.1 Managing your WebSphere Commerce Site. . . . . . . . . . . . . . . . . . 205
9.1.2 WebSphere resource management . . . . . . . . . . . . . . . . . . . . . . . . 206
9.2 System management tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
9.2.1 WebSphere Application Server Administrator’s Console . . . . . . . . 206
9.2.2 WebSphere Commerce Suite. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
9.2.3 WebSphere Commerce Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . 219
9.2.4 SecureWay Directory management . . . . . . . . . . . . . . . . . . . . . . . . 222
9.2.5 HTTP Server Administration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
9.2.6 DB2 UDB Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
9.3 Security guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227
9.3.1 Physical systems security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
9.3.2 Operating systems security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
9.3.3 Network security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
9.3.4 Web application security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
9.3.5 WebSphere security model and policy . . . . . . . . . . . . . . . . . . . . . . 234
9.4 Backup and recovery guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . .237
9.4.1 Strategies for backup and recovery . . . . . . . . . . . . . . . . . . . . . . . . 237
9.4.2 Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
9.4.3 Web assets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
9.4.4 Configuration files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
9.4.5 Development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Part 3. B2C working example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245

Contents
vii
Chapter 10. B2C store working example. . . . . . . . . . . . . . . . . . . . . . . . . . 247
10.1 B2C store working example overview. . . . . . . . . . . . . . . . . . . . . . .248
10.2 Runtime environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
10.3 Development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
10.4 Test environment guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
10.5 Sample code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258
10.6 Create the base store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259
10.7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
Chapter 11. User management and security . . . . . . . . . . . . . . . . . . . . . . 261
11.1 User management and security guidelines. . . . . . . . . . . . . . . . . . .262
11.1.1 Customer registration and profile management . . . . . . . . . . . . . . 262
11.1.2 Member security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
11.1.3 Member groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
11.2 Member subsystem architecture. . . . . . . . . . . . . . . . . . . . . . . . . . .266
11.2.1 Member registration and profile management . . . . . . . . . . . . . . . 267
11.2.2 Member groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
11.2.3 Member security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
11.2.4 Commerce Suite components of member subsystem . . . . . . . . . 281
11.3 Implementation examples overview . . . . . . . . . . . . . . . . . . . . . . . .282
11.3.1 ITSO sample store user requirements . . . . . . . . . . . . . . . . . . . . . 282
11.3.2 Solution overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
11.4 Use case 1: online user registration . . . . . . . . . . . . . . . . . . . . . . . .286
11.4.1 Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
11.4.2 Component identification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
11.4.3 Component study and implementation . . . . . . . . . . . . . . . . . . . . . 287
11.4.4 Deployment and testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
11.5 Use case 2: user registration using LDAP . . . . . . . . . . . . . . . . . . .291
11.5.1 Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
11.5.2 Solution overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
11.5.3 High-level implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
11.5.4 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
11.6 Use case 3: user registration using MQSeries . . . . . . . . . . . . . . . .297
11.6.1 Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
11.6.2 Solution overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
11.6.3 High-level implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
11.6.4 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Chapter 12. Catalog management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
12.1 Catalog design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304
12.1.1 Catalog hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
12.2 Strategies for loading the store catalog . . . . . . . . . . . . . . . . . . . . .308
12.2.1 Data preprocessing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

viii
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
12.2.2 Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
12.2.3 Propagation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
12.3 Data management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323
12.3.1 Add products, items, and offer price. . . . . . . . . . . . . . . . . . . . . . . 323
12.3.2 Remove products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Chapter 13. Order customizations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
13.1 Order subsystem overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .330
13.1.1 Order state diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
13.1.2 Common order customizations. . . . . . . . . . . . . . . . . . . . . . . . . . . 339
13.2 Reorder example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .344
13.2.1 Summary of ITSO store requirements . . . . . . . . . . . . . . . . . . . . . 344
13.2.2 Solution outline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
13.3 Use case 1: reorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .349
13.4 Use case 2: set scheduled orders. . . . . . . . . . . . . . . . . . . . . . . . . .353
13.5 Use Case 3: browse/delete scheduled orders. . . . . . . . . . . . . . . . .355
13.6 Deployment of reorder customization. . . . . . . . . . . . . . . . . . . . . . .359
Chapter 14. Messaging integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
14.1 Messaging subsystem architecture. . . . . . . . . . . . . . . . . . . . . . . . .362
14.1.1 Commerce Suite inbound messaging system. . . . . . . . . . . . . . . . 362
14.1.2 Commerce Suite outbound messaging system. . . . . . . . . . . . . . . 368
14.2 MQSeries back-end integration example . . . . . . . . . . . . . . . . . . . .371
14.2.1 High-level implementation steps. . . . . . . . . . . . . . . . . . . . . . . . . . 373
14.3 Newsletter example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
14.3.1 Deployment of components for the newsletter application . . . . . . 395
Chapter 15. Personalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
15.1 Personalization overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .400
15.1.1 Rules-based personalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
15.1.2 Collaborative personalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
15.2 Personalization in WebSphere Commerce Suite. . . . . . . . . . . . . . .403
15.2.1 Campaigns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
15.2.2 Customer profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
15.2.3 Discounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
15.2.4 Implementation example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
15.3 Awareness advertising. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .412
15.3.1 Designing the initiative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
15.3.2 Defining and creating the ad copy. . . . . . . . . . . . . . . . . . . . . . . . . 413
15.3.3 Defining and creating the e-marketing spots. . . . . . . . . . . . . . . . . 415
15.3.4 Creating the awareness initiative . . . . . . . . . . . . . . . . . . . . . . . . . 417
15.3.5 Implementation example - awareness advertisement. . . . . . . . . . 418
15.4 Suggestive selling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .430
15.4.1 Designing the initiative . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

Contents
ix
15.4.2 Defining and creating e-marketing spots. . . . . . . . . . . . . . . . . . . . 431
15.4.3 Creating the suggestive selling initiative. . . . . . . . . . . . . . . . . . . . 432
15.4.4 Implementation example - suggestive selling. . . . . . . . . . . . . . . . 434
15.5 Campaign reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .440
Chapter 16. Auctions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
16.1 Negotiation subsystem overview . . . . . . . . . . . . . . . . . . . . . . . . . .444
16.2 Auctions in WebSphere Commerce Suite. . . . . . . . . . . . . . . . . . . .447
16.2.1 Benefits of auctions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
16.2.2 Types of auctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
16.2.3 Auction rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
16.2.4 Auction style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
16.2.5 Autobids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
16.2.6 Enable scheduler jobs for auctions. . . . . . . . . . . . . . . . . . . . . . . . 450
16.2.7 CreateAuction command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
16.2.8 CleanJob command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
16.2.9 Delete obsolete auction records . . . . . . . . . . . . . . . . . . . . . . . . . . 453
16.3 Auction example overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .453
16.3.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
16.3.2 Solution outline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
16.3.3 Auction example use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
16.4 Use case 1: create the ITSO store auction. . . . . . . . . . . . . . . . . . .455
16.4.1 Activate the job scheduler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
16.4.2 Install the sample auction files . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
16.4.3 Update the VIEWREG table for auctions . . . . . . . . . . . . . . . . . . . 459
16.4.4 Create an auction from Commerce Suite Accelerator. . . . . . . . . . 461
16.4.5 Verify the auction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
16.5 Use case 2: integrate the auction and ITSO store. . . . . . . . . . . . . .474
16.5.1 Provide links from the ITSO store and auction . . . . . . . . . . . . . . . 476
16.5.2 Replace frames with JSP includes . . . . . . . . . . . . . . . . . . . . . . . . 482
16.5.3 Create same look and feel for auction and ITSO store. . . . . . . . . 484
16.5.4 Verify the auction and ITSO store integration. . . . . . . . . . . . . . . . 487
Chapter 17. Managing a store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
17.1 I/T specialist roles and tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . .490
17.1.1 Network administrator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
17.1.2 System administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
17.1.3 Site administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
17.1.4 Store administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
17.1.5 Database administrator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
17.2 Business user roles and tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . .504
17.2.1 Order clerk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
17.2.2 Customer service representative . . . . . . . . . . . . . . . . . . . . . . . . . 507

x
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
17.2.3 Marketing manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
17.2.4 Merchandising manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
17.2.5 Merchant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
17.3 Reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .518
17.3.1 What is IBM WebSphere Commerce Analyzer?. . . . . . . . . . . . . . 519
17.3.2 High-evel implementation steps . . . . . . . . . . . . . . . . . . . . . . . . . . 520
17.3.3 Business reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
17.3.4 Inventory report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Part 4. Appendixes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .529
Appendix A. Use cases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
UC#2 logon with LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .532
UC#2 user login authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
UC#3 user profile update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
UC#4 reorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
UC#5 order schedule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
UC#6 scheduled order deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Appendix B. Loader package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
Loader package components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .540
Load process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Installation on remote machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Sample data load. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
Loader usage considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
Appendix C. WebSphere Commerce Analyzer. . . . . . . . . . . . . . . . . . . . . 555
Pre-installation requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .556
Creating the required Commerce Suite shared folders. . . . . . . . . . . . . . . 556
Commerce Suite HTML relative report path . . . . . . . . . . . . . . . . . . . . . . . 557
Information required during installation. . . . . . . . . . . . . . . . . . . . . . . . . . . 557
Controlling access to the business reports. . . . . . . . . . . . . . . . . . . . . . . . 558
Default printer on the Commerce Analyzer server . . . . . . . . . . . . . . . . . . 560
Installing WebSphere Commerce Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Configuring WebSphere Commerce Analyzer. . . . . . . . . . . . . . . . . . . . . . . . 562
Commerce Analyzer Configuration Manager . . . . . . . . . . . . . . . . . . . . . . 563
Required configuration for Commerce Analyzer. . . . . . . . . . . . . . . . . . . . 564
Configuring WebSphere Commerce Suite . . . . . . . . . . . . . . . . . . . . . . . . 566
Creating the datamart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
Preparing the datamart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
Configuring the Brio Broadcast Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 570
Configuring the warehouse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570
Configuring the extraction scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571
Changing the store, language, or currency. . . . . . . . . . . . . . . . . . . . . . . . 573

Contents
xi
Post configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
Configure startup parameters for the Brio Broadcast Server . . . . . . . . . . 574
Logging into the Warehouse Center. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
Update passwords in DB2 Warehouse. . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Update password for the Start Brio Agent. . . . . . . . . . . . . . . . . . . . . . . . . 577
Scheduling the extraction process to run daily . . . . . . . . . . . . . . . . . . . . . 577
Automate data extraction process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
Running the extraction process the first time . . . . . . . . . . . . . . . . . . . . . . 579
Verifying WebSphere Commerce Analyzer. . . . . . . . . . . . . . . . . . . . . . . . 580
Saving copies of the business reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
Appendix D. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
System requirements for downloading the Web material . . . . . . . . . . . . . 584
How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
IBM Redbooks collections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
Special notices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593

xii
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
xiii
Preface
The Patterns for e-business are a group of proven, reusable assets that can be
used to increase the speed of developing and deploying Web applications. The
pattern discussed in this redbook, Electronic Commerce composite pattern,
identifies the interaction of users with enterprise B2C Web sites that sell goods
and services.
Part 1 of the redbook guides you through the process of selecting an Application
and Runtime pattern. Next, the platform-specific product mappings are identified
based upon the selected Runtime pattern.
Part 2 of the redbook provides a set of guidelines for building your e-commerce
application. These guidelines include e-business life cycle, technology options,
application design, application development, systems management and security.
Part 3 of the redbook teaches you by example how to implement many common
customizations needed by a B2C e-commerce Web site that requires back-end
integration. The customization examples highlight the key technologies and
features of a B2C e-commerce Web site such as JSPs, commands, EJBs,
security and user management (LDAP), MQSeries and e-mail messaging, order
customizations, personalization, auctions, catalog management, and managing
a store.
The team that wrote this redbook
This redbook was produced by a team of specialists from around the world
working at the International Technical Support Organization, Raleigh Center.

xiv
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 0-1 The IBM Redbook team (first row: Sanjoy Banik, Siva Kumar, Ashish Cowlagi; second row: John
Ganci, Fabrizio Boaglio, Miroslav Holecy).
John Ganci is a Senior Software Engineer, WebSphere Specialist at the IBM
ITSO, Raleigh Center. He writes extensively and teaches classes on WebSphere
and related topics. John has 14 years of experience in product and application
design, development, system testing, and consulting. His areas of expertise
include e-commerce, personalization, pervasive computing, and Java
programming. Before joining the ITSO, he developed e-commerce sites for IBM.
Sanjoy Banik is an e-commerce consultant with Infinity Solutions Limited in New
Zealand. He has five years of experience in electrical and electronics
engineering, including the electro medical sector, and nine years of experience in
I/T fields, including teaching computer science. He holds a Master's degree in
Computer Science from University of Auckland and a Bachelor’s degree in
Electrical and Electronics Engineering from Bangladesh Institute of Technology.
His areas of expertise include e-business solutions with Java and Microsoft
architecture.

Preface
xv
Fabrizio Boaglio is an I/T Specialist in the Centre for IBM e-business Innovation
in Milan, Italy. He has two years of experience in the e-business field. He holds a
degree in Management Engineering from Polytechnic of Turin. His areas of
expertise include Enterprise Java programming, team programming and B2B
e-commerce solutions.
Ashish Cowlagi is the team leader for IBM WebSphere Commerce education in
the US. He has over four years of experience with developing and architecting
enterprise applications, primarily using Java. He holds a Bachelor’s degree in
Electrical Engineering from the University of Poona in India. His areas of
expertise include J2EE-based application design and architecture, focused on
WebSphere and VisualAge for Java.
Miroslav Holecy is an I/T Specialist in IBM Sweden. He has five years of
experience in the e-business design and development. His areas of expertise
include application design, e-commerce, and Enterprise Java programming.
Siva Kumar is a Software Engineer with IBM Global Services in India. He has
four years of experience in the I/T field. He holds a Master’s degree in
Technology from Indian Institute of Technology, Madras. His areas of expertise
include networking, Internet security, e-business and middleware.
Thanks to the following people for their contributions to this project:
Jonathan Adams, IBM UK
Bob Fraser, IBM Canada
Mark Ho, IBM Canada
Asha Mishra, IBM Canada
Ramiah Tin, IBM Canada
Jacob Vangergoot, IBM Canada
Janette Wong, IBM Canada
Darshanand Khusial, IBM Canada
Paul Tanner, IBM Australia
Michal Jordan-Rozwadowski, IBM Canada
Notice
This publication is intended to help I/T architects, I/T specialists, developers and
consultants who design, develop, test, deploy, and manage e-commerce Web
sites using WebSphere Commerce Suite V5.1. The information in this publication
is not intended as the specification of any programming interfaces that are
provided by WebSphere Commerce Suite V5.1, Pro Edition, or WebSphere
Commerce Studio V5.1, Professional Developer Edition for Windows NT and
Windows 2000.

xvi
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
See the PUBLICATIONS section of the IBM Programming Announcement for
WebSphere Commerce Suite V5.1, Pro Edition (specific platform), and
WebSphere Commerce Studio V5.1, Professional Developer Edition for Windows
NT and Windows 2000 for more information about what publications are
considered to be product documentation.
IBM trademarks
The following terms are trademarks of the International Business Machines
Corporation in the United States and/or other countries:
Comments welcome
Your comments are important to us!
We want our IBM Redbooks to be as helpful as possible. Send us your
comments about this or other Redbooks in one of the following ways:
Use the online Contact us review redbook form found at:
ibm.com/redbooks
Send your comments in an Internet note to:
redbook@us.ibm.com
Mail your comments to the address on page ii.
e (logo)®
IBM ®
AIX
AS/400
DB2
DB2 Universal Database
Home Director
HotMedia
MQSeries
Net.Data
OS/2
OS/390
PC 300
RS/6000
Redbooks
Redbooks Logo
S/390
SecureWay
SP
SP1
SupportPac
VisualAge
WebSphere
Lotus
Approach
Domino
eSuite
Notes

© Copyright IBM Corp. 2001
1
Part 1
Electronic
Commerce
composite
pattern
Part 1

2
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
3
Chapter 1.
Introduction
The technology demands of e-business require an accelerated approach to
application design, development and deployment. Great advances in software
and hardware development have been made by the use of standards and
well-specified components for assembly. The desire to apply the concepts of
software design patterns enable an efficiency in the design and implementation
of software applications and infrastructure.
IBM has developed a series patterns called the Patterns for e-business, which
aim to communicate in a highly accessible fashion the Business pattern,
Application pattern, Runtime pattern, product mapping, and design and
development guidelines required for different classes of applications.
This book describes how to design and develop Business-to-Consumer (B2C)
e-commerce Web sites, using IBM WebSphere Commerce Suite V5.1, by
providing guidelines and customization examples based on the IBM Framework
for e-business and Patterns for e-business.
1

4
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
1.1 Electronic commerce overview
In order to be competitive in the global marketplace, businesses need to offer
greater levels of customer service and support than ever before. When
customers access a Web site today, they expect to be able to browse a product
catalog, buy the products online in a secure environment, and have the product
delivered to their doorstep.
WebSphere Commerce Suite V5.1 is designed to provide a complete solution for
a company’s electronic commerce needs. The product as a whole has evolved to
meet the needs of a rapidly changing market; it is constructed to incorporate
many of the concepts which are now integral to business over the Internet.
e-commerce
Electronic commerce or e-commerce involves doing business online, typically via
the Web. The terms e-business, e-tailing, and i-commerce are often used
synonymously with e-commerce. e-commerce implies that goods and services
can be purchased online, whereas e-business might be used as more of an
umbrella term for a total presence on the Web, which includes the e-commerce
component on a Web site.
m-commerce
Simply put, m-commerce is e-commerce using a mobile device such as a mobile
phone, wireless PDA, or wireless laptop. Mobile commerce or m-commerce
refers to the use of mobile devices to partially or completely perform a
transaction electronically from a commerce Web site for the exchange of goods
and services for monetary consideration.
The key distinction between m-commerce and e-commerce at present is the use
of a mobile device with a Web browser to access the commerce Web site,
instead a more traditional PC Web browser client. In the future, mobile devices
will become so common for electronic commerce that there will probably not be a
distinction (m-commerce).
For more detailed information about m-commerce, refer to Mobile Commerce
Solutions Guide using WebSphere Commerce Suite V5.1, SG24-6171.
1.1.1 Concepts of e-commerce
Some of the key concepts of an e-commerce Web site include the following:
User profile

Chapter 1. Introduction
5
Most B2C sites try to maintain information about users. They encourage
users to register. Information entered, as well as information gathered during
the users’ visits, form the user profile. The user profile information can be
used as a powerful marketing tool, to personalize the Web site content for the
the user. The personalized content can be used to filter the product catalog
for only products that the customer is interested in, or implement such selling
techniques as cross-selling and up-selling.
Product catalog
A product catalog on the Web is analogous to a printed catalog. Products are
organized into logical groups, and the display of the products are tailored to
maximize the sales of the products. Customers can browse the catalog to
search for products and then place orders.
Shopping flow
A shopping flow in the e-commerce environment is the process where
customers browse the catalog, select products, and purchase the products.
Shopping cart
The metaphor of a shopping cart has become widely used on the Web to
represent an on-line order basket. Customers browse an e-commerce site
and add products to their shopping carts. Shoppers proceed to the check-out
to purchase the products in their shopping carts.
1.1.2 e-commerce models
As e-commerce has evolved, two major types of store models have emerged:
Business-to-Consumer (B2C), and Business-to-Business (B2B). WebSphere
Commerce Suite supports both of these models. Another popular e-commerce
model is the auction model.
Business-to-Consumer (B2C)
The Business-to-Consumer (B2C) e-commerce store model, is a publicly
accessible Web site offering products for sale. It is analogous to a store on the
street, where any member of the public can walk in and make a purchase. A new,
unknown customer is called a guest shopper. The guest shopper has the option
of making purchases, after providing some general information about themselves
to fulfill the transaction (name, address, credit card, etc.). Most B2C sites
encourage users to register and become members. In doing so, the business can
establish a relationship with the customer, provide better service, and build
customer loyalty.

6
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Business-to-Business (B2B)
The Business-to-Business (B2B) e-commerce store model refers to an
e-commerce store specifically designed for organizations to conduct business
over the Internet. The two entities are known to each other and all users are
registered. B2B applications can streamline operations between businesses. For
example, a retailer can place orders from a supplier B2B Web site. This type of
e-commerce model greatly increases the speed and efficiency of the buying
process between businesses.
Auctions
Auctions can be incorporated into B2C or B2B models. Alternatively, auction
e-commerce stores can stand alone. Sites dedicated to auctions act as brokers,
facilitating relationships between buyers and sellers. Auctions are a well-known
way of moving surplus merchandise.
1.2 IBM Framework for e-business
An e-business connects business systems to customers, employees, suppliers,
and distributors to the Web for the following reasons:
Improve time to market
Access a broader base of customers and suppliers
Improve efficiency
Reduce costs
To achieve these benefits, existing businesses must transform their traditional
business processes with e-business applications. New businesses, sometimes
called “NetGens”, can adopt e-business applications from the beginning to
achieve the same benefits.
The IBM Framework for e-business, often referred to as the Framework, is at the
core of IBM's e-business strategy to help the customers build, run and manage
e-business applications.
1.2.1 Framework overview
The IBM Framework for e-business is based on the following principles:

Chapter 1. Introduction
7
Industry-standard technologies
The Framework is based on multi-platform, multi-vendor standards such as
Java, XML, HTML, Linux, and CORBA. It includes the client, application
server, network, data and infrastructure standards that make it possible for a
client to access services and data anywhere in the network. This model
simplifies application development and deployment by enabling developers to
write an application once and deploy it to any supported platform.
Proven methodologies
When building on existing I/T investments and mission-critical applications, it
is highly beneficial to reuse proven methodologies for quick action to capture
business opportunities and respond to market challenges.
The methodologies are built on the experiences of IBM architects, specialists,
and consultants and tested solutions. In addition, the proven methodologies
are further researched, refined and documented by the IBM Patterns for
e-business to make it easier to apply the technologies, standards, and
products of the IBM Framework for e-business.
The Patterns for e-business leverage the Framework by providing guidelines
for selecting the Business pattern, Application pattern, Runtime pattern,
product mapping, design, and development.
Leadership products
The IBM WebSphere middleware, DB2 data management software, Lotus
collaboration software, and Tivoli management software provide industry
leading solutions and a solid foundation for e-business applications. The IBM
software products can be implemented on a wide range of servers with
scalability in mind as the needs of your e-business grow.
1.2.2 Framework architecture
Figure 1-1 displays a summary of the key architecture elements of the IBM
Framework for e-business.

8
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 1-1 IBM Framework for e-business architecture
Web clients
Clients based on the Web browser model include traditional PC Web browser
clients and mobile clients such as WAP or i-mode mobile phones and PDAs.
Network infrastructure
Network infrastructure provides a platform for the entire e-business
environment and includes TCP/IP and network services, security services,
directory services, and file and print services. The supported standards
include TCP/IP, CDSA, SSL, IPSec, x.509v3 certificates, LDAP, AFS/DFS,
and IPP.
Application server
Application servers provide the core function for developing and supporting
the e-business application logic. This includes HTTP servers, J2EE
application servers, mail and community services, groupware services,
database services, transaction services, and messaging services.
Application Server
Software
Application
Integration
Systems Management
Network Infrastructure
Web Application Programming
Environment
e-business Application Services
Clients
Web Application
Servers
Content
Tools
External Services
Mobile
Device

Chapter 1. Introduction
9
Application integration
The Web enables e-businesses to leverage existing I/T investments.
Application integration also allows disparate applications, potentially written in
different programming languages and built on different architectures, to
communicate with each other within an enterprise and across enterprises.
e-business application services
e-business application services are higher-level application-oriented
components, such as e-commerce services, that conform to the Framework
for e-business programming model. These services allow e-business
solutions to be developed faster with higher quality.
Systems management services
These services support the end-to-end management across networks,
systems, middleware, and applications.
Development tools
Development tools enable the creation, deployment, and management of
e-business applications. It also supports integrating third-party tools into the
development process.
1.2.3 Framework Web application programming model
The IBM Framework for e-business Web application programming model
highlights the software tools and products used to build, run, and manage
e-business applications, as seen in Figure 1-2.
Figure 1-2 IBM Framework for e-business Web application programming model
Windows AIX Linux HP-UX Solaris OS/400 OS/390
Development
Tools and
Components
Application
Server
Software
Secure Network
and Management
Software
Build
Manage
Run
Application Framework

10
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Build: development tools and components
VisualAge for Java is used by programmers to develop Java assets,
WebSphere Studio is used by Web developers and designers to create Web
pages, and WebSphere Business Components provides the reusable
components for accelerated development and deployment.
Run: application server software
Lotus Notes/Domino is used for collaboration, WebSphere Application Server
is used for Web application logic and presentation, DB2 is used for data
management, and WebSphere MQ is used for integration and work flow.
Manage: secure network and management software
Tivoli products are used to provide a secure network and systems
management.
The benefits of developing applications using the IBM Framework for e-business
Web application programming model are as follows:
Maximize ease and speed of development and deployment.
Accommodate any client device. Support of Internet standards and a
server-centric model expands access to your e-business applications to a
broad range of client devices.
Ensure portability across a diverse server environment. Support of the open,
unifying Java platform makes it easier to deploy your e-business applications
on the systems that best meet your scalability needs and quality of service
requirements.
Leverage and extend existing assets. To improve time to market and reduce
cost of development, e-business applications must leverage and extend the
reach of secure, reliable, and scalable applications that are the core of many
business processes.
1.2.4 Framework e-business domain
IBM has worked with over 20,000 customers to build e-business applications and
solutions. The IBM e-business domains have been classified as follows (see
Figure 1-3)
Problem domain
Represents IBM’s classification of the main e-business problem areas.
Solution domain
This highlights the technologies and products used to develop a solution for
the identified problem domains.
Design domain

Chapter 1. Introduction
11
Resolves the design issues related to developing e-business applications and
solutions.
Figure 1-3 Framework solution domain
Additional information on the IBM Framework for e-business can be found at:
http://www.ibm.com/software/ebusiness
1.3 Patterns for e-business
By definition, a pattern is a model or plan used as a guide in making similar
components. The concept of patterns to solve software problems is not new. IBM
over the past couple of years has developed the Patterns for e-business, which
are a group of reusable assets or patterns that can help speed the process of
developing and deploying Web applications.
Customer Relationship
Management
e-Commerce
Enterprise Application
Integration
Supply Chain
Management
Business Intelligence
e-business
Problem Space
DB2,IntelligentMiner,
Visual Warehouse
MQSeries family,
Domino,BPF,B2B
Server,e-Commerce
Integrator
MQSeries Family,
Domino Workflow
WebSphere
Commerce and
related products
IBM HTTP Servers,
Studio,VAJ
WebSphere,Domino,
Performance Pack
Data Integration,
Warehousing,Mining
Queries,Analysis
XML,Message
Brokers,XML/EDI,
OBI,RosettaNet
Online Shopping,
ECML,Secure
Payments
HTTP,HTML,Java,
Web,Application
Servers,Client/Server,
Driven,Performance,
EJB,CORBA,TP
Monitors,XML
Technology/Product
Space
Systems Management
Design Space
Client
Enterprise
Data and
Applications
Network
Server
Application
Server
Performance
Security
Business Integration
(EAI,XML),Workflow
Collaboration
e-mail
Instant messaging
Lotus Notes/Domino
Lotus Sametime

12
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
The Patterns for e-business consist of the following types of patterns:
Business solutions
– Business patterns
Business patterns are used to identify high-level constructs for the primary
business solution.
– Integration patterns
Integration patterns provide solutions by integrating multiple Business
patterns.
– Composite patterns
Composite patterns represent commonly occurring combinations of
Business patterns and Integration patterns.
Application patterns
Application patterns define the high-level application components and flow for
refining the Business pattern.
Runtime patterns
Runtime patterns are used to define the logical middleware nodes used to
implement the Application pattern.
1.3.1 Patterns for e-business overview
The job of an I/T architect is to evaluate business problems and design a solution
based on the requirements and inputs of the customer. It is a great advantage to
the architect to capture the experiences of I/T architects.
IBM has made many advances in the area of patterns, in part by the work done in
the Enterprise Solution Structure (ESS) Architecture. ESS looks at patterns from
a complete end-to-end system architecture point of view. ESS promotes the
assembly of proven designs and components from an ever-growing and evolving
repository. ESS is part of the IBM Global Services Methodology.
For more information on ESS see “Enterprise Solutions Structure” in the IBM
Systems Journal, Volume 38, No. 1, 1999, found at:
http://www.research.ibm.com/journal/sj38-1.html
The Patterns for e-business capture the experiences of I/T architects by storing
the knowledge gained in a repository. The knowledge is further researched and
tested to develop Business patterns and lower-level patterns to save time and
money on future customer engagements.

Chapter 1. Introduction
13
These approaches are further refined into useful, tangible guidelines. The
patterns and their associated guidelines allow the architect to start with a
problem and a vision, find a conceptual pattern that fits this vision, define the
necessary functional pieces that the application will need to succeed, and then
actually build the application using coding techniques outlined in the guidelines.
At the highest level, the Business patterns define the possible business
interactions required for a solution. The business function will typically fall into
one or more of these defined Business patterns. A Business pattern describes
the relationship between the users, the business organization or applications,
and the data to be accessed.
Business patterns
There are four primary Business patterns:
Self-service business pattern
The Self-service business pattern, formerly known as the User-to-Business
pattern, describes situations where users are interacting with a business
application to view or update data.
Collaboration business pattern
The Collaboration business pattern, formerly known as the User-to-User
pattern, describes the interaction between users, including e-mail and
workflow processes.
Information Aggregation business pattern
The Information Aggregation business pattern, formerly known as the
User-to-Data pattern, describes situations where users access and
manipulate large amounts of data collected from multiple sources.
Extended Enterprise business pattern
The Extended Enterprise business pattern, formerly known as the
Business-to-Business pattern, describes the programmatic interaction
between two distinct businesses.
Note: For a more detailed look at patterns for software reuse, we recommend
the book Patterns for e-business: A Strategy for Reuse, by Jonathan Adams,
Srinivas Koushik, Guru Vasudeva, George Galambos, published by IBM
Press, ISBN: 1-931182-02-7, which many parts of this redbook are based
upon.

14
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Integration patterns
It would be very convenient if all problems fit nicely into the four primary Business
patterns. In reality things are often more complicated. When a business problem
describes multiple objectives that fit into multiple Business patterns, the Patterns
for e-business provide Integration patterns.
The following Integration patterns tie multiple Business patterns together:
Access Integration pattern
The Access Integration pattern provides for front-end integration of multiple
services and information through a common portal. The pattern is responsible
for handling multiple client device types, single sign-on, personalization, and
providing a common look and feel for the application interfaces.
Application Integration pattern
The Application Integration pattern provides for the seamless back-end
integration of multiple applications and data without the user accessing them
directly.
Composite patterns
Composite patterns represent commonly occurring combinations of Business
patterns and Integration patterns.
We refer to the combination of Business and Integration patterns identified in the
field as a Composite pattern. The makeup of Composite patterns varies and can
easily be extended to meet additional criteria.
Some common examples of Composite patterns are as follows:
Electronic Commerce composite pattern (focus of this redbook)
Account Access composite pattern
Portal composite pattern
Buy-side Hub composite pattern
Sell-side Hub composite pattern
Trading Exchange composite pattern
1.3.2 How to use the Patterns for e-business
Once the Business pattern, Integration pattern, or Composite pattern has been
identified, the next step is to define the high-level logical components that make
up the solution and how these components interact. This is known as the
Application pattern. A Business pattern will usually have multiple Application

Chapter 1. Introduction
15
patterns identified that describe the possible logical components and their
interactions. For example, an Application pattern may have logical components
that describe a presentation tier for interacting with users, a Web application tier,
and a back-end application tier.
Next, the Application pattern is further refined and broken down into one or more
Runtime patterns. Runtime patterns define functional nodes that represent
middleware functions that must be performed. The Application pattern exists as
an abstract representation of high-level functions, whereas the Runtime pattern
is a more concrete representation of the functions that must be performed, such
as the network structure to be used, systems management features, load
balancing and security.
Once a Runtime pattern has been identified, the next step is to determine the
product mapping of each node for the given operating system platform.
The next major phase is the use of the pattern guidelines to assist you in creating
the application using best practices that have been identified through experience.
Figure 1-4 depicts the Patterns for e-business flow and components.

16
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 1-4 Patterns for e-business flow
1.3.3 Selecting the Business pattern
When faced with the challenge of designing a solution for a business problem,
the first step is to take a high-level view of the goals you are trying to achieve. A
proposed business scenario should be described and each element should be
matched to an appropriate Business pattern. You may find that the total solution
will require one or more Business patterns.
In our case, the Electronic Commerce pattern is an example of a Composite
pattern, which contains elements of nearly all of the Business patterns and
Integration patterns. This pattern was formally known as the User-to-Online
Buying pattern. The e-commerce composite pattern is more fully described in
1.4, “Electronic Commerce composite pattern” on page 18.
Runtime
Patterns
Application
Patterns
Business &
Integration
Patterns
Best Practice Guidelines
Technology Options
Systems Management
Security
Application Design
Product
Mappings
Composite
Patterns
Application Development
Performance

Chapter 1. Introduction
17
1.3.4 Selecting the Application pattern
Application patterns break the application down into the most basic conceptual
components, identifying the goal of the application. They do not show
middleware, files, or the databases where Web pages may be stored.
For more detailed information on selecting an Application pattern, refer to
Chapter 2, “Selecting the Application pattern” on page 21.
1.3.5 Selecting the Runtime pattern
The Application pattern needs to be underpinned by middleware functions. Each
function is associated with a runtime node. In reality these functions, or nodes,
can exist on separate physical machines or may co-exist on the same machine.
In the Runtime pattern this is not relevant. The focus is on the logical nodes
required and their placement in the overall network structure.
For example, let us assume that our customer has determined that its business
requirements fit into the Electronic Commerce composite pattern and that
Application pattern 1 is the most descriptive of the scenario. The next step is to
determine the appropriate Runtime pattern for the Application pattern.
For more detailed information on selecting a Runtime pattern, refer to Chapter 3,
“Selecting the Runtime pattern” on page 29.
1.3.6 Selecting the product mapping
The last step in defining the network structure for the application is to instantiate
real product names and versions with one or more Runtime pattern nodes. The
product mappings are oriented toward a particular platform, though more likely,
the customer will have a variety of platforms involved in the network. In this case,
it is simply a matter of mix and match.
For more detailed information on selecting a Runtime pattern product mapping,
refer to Chapter 4, “Selecting the product mapping” on page 47.
1.3.7 Applying the guidelines
The Application patterns, Runtime patterns, and Runtime pattern product
mappings are intended to guide you in defining the application requirements and
the network layout. The actual application development has not been addressed
yet. Part 2 of this redbook provides guidelines for the Electronic Commerce
composite pattern, including the following:
Technology options

18
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
These guidelines provide knowledge on the technology options to consider
when developing e-commerce and Web applications.
Application design guidelines
These guidelines instruct architects and developers on best practices for
designing B2C e-commerce applications.
Application development guidelines
These guidelines provide the developer with knowledge to implement a
development environment and to develop the customized assets of the store.
Systems management guidelines
These guidelines address the day-to-day operational concerns, including
security, backup and recovery, and application management.
More information on the Patterns for e-business can be found at:
http://www.ibm.com/developerworks/patterns/
1.4 Electronic Commerce composite pattern
The Electronic Commerce composite pattern refers to a common example of a
integrating multiple Business patterns and Integration patterns to create a
composite pattern. This redbook instantiates the Electronic Commerce
composite pattern for B2C e-commerce Web sites. With a typical B2C
e-commerce Web site, products are sold through a catalog using such
components as user registrations, shopping navigation, shopping carts, and
payment using credit cards or electronic wallets.
The Electronic Commerce composite pattern utilizes a Self-Service business
pattern. However the catalog itself must be created by aggregating the products,
pricing, and marketing literature - and distilling it into the catalog itself, constitutes
an Information Aggregation pattern.
This pattern can also includes links to back-end systems allowing for inventory
updates, order processing, delivery systems, and credit checking. B2C
e-commerce Web sites that require back-end integration and messaging, known
as Enterprise-out, may include all of the Business and Integration patterns. Sites
that need to be implemented very quickly to enable Web-based buying without
close integration with back-end systems are known as Web-up.
Some common industries using the Electronic Commerce composite pattern
include the following:
Retail

Chapter 1. Introduction
19
Banking
Finance
Insurance
Travel
B2C e-commerce solutions allow enterprises to reach new customers and
manage transactions electronically. Consumers can purchase in confidence
knowing their transactions are secure and their privacy is protected.
In Part 3 of the redbook, we provide a B2C working example store that includes
many common store customizations. The customization examples highlight the
principles from the guidelines section of the redbook. In addition, the working
example chapters includes component-level design considerations and sample
code to implement the specific business function.

20
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
21
Chapter 2.
Selecting the Application
pattern
The selection of an Application pattern is based on the selected Business
pattern, Integration pattern, or Composite pattern. The Application patterns use
logical nodes to illustrate various ways to configure the interaction between
users, applications and data. The focus is on the application layout, shape, and
application logic for the associated data.
The Electronic Commerce composite pattern includes two Application patterns:
Application pattern 1 (Web-up)
The premise is to very quickly enable Web-based buying without close
integration with back-end systems.
Application pattern 2 (Enterprise-out)
The idea is to extend an existing order processing system to a new
Web-based online buying with integration and re-use of back-end systems.
The Application patterns have been implemented using the following criteria:
Business drivers
Key features
Considerations
Example
2

22
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
2.1 Application pattern 1 (Web-up)
Application pattern 1 (Web-up), for the Electronic Commerce composite pattern,
is applicable in a situation where you are building a new application and there is
no need to interface with legacy or third-party applications or data. All of the
required data is handled by the new e-business application. This Application
pattern does not require sharing, accessing or exchanging data with other
applications. The application implements all the required functions and does not
rely on functionality provided by other existing applications. Application pattern 1,
as seen in Figure 2-1, illustrates a 3-tier Web-up e-commerce application with
deferred access to the third tier.
Figure 2-1 Application pattern 1 (Web-up)
2.1.1 Application pattern 1: business drivers
This Application pattern is used by businesses that may have extensive existing
systems, but do not wish to invest the time to make the modifications or
interfaces necessary to allow those systems to be used directly by the new
Web-based online buying channel. This Application pattern provides some other
method to submit and confirm orders, either manual or batch.
Presentation
asynchronous
Read/write data
Application node
containing new or
modified components
Application node
containing existing
components with no
need for modification
or which cannot
be changed
Transient data
* work in progress
* cached committed
* staged
synchronous asynchronous
Application
2
Application
Application
1
Presentation

Chapter 2. Selecting the Application pattern
23
The main reasons for this approach are speed to market and cost of
implementation. The objective is to get the front-end shopping and buying site
implemented quickly and postpone worrying about smooth interfaces to the
back-end systems. This is known as a Web-up approach to e-commerce.
2.1.2 Application pattern 1: key features
Application pattern 1 represents a target Application pattern for many Web-up
application server vendors. It provides the ability for one or more point-to-point
connections to back-end legacy applications or databases. In the future the
e-commerce application can be more easily integrated with existing back-end
applications (for example an ERP or inventory management system). The
examples reviewed for this Application pattern typically involve some form of
deferred interaction with the back-end processing of the orders.
2.1.3 Application pattern 1: considerations
As the B2C e-commerce Web site becomes more successful, the site will need
better integration interfaces to back-end systems. In addition, the site may
require more real-time functionality, such as immediate delivery confirmation.
The site will probably evolve into an Application pattern 2 type of implementation
as described in 2.2, “Application pattern 2 (Enterprise-out)” on page 24.
When developing an Application pattern 1 (Web-up), many vendors promote
ease of development by mixing the presentation and business logic layers. This
type of development should be avoided, since separation promotes the effective
use of discrete skill sets and code reuse. Failing to separate the business and
presentation logic can lead to code that is hard to maintain and extend.
2.1.4 Application pattern 1: example
A major retail department store wishes to extend its reach to a Web sales
channel. As competition is keen, time to market is crucial. Existing infrastructure
includes a telephone sales channel and a back-end order processing system that
runs in batch. Currently green-screen point-of-sale terminals are used for online
transactions by the sales staff. In the short-term, modifications to the back-end
system are not feasible. The department store chooses Application pattern 1
because this Application pattern does not require back-end modification.

24
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
2.2 Application pattern 2 (Enterprise-out)
Application pattern 2 (Enterprise-out) for the Electronic Commerce composite
pattern applies to scenarios where there is the need for integration with legacy or
third-party applications. The new application is not built as a stand-alone
solution, but instead needs to integrate with existing applications. The integration
can be achieved on a functional basis or a data basis using a transaction
interface or a data interface.
When trying to integrate with an existing application, it is important to research
whether the application needs to be modified, and determine if the changes are
allowed. If the new application needs to use existing data you must determine if
the data can be used “as is” or if the structure needs to be changed, and if so, if
this modification is possible.
Application pattern 2, as seen in Figure 2-2, illustrates an Enterprise-out 3-tier
e-commerce application with online access to the third tier, although an
additional (fourth) decomposition tier may be added as displayed.
Figure 2-2 Application pattern 2 (Enterprise-out)
Note: In most cases, the objective is to leave the existing applications and
data unchanged.
synchronous synchronous
Read/write data
Application node
containing existing
components with no
need for modification
or which cannot
be changed
synchronous
asynchronous asynchronous
CRM
Product
WIP
CRM
LOB
Application node
containing new or
modified components
Read only data
Transient data
* work in progress
* cached committed
* staged
Application
2
Application
1
Commerce
Application
Decomp
Presentation

Chapter 2. Selecting the Application pattern
25
2.2.1 Application pattern 2: business drivers
Application pattern 2 utilizes Web technologies to sell goods directly to the
consumer and employs the Enterprise-out philosophy. Wherever possible,
existing order management and fulfillment systems are re-used. As organizations
become more sophisticated in their implementation, they typically enable
personalization. Personalization is used to customize the site to the needs of the
user to build customer loyalty and target members (register users) and member
groups with marketing and merchandising campaigns for such things as
cross-selling, up-selling, and specials.
2.2.2 Application pattern 2: key features
Application pattern 2 represents the target Application pattern for those
organizations that want to integrate the online buying application with their
existing enterprise systems. The Application pattern also addresses
maintenance of data on that tier, such as:
Product and catalog data, supporting the shopping process.
Customer-related data for personalization and registration. The data is often
duplicated in the enterprise systems on the fourth tier.
Work-in-process data, such as data supporting shopping cart functionality,
prior to submitting the orders for processing.
In addition, the pattern provides the ability to use some form of middleware to
access enterprise systems on the fourth tier. The middleware routes the
messages to back-end systems. The middleware may decompose a request into
several back-end interactions, and may serve as a broker, potentially
communicating with the systems of other companies.
Application pattern 2 (Enterprise-out) supports access to back-end fulfillment
systems that perform functions such as inventory, order management, pricing,
shipping, tax calculation, and credit processing. Some of the legacy applications
do not change, as denoted by the broad black border in Figure 2-2 on page 24.
Some of the newly written applications are intended to support not only the Web
channel, but also other sales channels such as call centers.
The interactions between the shopper and the middle-tier application will be
synchronous during the buying process. Often, asynchronous confirmation
messages are sent back to the user, usually by e-mail.

26
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Between the middle-tier and the back-end fulfillment systems, the recommended
approach is online synchronous interaction. This allows immediate confirmation
of important information such as the availability of inventory and delivery dates.
Asynchronous (but near-time) interaction is also utilized in many cases.
Automated and integrated batch interaction is a less preferable, but sometimes
the only option available. While not providing immediate confirmation for the
shopper, Application pattern 2 provides a more automated approach.
2.2.3 Application pattern 2: considerations
The same considerations mentioned in 2.1.3, “Application pattern 1:
considerations” on page 23, apply to Application pattern 2. In addition, the
following concerns need to be taken into account:
If the developer needs to provide access to many applications on the third
tier, an advanced Application pattern may be more appropriate. You should
consider an Application pattern that exploits a hub-and-spoke architecture
between the second and third tiers.
You should consider how this Application pattern will be deployed to avoid
systems management complexity. Complexity arises when frequently
updated corporate data resides on more than one tier, with the second and
third tiers both within the same organization but physically distributed. For
example, synchronization of backups may be cumbersome.
If there are different I/T organizations developing the new application and
maintaining or changing the existing systems, the development might be
difficult to coordinate. This is especially difficult if the interfaces between the
new and the existing systems are not properly defined and documented.
The new application may require changes to existing production systems.
This is always a critical task, especially when the back-end systems or
third-party applications are mission critical. Building a test system for the
existing applications that need to be changed is a good way to avoid
production system failure in the development and testing phase.
Obtaining skilled resources that can change the third-tier application is often a
problem. Many times, these are old applications, and finding someone who
understands them well enough to change them may be difficult.
The creation and management of the data on the second tier, and any
required synchronization with the back-end systems, is often a major effort.
Customer data residing on the second tier must be secure.

Chapter 2. Selecting the Application pattern
27
2.2.4 Application pattern 2: example
A clothing retailer has a large hard-copy catalog business, complete with a
telephone sales channel. Customers can call telemarketers to place orders with
immediate confirmation of inventory, delivery dates, and prices. The back-end
order processing systems are available 24/7. The retailer wants to expand this
business to the Web, but does not want a Web customer to have a lower level of
service than a phone customer. Online integration with the order processing
system will be crucial for the Web channel. Application pattern 2 is an excellent
choice for this retailer. It allows full integration with the back-end systems and a
full set of customer services.

28
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
29
Chapter 3.
Selecting the Runtime
pattern
Once the Application pattern has been chosen, the Runtime pattern is selected.
The Runtime pattern uses nodes to group functional and operational
components. The nodes are interconnected to solve the infrastructure and
integration needs of the Application pattern.
The chapter is organized into the following sections:
Runtime pattern overview
Runtime pattern tiers and nodes
Runtime pattern 1
Runtime pattern 2
3

30
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
3.1 Runtime pattern overview
This chapter will discuss two Runtime patterns corresponding to Application
patterns 1 and 2.
These Runtime patterns are based on the Enterprise Solution Structure (ESS),
Thin Client Transactional pattern. For more information on ESS see “Enterprise
Solutions Structure” in the IBM Systems Journal, Volume 38, No. 1, 1999, found
at:
http://www.research.ibm.com/journal/sj38-1.html/
Most references to vertical scalability in this chapter assume upgrading the
power, number, or memory capacity of the processors for a given platform.
Please bear in mind that one of the benefits of the IBM Framework for e-business
is that vertical scalability to a “big iron” solution is also possible by migrating the
application to other supported platforms, such as IBM eServer zSeries, pSeries,
and iSeries.
3.2 Runtime pattern tiers and nodes
The Runtime patterns will be shown in graphical form in the following sections.
Each pattern will consist of several nodes describing the function represented on
that node. Most patterns will consist of a core set of common nodes, with the
addition of one or more nodes unique to that pattern.
Within a typical Runtime pattern, the network is divided into three parts or tiers,
as seen in Figure 3-1:
Outside world
Demilitarized Zone (DMZ)
Internal network

Chapter 3. Selecting the Runtime pattern
31
Figure 3-1 Runtime pattern tiers and nodes
3.2.1 Outside world
As shown in Figure 3-1, the first tier is the outside world (Internet). The Internet
or the outside world zone contains nodes such as the Public Key Infrastructure
(PKI), Domain Name System (DNS) servers, and of course clients. These nodes
are partially described in Chapter 3, “Selecting the Runtime pattern” on page 29.
However this chapter will provide more detailed information on the client node.
Client nodes
Client nodes are responsible for accepting and validating the user input,
communicating the user inputs to the Commerce Server node, and presenting
the results received from the Commerce Server node to the user. Clients use
HTTP to communicate with the Web application server. Web clients are as
follows:
Web browser client
Web browser clients typically use a PC (running Windows, MAC, or UNIX)
using a Web browser such as Microsoft Internet Explorer or Netscape
Navigator. The Web browser uses the HTTP and HTTPs protocol to
communication with the Web server. These clients display HTML and DHTML
Internal network
Demilitarized Zone (DMZ)
Backend systems
Outside world
Mobile
Protocol
Gateway
Dispatcher B
Port 80
PC Client
HTML
Dispatcher A
Port 80
Port 443
Port 80
Port 443
ProtocolFirewall
Mobile client
Web server
plug-in
Web server
plug-in
Commerce
Application
Server
Commerce
Application
Server
DomainFirewall
Port 80
Database
Server
LDAP
Directory
Server
Order
procesing
center
Catalog
database
MQSeries
XML
FTP
XML

32
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Web pages. In addition, they are capable of processing client-side JavaScript
for enhancing navigation to perform simple input validation and to handle
simple errors. Furthermore, the majority of HTML clients can display small
Java applets to enhance the GUI.
Mobile client
Mobile clients or wireless clients include Mobile phones, wireless PDAs, and
wireless laptops. The two dominant wireless protocols are WAP and i-mode,
which use Wireless Markup Language (WML) and compact HTML (cHTML)
respectively to display content on the device. Wireless clients connect to the
wireless network via a wireless network provider protocol gateway. The
request from the mobile device is first processed by the wireless protocol
gateway, which then converts the request to the HTTP or HTTPS protocol to
access the Web server.
Application client
Application clients are primarily large Java applets or Java applications.These
clients provide rich graphical user interfaces compared to HTML clients. They
may communicate with the Web application server over a number of protocols
including HTTP and IIOP.
The advantages of using Web clients are as follows:
The majority of the presentation logic and all of the business logic will reside
on the server.
The client part of the application is lightweight and downloads quickly.
It is easier to secure, scale and maintain presentation and business logic that
reside on the server.
Further details on the client models can be found at:
http://www.ibm.com/developer/features/framework/framework.html
3.2.2 Demilitarized Zone (DMZ)
The first tier and the second tier are separated by the protocol firewall. The
second tier, known as a Demilitarized Zone (DMZ), is a network area that is
exposed to an untrusted outside world (Internet) and is considered a high-risk
zone for attacks. No confidential material should reside on any server in a DMZ
in an unprotected form. Only approved ports can be opened between the first
and second tier. Commerce Application Server receives HTTP requests (port 80)
and HTTPS requests (port 443).

Chapter 3. Selecting the Runtime pattern
33
Dispatcher node
The Dispatcher node provides the following fundamental functions for Web
applications:
Ensures that the application service remains available. This is achieved by
providing multiple instances of the service, running on several servers. In the
event that a server (or application) becomes unavailable (planned or as the
result of a failure), the dispatcher will distribute work only to the remaining
operational server. When the server becomes available again, it is added to
the pool.
Ensures that a consistent response time is enjoyed by the client. Statistics on
the response times from all servers in a pool can be used to measure the
level of acceptable service for the customer. The dispatcher will distribute
work evenly across all servers. This will ensure that no one server is
overloaded. It can also ensure that no single network path is overloaded
when there are other routes available (where servers are split across multiple
sub-networks).
Additionally, the dispatcher can be used as a systems management tool to
dynamically add (or remove) instances of an application service from the pool
in response to capacity/performance forecasting or for systems maintenance.
Since the dispatcher is a single point of failure, it should be backed up via
heartbeat or HACMP. The heartbeat alternative is usually cheaper and easier
to install than HACMP and available on several platforms.
Web server node
The Web server node is typically designed for access by HTTP clients and often
works in combination with an application server. The Web server serves static
content such as HTML and images to Web browser clients. Examples of Web
servers include the IBM HTTP Server and Netscape iPlanet Web server.
This node would be provided by the company, on company premises, or hosted
inside the enterprise network and inside a Demilitarized Zone (DMZ) for security
reasons. In most cases, access to this server would be in secure mode, using
services such as SSL or IPSec.
Web server redirector node
In order to separate the Web server from the application server, a so-called Web
server redirector node (or just redirector for short) is introduced. The Web server
redirector is used in conjunction with a Web server. The Web server serves
HTTP pages and the redirector forwards servlet and JSP requests to the
application servers. The advantage of using a redirector is that you can move the
application server behind the domain firewall into the secure network, where it is
more protected than within the DMZ.

34
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
The redirector can be implemented, for example, by either a reverse proxy server
or by a Web server plug-in such as the servlet redirector function of IBM
WebSphere Application Server, Advanced Edition.
3.2.3 Internal network
The internal network (intranet) or the third-tier is protected by an additional
firewall called a domain firewall. No direct traffic from the first tier is allowed to the
third tier. The intranet is considered a safe zone for the applications obtaining
confidential material.
Application server node
This node provides the infrastructure for application logic and may be part of a
Web application server node. It is capable of running both presentation and
business logic but generally does not serve HTTP requests. When used with a
Web server redirector the application server node will run both presentation and
business logic. In other situations, it may be used for business logic only.
The responsibilities of the application server include:
Receiving requests from the clients
Selecting and executing the appropriate business logic based on these
requests
Coordinating with external services (for example, LDAP directory) to retrieve
data and execute external applications
Formulating the response and dispatching it back to the client
To meet these requirements, the application servers provide a range of dynamic
page construction, business logic processing, data access, external application
integration, session management, load balancing, and failover services.
WebSphere Application Server supports Java-based technologies such as
Java servlets and Java Server Pages (JSPs) for dynamic page construction.
Business logic services provide a robust environment for processing business
logic independent of the user interface client types. WebSphere Application
Server supports components based on technologies such as JavaBeans and
Enterprise JavaBeans (EJBs) for programming business logic.
Connectors are components that support the communication between the
application server and the external services such as databases, legacy
applications and business partner applications. WebSphere Application
Server Advanced Edition provides a number of connectors including JDBC
drivers, JNDI class libraries (used by for LDAP Directory), CICS connectors,
MQ connectors, and IMS connectors.

Chapter 3. Selecting the Runtime pattern
35
Session management services are necessary because inherently HTTP is a
stateless protocol. The two main types of session management are
cookie-based and URL rewriting.
Security services include authentication, authorization, data integrity, privacy
(encryption) and non-repudiation services. The application server provides
these services by supporting industry-standard protocols such as SSL and
LDAP.
System management services provide a robust runtime environment for the
application hosted in the Web application server. These services allow load
balancing, failover support, remote monitoring, etc.
External Services include enterprise data sources, existing or new enterprise
applications (for example ERPs, financial systems, etc.), and business
partner systems.
Commerce application server node
This node provides the infrastructure for the presentation and business logic and
may be part of a commerce application server node.
Database server node
The WebSphere Commerce Suite is implemented using a relational database.
The database server runs at least WebSphere application server database and
WebSphere Commerce Suite production database. The WebSphere Commerce
Suite database contains all information that is used by the WebSphere
Commerce Suite application, including information about individual shoppers,
items, and prices, etc. For more information on the database system
management, refer to Chapter 9, “Systems management and security
guidelines” on page 203.
The WebSphere Commerce Suite application can be implemented with DB2
Universal Database or Oracle. DB2 Universal Database is part of the WebSphere
Commerce Suite product package. The technology used in this book is based
only on DB2 Universal Database.
The alternative option, an Oracle database, is mostly used on the Sun Solaris
platform and is not targeted in this book.
The database server node's function is to provide a persistent data storage and
retrieval service in support of the user-to-business transactional interaction. The
data stored is relevant to the specific business interaction.

36
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
It is important to note that the mode of database access is perhaps the most
important factor determining the performance of this Web application, in all but
the simplest cases. The recommended approach is to collapse the database
accesses into a single call or very few calls by invoking stored procedures.
Directory node
The WebSphere Commerce Suite supports integration with SecureWay Directory
using LDAP, a client/server protocol, for accessing a directory service.
WebSphere application server supports JNDI access to directory services.
Back-end system, catalog data nodes
This node can be an already existing database server containing catalog data. In
some cases, catalog data is imported from a back-end system into the
Commerce Suite store catalog. If the commerce database is not the master
catalog database, the replication of data from the back-end system will be run on
a regular basis. Data can be imported into the commerce database from the
back-end system.
Messaging node
This is a system where the orders will be sent from the application. Examples of
such implementation can be found in Chapter 14, “Messaging integration” on
page 361.
Public Key Infrastructure (PKI) node
A Public Key Infrastructure (PKI) node is a collection of standards-based
technologies and commercial services to support the secure interaction of two
unrelated entities (for example, a public user and a corporation) over the Internet.
In the context of the patterns defined in this redbook, PKI supports the
authentication of the server to the browser client, using the SSL protocol.
Domain Name System (DNS) node
The DNS node assists in determining the physical network address associated
with the symbolic address (URL) of the requested information.
Directory and security services node
The directory and security services node supplies information on the location,
capabilities and various attributes (including user ID/password pairs and
certificates) of resources and users known to this Web application system. The
node may supply information for various security services (authentication and
authorization) and may also perform the actual security processing, for example
to verify certificates. The authentication in most current designs validates the
access to the Web application server and the database server.

Chapter 3. Selecting the Runtime pattern
37
Protocol firewall and domain firewall nodes
Firewalls provide services that can be used to control access from a less trusted
network to a more trusted network, with the following traditional implementations:
Screening routers (the protocol firewall in this design)
Application gateways (the domain firewall)
The two firewall nodes provide increasing levels of protection at the expense of
increasing computing resource requirements. The protocol firewall is typically
implemented as an IP router, while the domain firewall is a dedicated node.
Shared file system node
The timely synchronization of several Web servers is achieved by using a shared
file system as the content storage and capitalizing on the replication capability of
this technology.
Application and data nodes
Existing applications are run and maintained on nodes that are installed in the
internal network to provide business logic that uses data maintained in the
internal network. The number and pattern of the existing applications and data
nodes is dependent on the configuration used by the legacy systems.
3.3 Runtime pattern 1
Runtime pattern 1 is based on the IBM Enterprise Solution Structure (ESS)
Reference Architecture and relates to Application pattern 1 (Web-up).
Figure 3-2 on page 39 is composed of logical nodes that represent a collection or
grouping of the major building blocks of the solution. Nodes are used by the lead
architect to describe the design at a logical level. They contain a set of
components that provide either infrastructure or application functionality.
Where do you go from here?
In Chapter 2, “Selecting the Application pattern” on page 21, you were
assisted in choosing the appropriate Application pattern for your environment.
If you chose Application pattern 1, continue to 3.3, “Runtime pattern 1” on
page 37.
If you chose Application pattern 2, then skip the next section and go directly to
3.4, “Runtime pattern 2” on page 42.

38
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Examples of infrastructure components that could run on a commerce server
node include Web servers, Java Virtual Machines, and TCP/IP stacks. Examples
of application components that could reside on a commerce server node include
HTML pages, JavaServer Pages (JSPs), Java Servlets (servlets), and Enterprise
JavaBeans (EJBs) developed by Web designers and Java programmers. Logical
nodes map to product instantiations in a step called product mappings. In some
cases the logical node will map one-to-one to a physical machine; however, this
is not always the case. Multiple nodes may be mapped to one machine, or a
single logical node may be spread across multiple physical machines.

Chapter 3. Selecting the Runtime pattern
39
Figure 3-2 Runtime pattern 1: Application pattern 1 (Web-up)
At the logical level, this Runtime pattern involves a synchronous interaction with
the user during the first part of the shopping experience. An asynchronous (and
deferred) response for the processing of details and confirmation of a submitted
order follows. Therefore, this Runtime pattern does not allow for such real-time
features as immediate inventory validation, order completion, or shipping details.
Internet
Retail
customer
Cookie
Outside World
Demilitarized Zone
(DMZ)
Internal Network
Online completion of
orders is not done
by shoppers
Protocolfirewall
Dispatcher
Application
nodes
Application
nodes
Domainfirewall
Secure and
non-secure
protocol
Secure
Internet
protocol (IP)
Databases
Application
nodes
Orders are stored in the DB server node.
Integration with back-end systems,if any,
are not tightly integrated (could be batch
or manual).
Content
creation &
management
node
Commerce
application
logic
Connections
to data
Connections
to back ends
(optional)
Commerce
Application
Server Node
Web Server
Static content
Redirect
- Static pages
- Promotions
Application pattern 1
Presentation
asynchronous
synchronous
asynchronous
Application
2
Application
Application
1
Database
Server node
-Databases
-Work in progress
Presentation

40
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Web-up basic online shopping process
1.From a Web browser client, the shopper connects to the commerce site by
entering the Web site URL, and will do one of the following:
– Log in to the commerce site if the user is recognized as a registered
shopper from a profile on the database server.
– The user may browse the site anonymously.
– Enter profile information to become a registered user.
2.The user then interacts with the pages of the site. The pages are either static
pages served from the Web server or dynamic pages served from the
commerce application server, with data on the pages being populated from
the database server.
3.Items will be added to a shopping cart. The data for the shopping cart is
stored on the database server along with required session state information.
A cookie is sent to the client browser. This cookie allows the commerce
server to track the progress of the customer interactions on the commerce
site and connect users with their shopping cart.
4.When the shopper wishes to buy or check out items in the shopping cart, the
commerce server stores the submitted order on the database server for later
processing. An acknowledgment is sent back to the shopper that the order
has been submitted, and the interactive session is terminated.
5.The system will use one of several techniques to retrieve the order and
process it through the back-end fulfillment, inventory, payment and shipping
processes.
6.Eventually, a confirmation e-mail of order status (such as order shipped, out
of stock, credit problems) is sent to the user.
Typically, the logon process uses registration data from the database server
node to identify registered shoppers and encryption technology, such as SSL, to
protect sensitive data (for example, credit card or address information).
Application pattern 2 is focused on extending the back-end systems with a tightly
integrated Web access channel; integration with corporate-wide directory and
security mechanisms may be desired. The Runtime pattern 2 corresponding to
Application pattern 2 includes directory and security nodes on the internal
network, as seen in Figure 3-3 on page 43.
Note: This pattern does not specify the details of back-end integration, which
may be done in batch or manually.

Chapter 3. Selecting the Runtime pattern
41
In the Runtime pattern 1, the Directory and Security nodes are omitted, since
corporate-wide directory and security mechanisms are usually not desired. The
ESS Reference Architecture, used by IBM Global Services, provides a much
more detailed flow of the online shopping process and how it interacts with the
infrastructure. This information is often used to prepare vendor quotes for the
products necessary to physically implement the logical Runtime pattern.
3.3.1 Runtime pattern 1: example
In 2.1.4, “Application pattern 1: example” on page 23, the example retail store
needed to expand its sales to the Web. The example retail store chose
Application pattern 1 of the Electronic Commerce composite pattern because of
the need for a Web-up solution.
The retail department store implemented support for two distinct buying channels
within the same site:
Web browser-based shoppers use the Web channel
Telemarketers utilize their point-of-sales system to complete orders
Walking through a purchase
1.During the shopping process, the user interacts synchronously with the
commerce server and the database server. This process is similar to the
shopping experience found in the Enterprise-out approach to the Application
pattern 2 runtime. Once the shopper has decided to buy the items in the
shopping cart, this pattern takes a very different approach:
– The shopper is simply notified that the order has been taken and that
confirmation is forthcoming.
– Most importantly, there is no online linkage from the online buying
front-end to the back-end systems (manual).
2.Order processing is completed:
– In the past, the orders were processed by telemarketers by phone. With
the new Internet front-end, the call center representatives simply log in to
the new application on commerce server and access any submitted, but
unfulfilled, orders on the database node.
– On behalf of the online shopper, the call center representatives submit the
unfulfilled orders to the back-end order processing systems. These
systems send e-mail to the shoppers, confirming their orders and
providing such information as delivery dates. While the online shoppers
are interacting with the system, they are unaware of factors such as
delivery dates or out-of-stock items. This is a major drawback for this
pattern.

42
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Reasons for this approach
Fast time to market (two to three months) was critical for this customer.
A process for customers to order over the phone was already in place.
The back-end order processing systems offered no interactive interface for
the commerce server front-end to utilize for direct online access.
The back-end order processing systems did not provide the 24/7 hours of
operation demanded by Internet shoppers.
The volume of orders was not expected to be large initially, so the customer
believed it could handle the load manually. This approach provided a quicker
time to market than that required by integrating directly with the back-end
systems. The retailer expected lower volume due to the nature of their sales:
primarily big-ticket items such as refrigerators, not high-volume items such as
socks.
Obviously, the retailer intends to expand usage and include many more items.
With augmented advertising of the site, the retailer expects sales volume to
increase dramatically and faces a pressing need to provide a less manual
approach to the order processing back-end systems. Over time this site will most
likely evolve into one that more closely resembles an Enterprise-out solution,
which includes automated interfaces to order processing either in batch or
directly online.
3.4 Runtime pattern 2
Runtime pattern 2 is the preferred Runtime pattern for the Electronic Commerce
composite pattern. It allows for immediate confirmation of order completion,
combined with information such as shipping details and volume discount pricing.
This Runtime pattern involves either a synchronous or asynchronous connection
to the back-end, with synchronous being the preferred choice. This Runtime
pattern provides online access to the back-end systems during checkout and
order completion. It is based on the ESS Reference Architecture. This Runtime
pattern represents a good starting point for selling merchandise over the Web.
Typically, it involves integration with existing back-end systems as part of the
Enterprise-Out approach of Web enabling existing systems to sell goods.
Where do you go from here?
If you chose Application pattern 1, skip the next section, and go to Chapter 4,
“Selecting the product mapping” on page 47.
If you chose Application pattern 2, continue to 3.4, “Runtime pattern 2” on
page 42.

Chapter 3. Selecting the Runtime pattern
43
Figure 3-3 is composed of logical nodes that represent a collection or grouping of
the major building blocks of the solution.
Figure 3-3 Runtime pattern 2: Application pattern 2 (Enterprise-out)
Enterprise-out basic online shopping process
1.From a Web browser client, the shopper connects to the commerce site by
entering the site URL. At this point the customer will do one of the following:
– Log in to the commerce site if he/she is recognized as a registered
shopper from a profile on the database server.
– The user may browse the site anonymously.
– Enter profile information to become a registered user.
Internet
Retail
customer
Cookie
Outside World
Demilitarized Zone
(DMZ)
Internal Network
Online completion of
orders and data
Protocolfirewall
Dispatcher
Secure and
non-secure
protocol
Systems
management
Security
Directory
Databases
Secure
Internet
Protocol
(IP)
Commerce
application
logic
Connections
to data
Connections
to back ends
(optional)
Commerce
Application
Server Node
Web Server
Static content
Redirect
Content
creation &
management
node
Batch transfer of orders
and data is not used in
this implementation
- Static pages
- Promotions
Domainfirewall
-Databases
-Work in progress
Application
2
Application
1
Decomp
Commerce
Application
Application pattern 2
Presentation
Database
server node
Application
nodes
Application
nodes
Application
nodes
Integration
node

44
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
2.The user then interacts with the pages of the site. The pages are either static
pages, served from the Web server or dynamic pages served from the
commerce application server with data on the pages being populated from
the database server.
3.Items will be added to a shopping cart. The data for the shopping cart is
stored on the database server along with required session state information.
A cookie is sent to the client browser. This cookie allows the commerce
server to track the progress of the customer interactions on the commerce
site and connect users with their shopping cart.
4.When the shopper wishes to buy or check out items in the shopping cart, one
of two implementations are taken:
a.Interaction through the integration node to access the back-end
application nodes (such as order processing, pricing, inventory, credit, and
shipping) and immediately provide feedback to the shopper such as
confirmations and delivery dates. This is the preferred approach.
b.The less preferred approach is to store the submitted order on the
database server for later submission via batch processing.
Acknowledgment that the order has been submitted is sent back to the
shopper from the commerce server to the Web browser. An e-mail
confirmation of such events as delivery, out of stock conditions, and credit
problems will be sent later by the back-end processing systems. This
approach is less desirable from a user's viewpoint because it does not
provide such features as immediate inventory validation, order completion,
and estimated shipping details. It is less desirable from the company's
viewpoint because it allows less direct control of such things as order
completion and shipping processes. This approach is similar to the
Web-up approach, except that it provides more automated linkage to the
batch processes.
Typically the logon process uses registration data on the database node to
identify registered shoppers and encryption technology, such as SSL to protect
sensitive transmissions (for example, credit card or address information).
Currently, most sites do not use digital certificates. This Runtime pattern does
include directory and security nodes, indicating that future use of technologies
such as LDAP directories and digital certificates is likely. The content creation
and management node represents the functions required to create and
administer the database server and commerce server nodes.
The ESS Reference Architecture used by IBM Global Services provides a more
detailed flow of the online shopping process and how it interacts with the
infrastructure. This information is often used to prepare vendor quotes for the
products necessary to physically implement the logical Runtime pattern.

Chapter 3. Selecting the Runtime pattern
45
3.4.1 Runtime pattern 2: example
Each project team may need to modify the basic node diagram of how the logical
architecture works in order to accommodate individual client requirements.
The example is of an outsourced commerce front-end connected via a
synchronous link to in-house back-end order processing systems (Enterprise-out
approach).
In 2.2.4, “Application pattern 2: example” on page 27, the clothing retailer
needed to expand its sales to the Web. The company intends to outsource the
Web front-end to the IBM Universal Server Farm, and have the back-end reside
on the company's host systems in its data center. The IBM Universal Server
Farm refers to a set of outsourcing sites run by IBM. Server technology from
multiple vendors is operated by IBM on behalf of organizations that would rather
not manage their own server operations. Often with e-commerce Web sites, the
nodes in the DMZ front-end and the database server node are outsourced.
These are then networked to the company's own data center for back-end order
processing.
The reasons for implementing their Web channel with the Enterprise-out Runtime
pattern 2 are discussed in “Reasons for architectural approach” on page 45. This
approach is quite close to the basic Runtime pattern 2. It differs in the following
ways:
The front-end commerce site is outsourced and hosted at the IBM Universal
Server Farm.
The back-end resides at the company's in-house data center. The
modification is that communication between the DMZ and the internal network
takes place over the Internet using a secure connection between two firewalls
(firewalls 4 and 5). This also implies TCP/IP communication to the back-end.
The retailer chose the preferred approach of linking to the back-end order
entry systems in a synchronous and online manner. The reasons for this are
listed in “Reasons for architectural approach” on page 45.
A separate batch link exists for publishing and maintaining data on the
database that is necessary for administration of the site.
Reasons for architectural approach
The company had a mandatory business requirement that users have immediate
confirmation of orders with shipping, discounts, and pricing information. This data
was to be provided through the back-end order processing systems. The
company was providing immediate confirmation of call center orders and did not

46
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
want less functionality for its Web customers. The company needed to support
the existing call center. The back-end systems were already in place with server
interfaces, and sufficient hours of operation. It was relatively easy to utilize the
same interfaces to support Internet access.

© Copyright IBM Corp. 2001
47
Chapter 4.
Selecting the product
mapping
In this chapter we map the logical nodes defined in the Runtime pattern to
products for the selected platform. The product mapping identifies the platform,
software product name, and version. The IBM Framework for e-business
provides support for many platforms, including IBM AIX, IBM OS/400, IBM
OS/390, Sun Solaris, HP-UX, Linux, and Windows NT/2000.
The framework provides the flexibility to allow you to develop and test the
application on your runtime platform and easily deploy the application on the
customer’s platform of choice.
In order to perform the product mapping, we need to first select a platform. When
selecting a platform, you should consider the following points:
Existing systems and platform investments
Available customer and developer skills
Customer choice
4
Note: It is common for a company to have a mixture of platforms within the
whole integrated e-business solution. The requirement for integration with a
mixed platform environment makes the Application Framework for e-business
a very appealing choice with its support for many operating system platforms.

48
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
The platform selected should fit into the customer's environment and ensure
quality of service, such as scalability and reliability to ensure the solution can
grow with the e-business.
Next, we will review the Runtime pattern product mapping. This redbook includes
product mapping information using WebSphere Commerce Suite V5.1 for
Windows NT, Windows 2000, AIX, and Solaris. The most current information on
product mappings, including additional platforms, can be found on the Patterns
for e-business Web site at:
http://www.ibm.com/developerworks/patterns
Where do you go from here?
In Chapter 3, “Selecting the Runtime pattern” on page 29, you were assisted
in selecting the appropriate Runtime pattern for Application pattern 1.
If you chose Runtime pattern 1, continue to 4.1, “Runtime pattern 1: product
mapping” on page 49.
If you chose Runtime pattern 2, then skip the next section and go directly to
4.2, “Runtime pattern 2: product mapping” on page 52.

Chapter 4. Selecting the product mapping
49
4.1 Runtime pattern 1: product mapping
This section provides product mapping information for Runtime pattern 1 logical
nodes, for specific software products on the selected platform.
4.1.1 Runtime pattern 1: product mapping - Windows NT/2000
Figure 4-1 illustrates the Windows NT/2000 platform software product names
and versions typically used in WebSphere Commerce Suite V5.1 for Runtime
pattern 1.
Figure 4-1 Runtime pattern 1: product mapping for Windows NT/2000
Product mapping example - Windows NT/2000
In Figure 4-1 illustrates the example company product mapping for the Windows
NT/2000 platform. The company had the benefit of implementing one operating
system platform, Windows NT/2000, within the DMZ network.
Internet
Retail
customer
Cookie
Outside World
Demilitarized Zone
(DMZ)
Internal Network
Windows NT or 2000 Server
DB2 Server 7.1 + Fixpack 2a
Intel-based RAID0 Disk
IBMHTTP Server
1.3.12 for Windows +
WAS plug-in
NetworkDispatcher
DB server
node
Content
creation &
management
node
Protocolfirewall
Domainfirewall
Application
nodes
Application
nodes
Application
nodes
OS/390
CICSor IMS
DB2
Customor ERP
applications
MQSeries 5.2
Windows NT or 2000 Server
Network Dispatcher 3.6
Windows NT or 2000 Server
WCS 5.1
WAS 3.5 + Fixpack 2 + E-fixes
DB2 Client 7.1 + Fixpack 2a
MQSeries Client 5.2
Commerce
application
logic
Connections to
data
Connections to
back ends
(optional)
Commerce
Application
Server Node

50
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
4.1.2 Runtime pattern 1: product mapping - AIX
Figure 4-2 illustrates the AIX platform software product names and versions
typically used in a Building B2C Web Sites for Runtime pattern 1.
Figure 4-2 Runtime pattern 1: product mapping - AIX
Note: In this example, the company needed to implement product mappings
to other platforms than Windows NT on their internal network, with the
exception of the database server.
Internet
Retail
customer
Cookie
Outside World
Demilitarized Zone
(DMZ)
Internal Network
AIX 4.3.3
Network Dispatcher 3.6
Protocolfirewall
NetworkDispatcher
IBM HTTP Server
1.3.12 for AIX +
WAS plug-in
AIX 4.3.3
WCS 5.1
WAS 3.5 + Fixpack 2 + E-fixes
DB2 Client 7.1 + Fixpack 2a
MQSeries Client 5.2
RS/6000 or SP2 nodes
Domainfirewall
Content
creation &
management
node
Application
nodes
Application
nodes
Application
nodes
DB2
Customor ERP
applications
MQSeries 5.2
Commerce
application
logic
Connections
to data
Connections
to back ends
(optional)
Commerce
Application
Server Node
AIX 4.3.3
DB2 Server 7.1 + Fixpack 2a
Large RS/6000 or SP2 node
HACMP high availability disk
DB server
node

Chapter 4. Selecting the product mapping
51
Product mapping example - AIX
In Figure 4-2 illustrates the example company product mapping for the AIX
platform. The company had the benefit of implementing one operating system,
AIX, within the entire DMZ network. Even the firewalls were able to run on the
AIX platform.
In the case of a Web-up implementation, the back-end may not exist or may be
installed concurrently with the front-end systems. In such cases, the back-end
application servers may also use the AIX platform.
Typically, multiple RS/6000 or SP2 commerce servers will be clustered using the
Network Dispatcher for load balancing. Large enterprise customers often are
running on S/390 hardware and software for back-end processing with legacy
systems.
If the commerce and database servers had been implemented using Sun Solaris
or HP-UX technology, the product mapping would be similar.
4.1.3 Runtime pattern 1: product mapping - Solaris
Figure 4-3 on page 52 depicts the product mapping for Solaris WebSphere
Commerce Suite V5.1 Runtime pattern 1.
Where do you go from here?
If you chose Runtime pattern 1, skip the next section and go directly to Part 2,
“Electronic Commerce composite pattern: guidelines” on page 57.
If you chose Runtime pattern 2, continue to 4.2, “Runtime pattern 2: product
mapping” on page 52.

52
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 4-3 Runtime pattern 1: product mapping - Solaris
4.2 Runtime pattern 2: product mapping
This section provides product mapping information for Runtime pattern 2 logical
nodes, for specific products on the selected platform.
Internet
Retail
customer
Cookie
Outside World
Demilitarized Zone
(DMZ)
Internal Network
Solaris 7
Network Dispatcher 3.6
Protocolfirewall
NetworkDispatcher
Commerce
application
logic
Connections
to data
Connections
to back ends
(optional)
Commerce
Application
Server Node
DB2
Customor ERP
applications
MQSeries 5.2
Netscape iPlanet
Web Server 4.17 for
Solaris + WAS
plugin
Solaris 7
WCS 5.1
WAS 3.5 + Fixpack 2 + E-fixes
Oracle Client 8.16
MQSeries Client 5.2
RS/6000 or SP2 nodes
DB server
node
Content
creation &
management
node
Application
nodes
Domainfirewall
Solaris 7
Oracle Server 8.16
Application
nodes
Application
nodes

Chapter 4. Selecting the product mapping
53
4.2.1 Runtime pattern 2: product mapping - Windows NT/2000
Figure 4-4 illustrates the Windows NT platform software product names and
versions used in WebSphere Commerce Suite V5.1 for Runtime pattern 2.
Figure 4-4 Runtime pattern 2: product mapping - Windows NT/2000
Note: None of the mappings implemented for the integration node, provide a
hub and spoke link to back-end systems. We are focussing on the commerce
application server and simply used MQSeries to link point to point to the
back-end systems.
Internet
Retail
customer
Cookie
Outside World
Demilitarized Zone
(DMZ)
Internal Network
Windows NT or 2000
Server
SecureWay Directory
(LDAP) 3.21
Protocolfirewall
Systems
management
Security
Directory
Databases
IBMHTTP
Server 1.3.12
for Windows +
WAS plug-in
Content
creation &
management
node
Windows NT or 2000 Server
DB2 Server 7.1 + Fixpak 2a
Intel-based RAID 0 Disk
Database
server node
Integration
node
NetworkDispatcher
Windows NT or 2000 Server
WCS 5.1
WAS 3.5 + Fixpak 2 + E-fixes
DB2 Client 7.1 + Fixpak 2a
MQSeries Client 5.2
Intel-Based RAID Disk
Domainfirewall
Commerce
application
logic
Connections
to data
Connections
to back ends
Commerce
Application
Server Node
OS/390
CICS or IMS
DB2
Customor ERP
Applications
MQSeries 5.2
Windows NT or 2000 Server
Network Dispatcher 3.6
Application
nodes
Application
nodes
Application
nodes

54
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
4.2.2 Runtime pattern 2: product mapping - AIX
Figure 4-5 illustrates the AIX platform software product names and versions
typically used in WebSphere Commerce Suite V5.1 for Runtime pattern 2.
Figure 4-5 Runtime pattern 2: product mapping - AIX platform
In Figure 4-5, the example company had a large investment in the AIX platform.
The company had the benefit of implementing one operating system, AIX, within
the entire DMZ network. Even the firewalls were able to run on the AIX platform.
Typically, multiple RS/6000 or SP2 commerce servers will be clustered using the
Network Dispatcher for load balancing. Large enterprise customers often are
running on S/390 hardware and software for back-end processing with legacy
systems.
Internet
Retail
customer
Cookie
Outside World
Demilitarized Zone
(DMZ)
Internal Network
AIX 4.3.3
SecureWay Directory
(LDAP) 3.21
Protocolfirewall
Systems
management
Security
Directory
Databases
IBMHTTP
Server 1.3.12
for AIX + WAS
plug-in
Content
creation &
management
node
AIX 4.3.3
DB2 Server 7.1 + Fixpak 2a
Large RS/6000 or SP2 node
HACMP high availability disk
Database
server node
Integration
node
NetworkDispatcher
AIX 4.3.3
WCS 5.1
WAS 3.5 + Fixpak 2 + E-fixes
DB2 Client 7.1 + Fixpak 2a
MQSeries Client 5.2
RS/6000 or SP2 nodes
Domainfirewall
Commerce
application
logic
Connections
to data
Connections
to back ends
(optional)
Commerce
Application
Server Node
OS/390
CICS or IMS
DB2
Customor ERP
Applications
MQSeries 5.2
AIX 4.3.3
Network Dispatcher 3.60
Application
nodes
Application
nodes
Application
nodes

Chapter 4. Selecting the product mapping
55
4.2.3 Runtime pattern 2: product mapping - Solaris
Figure 4-6 depicts the product mapping for Solaris WebSphere Commerce Suite
V5.1 Runtime pattern 2.
Figure 4-6 Runtime pattern 2: product mapping - Solaris
Internet
Retail
customer
Cookie
Outside World
Demilitarized Zone
(DMZ)
Internal Network
Solaris 7
SecureWay Directory
(LDAP) 3.21
Protocolfirewall
Systems
management
Security
Directory
Databases
IBMHTTP
Server 1.3.12
for AIX + WAS
plug-in
Content
creation &
management
node
Solaris 7
Oracle Server 8.16
Database
server node
Integration
node
NetworkDispatcher
Solaris 7
WCS 5.1
WAS 3.5 + Fixpak 2 + E-fixes
Oracle Client 8.16
MQSeries Client 5.2
Domainfirewall
Commerce
application
logic
Connections
to data
Connections
to back ends
(optional)
Commerce
Application
Server Node
OS/390
CICS or IMS
DB2
Customor ERP
Applications
MQSeries 5.2
Solaris 7
Network Dispatcher 3.60
Application
nodes
Application
nodes
Application
nodes

56
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
57
Part 2
Electronic
Commerce
composite
pattern:
guidelines
Part 2

58
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
59
Chapter 5.
e-business life cycle
This chapter describes the iterative and incremental development methodologies
used to build an e-business application from end to end. The Patterns for
e-business are used to navigate from the problem domain to the solution domain
within the development methodology.
There are many defined methodologies used for the software development
process. In this chapter we will review the IBM Global Services Method and the
Rational Unified Process (RUP). In addition, we describe the e-business
life-cycle phases, roles, inputs and outputs.
The chapter is organized into the following sections:
IBM Global Services Method
Rational Unified Process
e-business life-cycle phases
5

60
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
5.1 IBM Global Services Method
The IBM Global Services Method, known as the Method, is a work product-based
technical method for IBM Global Services practitioners. The Method is used by
IBM practitioners worldwide to facilitate the shift to asset-based services and
intellectual capital harvesting and reuse throughout the engagement life cycle.
Work products, which form the building blocks of the Method, can be arranged,
assembled and custom crafted to support the implementation of offerings and
industry solutions.
Work products (WP) are the foundation of the IBM Global Services Method.
Work products are tangible artifacts that are produced during the project. This
includes models, reports, diagrams, plans, code and other documents that are
direct stepping stones to the final deliverable. They have a specific purpose in
the engagement and describe specific content using predefined semantics and
syntax. Work products are produced as a result of performing one or more tasks.
Some tasks produce less tangible outputs (for example, pass/fail, trained
students) and are called
outcomes
.
Work products are not the same as deliverables, as they may be an intermediate
products and not delivered to the customer. All deliverables consist of work
products, but not all work products are deliverables. Work products have a 3-10
page Work Product Description (WPD). A WPD describes a type of work product
and defines how to create the actual instance of the work product. WPDs are
grouped into domains.
Figure 5-1 on page 61 depicts the IBM Global Services Method phases and
domains. The domains are the logical groupings of work products, and fit a role
or specific skill, thus enabling specialization.

Chapter 5. e-business life cycle
61
Figure 5-1 IBM Global Services Method
5.1.1 Standard Work Product Descriptions
The basis of the Method is a core set of 300 Work Product Descriptions (WPDs)
that can be shared by all practitioners using the Method. The work products
cover a broad range of work performed on engagements and are logically
categorized into six high-level domains (see Figure 5-1) with subdomains to
further categorize content where needed:
Engagement: includes those WPDs used to define, plan, manage, and close
an IBM Global Services Method engagement. This domain also contains the
Work Product Descriptions.
Business: provides the WPDs needed to conduct a structured investigation of
the current and desired situations in a customer’s business in order to
develop and implement the appropriate solution.
Organization: contains the WPDs used to assess organizational and cultural
impacts and issues, in order to determine the customer’s ability to absorb the
change required to develop and implement a new solution.

62
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Application: provides WPDs for the full life cycle of application development
including design, development, testing and maintaining applications.
Architecture: contains the WPDs used to structure a solution architecture
including the hardware and software components, externally visible interfaces
between them, and the relationship among them.
Operations: includes the WPDs pertaining to the ongoing operations of a
solution including facilities management, problem reporting, information
technology management, and security considerations.
5.1.2 Engagement models
In addition to the Work Product Descriptions, the Method also provides guidance
for how engagements should be conducted. This guidance is delivered through
29 engagement models that represents the typical projects conducted in nine
families within IBM Global Services Method. The engagement models provide
guidance for the phases, activities, and tasks required (often called the work
breakdown structure, or WBS), the work products that are produced, the roles
required to perform the work, and any applicable techniques that should be used
for one or more of the tasks.
The IBM Global Services Method (Release 3.1.0) catalog currently consists of
the following families and engagement models:
Custom Application Development
Customer Relationship Management
E-Procurement
Global AMS Delivery
Information Technology Management
Knowledge Management
Network Consulting
Rapid Custom Development
Testing
5.1.3 Custom Application Development phases
A typical B2C e-commerce Web site development project would fit within the
engagement model of Custom Application Development. The IBM Global
Services Method, Custom Application Development engagement model consists
of the following phases, as seen in Figure 5-2 on page 63:
Solution Startup: Covers the required start activities from PMM.

Chapter 5. e-business life cycle
63
Solution outline: Provides the client with the necessary costs, schedule and
risk information to make an informed investment decision regarding a
potential new system.
Macro design: Develops a robust architectural framework upon which to build
agile releases.
Micro design: Prepares for the build cycle of a specific release of the system
by driving the architecture and design to a release specific and
implementation platform view.
Build cycle: Incrementally develops and tests the system until the objectives
of the release are achieved.
Deployment: Deploys the system and prepares for the next release of the
system.
Solution Close: Covers the required close activities from PMM including
gathering metrics and posting intellectual capital.
Figure 5-2 Custom Application Development process
The solution outline and macro design are conducted once. The three phases
that make up a Release are grouped together and performed many times (see
Figure 5-2), once for each release of the system. The Solution Startup and
Solution Close phases bracket the engagement and may be duplicated
depending on how the engagement is sold.

64
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
5.2 Rational Unified Process
The Rational Unified Process (RUP) is a Web-enabled software life cycle process
that is widely used within the software and consulting industry. In this section, we
provide a brief description of the major concepts of the Rational Unified Process.
RUP provides extensive guidelines, templates, and examples for all of the critical
development activities. RUP's e-business specific content provides explicit
guidance in areas such as business modeling, Web architectures and testing for
the Web. Guidance for developing on IBM WebSphere, Java 2 Enterprise Edition
(J2EE) platforms are also provided to accelerate your e-development projects.
RUP is a customizable framework that can easily be adapted to the way you
work. It is tightly integrated with Rational tools, allowing development teams to
gain the full benefits of Rational product features, the Unified Modeling Language
(UML), and other industry best practices.
From a management perspective, the software life cycle of the Rational Unified
Process is decomposed over time into four sequential phases (see Figure 5-3),
each concluded by a major milestone; each phase is essentially a span of time
between two major milestones. At each phase-end an assessment is performed
(Activity: Life Cycle Milestone Review) to determine whether the objectives of the
phase have been met. A satisfactory assessment allows the project to move to
the next phase.

Chapter 5. e-business life cycle
65
Figure 5-3 Rational Unified Process
For detailed information on the Rational Unified Process, we recommend the
following:
Rational Software Web site product link for Rational Unified Process at:
http://www.rational.com/products/rup/index.jsp
Philippe Kruchten, The Rational Unified Process, An Introduction, Second
Edition, Addison-Wesley, 2000, ISBN 0201707101
5.3 e-business life-cycle phases
The e-business life cycle approach presented in this redbook is derived from the
IBM Global Services Method. The purpose of this section is to describe the types
of work products, inputs and outputs in a fashion that can be applied to various
software development models.
We have added three phases - requirements, test, and operations - to
accommodate the WebSphere Commerce Suite implementation of projects to
highlight these phases.

66
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 5-4 Life cycle phases
We have defined eight phases for WebSphere Commerce Suite implementation,
as seen in Figure 5-4, based on the following assumptions:
The requirements and solution design phases are problem oriented.
High-level design and low level design phases are solution oriented.
The project management is involved during the entire project life cycle.
The Unified Modeling Language (UML) is applied to all phases.
The roles defined for every phase can be redefined for a particular project.
These phases run in a sequence and therefore the output from one phase
becomes logically the input into the next phase.
5.3.1 Requirements phase
At the beginning of a project it is necessary to get a good handle on the
requirements and their prioritization. It is wise to state requirements clearly from
the start and elaborate on them in detail during later phases.
Roles
The typical roles needed are as follows:
Business consultant
Business analyst
Technical consultant
Input
The input for this phase is as follows:
Business objectives (for example, a business idea to expand a catalog to the
Internet)

Chapter 5. e-business life cycle
67
Output
The output from this phase is as follows:
Business process model
Requirements specification
Description
The requirements phases includes the business process model, the
requirements specification, and functional and non-functional requirements.
Business Process Model
The Business Process Model is used to gain an understanding of the business
operations.
Requirements specification
The requirements gathering and the use cases modeling happens in the
interactions where a new use case can show a demand for new requirements.
Use cases models describe what the system will do in the form of interactions
between a user and the system. The use case modeling facilitates the
development of functional requirements, fully states the functional capabilities to
be delivered to the user, and establishes the boundary of future e-business
applications. The use case model uses graphical symbols as seen in Figure 5-5,
and text to specify how users in specific roles will use the system.
Figure 5-5 User registration use case diagram
Functional requirements
The functional requirements cover the following areas:
Content of site and content management requirements
Tip: Make sure that the requirements are frozen before advancing to the next
phase. If the requirements are not frozen or stated properly, additional
changes during design phases or development phase can increase the risk to
a successful outcome for the entire project.

68
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Marketing actions and programs that may be implemented on the site
Order processing requirements
Order fulfillment requirements
Payment processing and handling requirements
These requirements are described by the use cases model. You can use the
requirement approach questionnaire from Building e-commerce Solutions with
Net.Commerce: A Project Guidebook, SG24-5417, or for details on how to gather
requirements refer to “Chapter 3 Planning your site - Requirements gathering” in
the Fundamentals, IBM WebSphere Commerce Suite V5.1 product guide.
Non-functional requirements
Non-functional requirements are the qualitative requirements that a system must
satisfy. The work product can also be used for a set of systems in effect for a
department or enterprise-level description of requirements.
Non-functional requirements consist of:
Service level requirements (SLRs), which are runtime properties for the
application as a whole, or parts of the application that must be satisfied (use
cases). SLRs include:
– Capacity and performance (volumetrics)
– Availability (for example, availability 24x7)
– Security
– Systems management
Other required (non-runtime) properties of the system, such as:
– Portability
– Maintainability
– The business constraints which the system must satisfy (for example,
geographical location)
– The technical standards the system must satisfy
– The technical “givens” that constrain the system (for example, existing
database and hardware)
The requirement specification for a WebSphere Commerce Suite V5.1
implementation project must comply with the industry specification. For example,
WebSphere Commerce Suite can be used with the following industries:
Retail
Financial

Chapter 5. e-business life cycle
69
Banking
Industrial
Communication
Distribution
5.3.2 Solution outline phase
During the solution outline phase, the application’s requirements are validated
and the project scope is defined. The primary objective is to determine the
complexity and scope of the application that is going to be delivered.
Roles
The typical roles needed are as follows:
Lead architect
Solution designer
Business analyst
Output
The output from this phase is as follows:
Architecture model
Solution strategy
Risk assessment
Description
This phase of the project is problem driven and includes the architecture model,
solution strategy and risks.
Architecture model
The architecture model shows the commerce environments used to develop,
test, and deploy the e-commerce application. The architecture decisions made
should be properly documented. They will be used as input for the high-level
design where architecture is driven from the selected Application pattern.
Tip: UML tools such as uses cases, use case diagrams or interaction
diagrams should be applied very intensively during this phase.

70
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Solution strategy
The solution strategy defines how the project will address subjects such as
content management, release of versions, deployment, and testing. Output from
this strategy can include:
Content management plan
In this plan you establish the roles required to generate content and define
the process to release and deploy each version.
Catalog management plan
In this plan you establish the roles required to load data into the catalog. In
addition you could establish a plan to load data in a test environment.
Versions release plan
In this plan you define the process by which application components are
released.
Deployment plan
In this plan you define the process to deploy applications in a test
environment.
Test strategy plan
In this plan you define the strategy to develop test cases, create test
environments, perform tests, and execute stress tests.
Risk assessment
The requirements risks are defined from use cases. Therefore, it is very
important to discover all the potential use cases. Usually time spent on risk
assessment pays off during the following phases.
Additional risks come from the technology that is going to be used and mainly
from interaction between components of the application.
Skills risks must be analyzed as well. Most of the time when a project is delayed,
it is due to a lack of competent human resources.
5.3.3 High-level design phase
The main objective for this phase is to deliver the high-level design for the
application discussed in the previous two phases.
Tip: The UML tools uses cases, interaction diagrams, deployment diagrams
or component collaboration diagrams can by applied during this phase.

Chapter 5. e-business life cycle
71
Roles
The typical roles needed are as follows:
Application architect
Product specialists
Solution designer
Output
The output from this phase is as follows:
High-level design
Description
High-level design is based on requirements specification, architecture model and
the analysis and design phases. The tasks included in the high-level design are
as follows:
Develop a navigation flow
The navigational flows are directly tied back to the user scenarios and use
cases. A site map detailing the page navigation is developed. This gives a
detailed overview of the site and defines the user experience.
Develop a user interface structure
The user interface structure defines sectors that will be considered in the
build cycle implementation. This allows you to develop JSPs in a segmented
manner with spaces and styles for graphical design and logic that will be
integrated later.
Develop a component model
This is an architectural document that describes the high-level structure of the
system and identifies the responsibilities, relationships, and interactions of
components. It documents the way application and technical elements of the
system are related.
Develop a design and plan for tests
Set up the development environment
Create a development plan for the following release cycles

72
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
5.3.4 Low-level design phase
The low-level design document is used by developers to develop the WebSphere
Commerce Suite application.
Roles
The typical roles needed are as follows:
Product specialists
Solution designer
Output
The output from this phase is as follows:
Low-level design
Description
The development plan outlines several release cycles to implement the
requirements iteratively and incrementally. Each release cycle starts with this
micro design that focuses on transforming the business model into a design
model by taking the selected use cases and running them through a typical
object-oriented development phase. Transforming means that we use the
business model to bring it to such a technically detailed level that it can be
implemented. This is done by adding all the architecture and
implementation-specific classes and components to the existing business model.
This phase is for the detailed design and includes the following tasks:
Developing a Fit/Gap analysis.
This is a technical and visual document that compares the requirements
against the default store. The analysis helps to determine what
customizations need to be implemented.
Transforming the use cases to the WebSphere Commerce Suite programming
model.
Tip: The work products produced in this phase could be interaction diagrams,
component diagrams and activity diagrams.

Chapter 5. e-business life cycle
73
5.3.5 Development phase
The development phase produces the core deliverables of the project.
Roles
The typical roles needed are as follows:
Web designer
Java programmer
Catalog designer
Test architect
Output
The output from this phase is as follows:
Web assets
Data assets
Description
In each release cycle the low-level design is followed by the development cycle.
The designed system is actually coded and tested in several development
cycles. As in the low-level design, each build cycle focuses only on the
requirements valid for that particular release. So with every build cycle the
developed system grows in the functionality implemented.
In the development cycle the results of the low-level design are turned into code
as follows:
Write and unit test the source code
Build the executable code if necessary (for example, all Java code)
Perform various unit tests on the executable code
System test the application in a test runtime environment
Prepare for deployment
The incremental approach used to run the release cycles is also used for the
different activities of the development cycle. It is run in several iterations for one
release, with each iteration transforming more of the design into tested
executable code that is ready to be deployed.
Tip: The UML diagram produced in the micro design phase include use cases,
class models, interaction diagrams, activity diagrams, and state diagrams.

74
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
5.3.6 Test phase
Testing is a necessary part of any e-business development project. WebSphere
Commerce Suite solutions include various Web technologies and requires
rigorous integration testing.
Roles
The typical roles needed are as follows:
Test architect
Test specialist - business
Test specialist- technical
Tester
Test environment specialist
Input
The input into this phase is as follows:
Test design
Test plans
Test environment
Output
The output from this phase is as follows:
List of defects
Description
A detailed test plan is created for each level of testing identified as necessary
based on project life cycle testing requirements. Each testing level represents a
known level of physical integration and quality of the system solution under
development. Each plan identifies the scope of testing for that level,
functions/features to be tested, the testing tasks to be performed, the personnel
responsible for each task, and the business and technical risks that can be
addressed through that level of testing.
Project needs based on size, complexity, risks and costs determine the levels of
testing to be used.
The following are commonly used levels of testing:
Unit test

Chapter 5. e-business life cycle
75
Unit tests are used to verify particular pieces of function or code, before they
are integrated into the production code base. Unit tests can be performed on
a developer's machine. Usually, developers configure a WebSphere Test
Environment (WTE) in VisualAge for Java for unit tests purposes. Using WTE
you can test customized code including Java beans, Enterprise JavaBeans,
and JavaServer Pages without needing to deploy this code to a WebSphere
Commerce Suite test machine.
Build Verification Test (BVT)
Members of the development team check their source code into the source
control tool, and mark the components as part of a build level. The build team
is responsible for building the application in a controlled environment based
on the source code available in the source control system repository. The
build team extracts the source code from the source control system, executes
scripts to compile the source code (link if needed), package the application,
and test the application build.
The tests run on the application of the build produced is called a Build
Verification Test (BVT). BVT is a predefined and documented test procedure
to ensure that basic elements of the application are working properly before
accepting the build and making it available to the test team for Function
Verification Test (FVT) and/or System Verification Test (SVT).
Functional Verification Test (FVT)
These tests are used to verify individual functions delivered by your
WebSphere Commerce Suite store. For example, you may verify if the taxes
are being calculated properly. These tests are usually performed in a
dedicated test environment that has a working instance of WebSphere
Commerce Suite.
System Verification Test (SVT)
System tests are used to test a group of functions. A dedicated test
environment should be used with the same system and application software
as the target production environment. To get the best results from your tests,
you need to find the most similar environment and involve as many
components as possible, such as creating a store, executing some
transactions and verifying if all functions are working properly.
Integration Verification Test (IVT)
These tests are performed when your store site must work with other
systems, for example, a billing system (such as Payment Manager) or a
back-end inventory. In this case, your environment should be similar to the
target production environment.
Stress test

76
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Stress tests simulate the volume of traffic that you expect to have at your
store and ensure that it will support this stress and determine if the system
performance is acceptable.
Customer Acceptance Test
This is a level of testing in which all aspects of an application or system are
thoroughly and systematically tested to demonstrate that it meets business
and non-functional requirements. The scope of a particular acceptance test is
defined in the acceptance test plan.
5.3.7 Deployment phase
When creating and customizing WebSphere Commerce Suite application, many
different types of assets are developed (for example, static HTML, images, JSPs,
servlets, EJBs, XML data files), depending on the complexity. The assets need to
be managed in a central development environment and deployed to the
production machine.
Roles
The typical roles needed are as follows:
Site administrator
Database administrator
Input
Input into this phase are as follows:
Deployment model
Production environment
Output
The output from this phase is as follows:
Cut over to production
Confirmation of a deployment
Description
The purpose of this phase is to deploy the WebSphere Commerce Suite
application and prepare for the next release.
Tip: The input work products for this phase could be test plan and test cases.

Chapter 5. e-business life cycle
77
Depending on the size of the developed components in the build cycle, the
development team might decide to build it in several iterations. Even though
each build cycle produces executable code, only the final result is usually
deployed. The whole project is also run iteratively. It is up to the development
team to decide which release, built in a development cycle, is going to be
deployed. There might be alpha or beta releases that are deployed only to a
certain number of test users.
A deployment plan has to be created that encompasses not only when and how
to install and set up the newly developed application, but it must include all
hardware and prerequisite software requirements. You also have to plan for
system management, taking into consideration what has to be managed and
how, how to establish the required security, and what has to be done for
availability and recovery, before you can deploy the application into a production
environment.
5.3.8 Operations phase
This phase covers the activities after the WebSphere Commerce Suite
application has been deployed to the production environment.
Roles
The typical roles needed are as follows:
I/T specialist roles
– Site administrator
– Store administrator
– Database administrator
Business user roles
– Merchant
– Marketing manager
– Merchandising manager
– Customer service representative
– Order clerk
Note: The deployment model can be used to explain the deployment scheme
of the application.

78
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Input
The input into this phase is as follows:
System operational guidelines
Maintenance guidelines
Application guidelines
Output
The output from this phase is as follows:
Operational system
Reports (for example, user statistics and system performance)
Description
Once the B2C e-commerce store has been deployed, there are many operations
that need to be performed to maintain the site. Such tasks as catalog data loads,
gathering user statistics, and reporting need to be performed. In addition,
functionality of the store may need to be serviced or modified.

© Copyright IBM Corp. 2001
79
Chapter 6.
Technology options
This chapter looks at the technology options to consider when developing
e-commerce and Web applications. The technologies are based upon the open
standards and Java-based business model of the IBM Framework for e-business.
We shall discuss technology options from the client technologies all the way to
back-end systems. This chapter provides guidelines for the technology options
available within each of the following topics:
Clients
Web application server
Commerce Server
Connectivity
6

80
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
6.1 Clients
e-commerce systems today can be accessed from a wide variety of clients, from
the ubiquitous Web browser to the newest cell phone. The e-commerce Web site
may needs to support a wide spectrum of client technologies to be competitive.
This section discusses the following types of clients:
Web browser client
Java applet
Application client
Mobile client
6.1.1 Web browser client
Web browser clients use the HTTP protocol to communicate with the Web
server. HTTP is a very lightweight protocol and allows the server to support large
loads even with relatively modest hardware. HTTP traffic can be encrypted using
Secure Sockets Layer (SSL) to maintain secure communications between the
browser and the server (Figure 6-1 on page 80).
Figure 6-1 Web client technology options
HTTP Server
XML + XSL
HTTP/HTTPS
Applet
JVM
Web Browser Client
Browser
Plugins
(Real,
Flash etc)
DHTML
HTML

Chapter 6. Technology options
81
A Web browser is a fundamental component of the Web client. For PC-based
clients, the browser typically incorporates support for HTML, DHTML, JavaScript
and Java. Some browsers are beginning to add support for XML as well. Under
user control, there is a whole range of additional technologies that can be
configured as “plug-ins”, such as RealPlayer from RealNetworks or Macromedia
Flash.
As an application designer you must consider the level of technology you can
assume will be available in the user’s browser. You can add logic to your
application to enable slight modifications based upon the browser level. Also,
when adding features that require a plug-in, you need to consider what portion of
your intended user community will have that capability.
For an e-business application that is to be accessed by the broadest set of users
with varying browser capabilities, the client is often written in HTML with no other
technologies. On an exception basis, limited use of other technologies, such as
using JavaScript for simple edit checks, can then be considered based on the
value to the user and the policy of the organization for whom the project is being
developed.
Markup languages
Different types of markup languages can be used inside of Web pages. Markup
languages use additional tags around the content to specify formatting or client
behavior.
HTML
HTML has the advantage of being the most widely accepted markup
language in use by Web browsers. The IBM Framework for e-business
encourages the use of thin clients -- and applications written with pure HTML
as the front end enjoy the advantages of being among the ‘thinnest’ clients.
Almost all browsers support HTML V3.2, which is often the lowest common
denominator for building the client side of an application.
DHTML
Dynamic DHTML brings a high level of flexibility to designing and displaying a
user interface.
Cascading Style Sheets (CSS) allow you to centrally control different fonts,
margins, and line spacing for various parts of the display, much like a modern
word processor. DHTML also allows interactivity in the Web page by
introducing scripting against a rich document object model and event model.
Tip: WebSphere Studio Page Designer includes tools that allow you to
perform HTML syntax checks against user-defined levels of HTML.

82
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Unfortunately DHTML implementations are found only on the more recent
browser versions. A small, basic set of functionality is common to both the
Microsoft and Netscape browsers, but differences appear in most areas. The
significant difference is that Microsoft allows the content of the HTML page to
be modified by using either JScript or VBScript, while Netscape only allows
the content to be manipulated (moved, hidden, shown) using JavaScript.
Due to the browser incompatibility issues, DHTML is not recommended in
environments where mixed levels and brands of browsers are present.
However, DHTML may be a viable option for implementing client-side input
validation or non-critical functions such as mouse interactions.
6.1.2 Java applet
Java applets provide the most flexible user interface technology that can be run
in a Web browser. A Java applet is a program written in Java that is downloaded
from the Web server and run inside a Java Virtual Machine (JVM) that is usually
embedded inside the Web browser.
JVMs embedded inside a browser usually run applets. This usually poses
significant issues with regards to cross-browser support of a given applet client.
Sun Microsystems introduced a Java plug-in to address the incompatibilities of
the JVMs across different browsers, but this requires the users to download and
install the plug-in. The IBM Framework for e-business discourages the use of
“heavy” applet clients unless specific client user interface requirements mandate
its use.
When used in a Web application, applets can be used in a number of different
ways, as shown in Figure 6-2.
Note: The WebSphere Commerce Suite Accelerator tool is an excellent
example of a DHTML client. It presents a slick interface, with dynamic buttons
and drop-down menus. However the trade-off is that only a specific version of
client browser (in this case Internet Explorer 5.5 or higher) is supported.

Chapter 6. Technology options
83
Figure 6-2 Java applet communication models
In mode 1 shown in Figure 6-2, the applet is used for enhanced display of
information coming from the Web server. Information is typically passed to the
servlet via applet parameters. This is one-way communication and may be useful
for displaying graphs, charts or navigational elements.
In mode 2, the applet can have two-way communication with the servlet. This
communication is in the form of HTTP request responses. To avoid issues with
different versions of Java being present on the server and the client, XML may be
used as a messaging protocol instead of passing serialized objects.
In mode 3, the applet communicates directly with the back-end EJB layer via
IIOP. While this allows the most flexible communications, this mechanism can
have significant security, deployment and compatibility implications and is
generally discouraged.
HTTP
Server
Servlet
Engine
EJB
Server
Plug In
Web Application Server
EJBs
Servlets
Mode 2:HTTP (HTML/XML)
Mode 3:RMI/IIOP
Mode 1:HTTP (HTML)
Applet
Java Virtual Machine
Web Application Server

84
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
6.1.3 Application client
Application clients are primarily large Java applets or Java applications. These
clients provide rich graphical user interfaces compared to HTML clients. They
may communicate with the Web application server over a number of protocols
including HTTP, IIOP, MQ, etc. Application clients communicate with the Web
application server primarily to receive data rather than pre-formatted HTML
pages. All of the user interface processing is performed on the client side. In
addition, under this model, some parts of the business logic can also be
processed on the client side. These kinds of client applications are not covered in
this book.
6.1.4 Mobile client
The mobile device market has increased dramatically over the past few years,
and promises to sustain this growth in the near future. Supporting mobile devices
brings its own unique set of challenges to e-commerce applications.
Mobile clients are not just another type of client. They are a whole class of client
applications, with wide variations in the device hardware capabilities, wireless
networks and the actual protocols and markup languages being used.
Compounding this is the fact that the mobile device landscape is constantly
changing.
While we must definitely consider the functional requirements of supporting the
required devices, network types and protocols, supporting a mobile client base
also forces us to consider important non-functional requirements, such as
brittleness, manageability and flexibility of the system, to be able to adapt to the
changing mobile environment.
In this section, we discuss some of the basic technology options for mobile
clients. In 6.3, “Commerce Server” on page 96, we examine application
considerations for mobile clients.
Mobile devices
A mobile device, in the context of this redbook, is a portable, generally small
wireless device that can be used to access the Internet via a browser. All mobile
devices are not created equal. There is a wide range of capabilities and
functionality.
Note: IBM HotMedia is an excellent example of the powerful use of applets in
mode 1 for displaying rich user interfaces. A sample of using HotMedia can be
found in the Web Fashion sample store.

Chapter 6. Technology options
85
We have categorized the wireless devices into three categories:
Mobile phones
Most of the recent models of wireless phones have some form of a
microbrowser embedded. While many devices are limited to voice and
one-way messaging (SMS or WAP push), others also have access to Internet
content via a browser.
These devices are often characterized by small screen sizes and limited input
methods. Examples are the Ericsson R380 WAP mobile phone and the NTT
DoCoMo 503i i-mode mobile phone.
Wireless PDAs
A Personal Digital Assistant (PDA) is a handheld computer with a wireless
interface that serves as an organizer for personal information. PDAs often
have a pen-like stylus to tap selections on menus and to enter printed
characters. Examples are the Palm VIIx, Epoc, and Pocket PC.
Although the stylus interface is generally adequate for navigating through
browser screens, entering larger amounts of data may be inconvenient with
these devices.
Wireless laptops
This category includes laptops, notebooks, or portable PC browser clients
that have a wireless interface to the network for Internet access. These clients
use standard TCP/IP protocols and a standard, full-featured browser.
The only additional consideration for these devices is that the wireless
connection is usually much slower than for wireline-based network clients. An
example of a wireless notebook is the IBM ThinkPad T20 with a wireless PC
card adapter.
The capability between the mobile device categories continues to be blurred. For
example, some phone manufacturers are developing PDA-like functionality into
mobile phones and providing larger screens and easier methods of input.
Wireless networks
Wireless networks are used to transmit data between mobile devices using
wireless adapters without the use of a physical cable or wire. While the choice of
network technology is generally a given in any project, it is important to
understand the features and limitations of the network technology available.
From an e-commerce perspective, the features that will affect us the most are:
Data transmission capabilities of the network
Network bandwidth available for data transmission

86
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
While network technologies and variations abound, we shall mention the three
most important technologies:
GSM
The Global Systems for Mobile Communications (GSM) standard is one of
the most important and widespread mobile standards worldwide. Many
variants of GSM have been created for different frequency ranges.
Typical GSM data speeds are around 9600 bps. GSM also supports many
other services such as Short Message Service Point-to-Point (SMS-PP),
Short Message Service Cell Broadcast (SMS-CB) and the Unstructured
Supplementary Services Data (USSD).
GPRS
General Packet Radio Service (GPRS) is a fundamental step in the migration
from GSM to 3G networks. This evolution path is represented in Figure 6-3.
GPRS can offer significantly higher bandwidth than GSM.
Figure 6-3 Projected evolution of wireless network technologies
IMT-2000/ UMTS
International Mobile Telecommunications-2000 (IMT-2000) is a third
generation (3G) wireless system. IMT-2000 offers support for a wide range of
mobile devices, includes links to terrestrial and/or satellite-based networks,
and the terminals may be designed for mobile or fixed use.
2G
2.5G
3G
GSM
9.6 Kbps
HSCSD
57.6 Kbps
GPRS
172.4 Kbps
EDGE
384 Kbps
UMTS
2 Mbps
1998
1999
2000 2001 2002

Chapter 6. Technology options
87
The Universal Mobile Telecommunications System (UMTS) is the European
implementation of the 3G wireless phone system. UMTS was designed as an
evolutionary system for GSM network operators, and offers impressive data
rates of up to 2 Mbps. UMTS uses the W-CDMA technology. GPRS and
EDGE are interim steps that will speed up wireless data for GSM.
Wireless protocols
Wireless protocols are used to connect mobile devices to the Internet. Many of
the wireless protocols have defined architectures that optimize the use of the
radio resource and also minimize the capabilities required for the device.
HTTP
The most obvious way of accessing Web-based applications from a mobile
device is to use the HTTP protocol to retrieve standard HTML content, as if
we were accessing the Internet through a fixed workstation.
This approach, which is very suitable for wired connections, presents many
limitations when adopted to wireless networks. Some of them are:
– Wireless networks usually have much less bandwidth and higher latency
than wired networks.
– Wireless connections are less stable in nature than wired connections and
are also unpredictable in terms of availability.
– Most mobile devices have limitations in display and input capabilities and
may not be able to deal with all the features of full HTML.
TCP/IP-based protocols work well over wireless connections. However, the
performance is slow over wireless networks. Many alternative protocols and
markup languages have been created for mobile environments. Simplified
markup languages have also evolved that are optimized for the limited
bandwidth available and the limited capabilities of the mobile device.
WAP
The Wireless Access Protocol (WAP) technology uses a protocol stack
different from HTTP and a new markup language, such as WML. Moreover, it
introduces a new scripting language for mobile devices, which is the
equivalent of JavaScript in the Internet world.
WAP is the dominant protocol in Europe and also available in many parts of
the US.
Note: While describing each of the wireless network services exhaustively is
beyond the scope of this book, we refer the reader to the redbook Mobile
Commerce Solutions Guide using WebSphere Commerce Suite V5.1,
SG24-6171.

88
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
i-mode
The i-mode approach defines a new markup language, which is called
Compact HTML (or more simply cHTML) and, as the name suggests, is a
subset of HTML with a few special tags. However, unlike WAP, it still relies on
the HTTP protocol.
One of the important features of i-mode is that it is a packet-based protocol,
much like HTTP. On the other hand, WAP is a circuit-based protocol.
i-mode is dominant in Japan and is planned to be rolled out in the US by
2002.
Web Clipping
The Palm Web Clipping solution uses the HTTP and HTTPS protocols, but
the page content is encoded according to a Palm proprietary format, called
the Web Clipping Application (WCA) format. The content is retrieved from the
content server in standard HTML and is then translated into WCA format by a
proxy for proper rendering on the Palm device.
As the next-generation networks (for example, IMT-2000/UMTS) become
available, which provide very high data throughputs, the HTTP and HTTPS
protocols and HTML markup language become a much more viable solution for
mobile devices.
Content and markup languages
HTML
The use of HTML as a markup language has already been discussed. It is
important to remember the bandwidth considerations, especially while
designing for slower networks.
HDML
Handheld Device Markup Language (HDML) is a specialized version of
HTML, designed to enable wireless pagers, cell phones, mobile phones and
other handheld devices to obtain information from Web pages. HDML was
developed by Phone.com before the WAP specification was standardized. It
is a subset of WML with some features that were not included in WAP.
HDML is still widely used in the US and has several million users in Japan,
although the dominant markup language and service are cHTML used with
i-mode. The UP.Browser developed by OpenWave Phone.com provides
support for HDML markup.

Chapter 6. Technology options
89
WML
Wireless Markup Language (WML) is a tag-based language used in the
Wireless Application Protocol (WAP). WML is an XML document type
allowing standard XML and HTML tools to be used to develop WML
applications. It evolved from Phone.com's HDML, but WML is not a superset
of HDML. The WML specification is now managed by the WAP consortium.
Certain HDML features are not found in WML.
cHTML
Compact HTML (cHTML) is a more efficient variation of HTML specifically
designed for use by the i-mode wireless service.
XHTML
Extensible HTML (XHTML) is a combination of HTML 4.0 and XML 1.0 into a
single format for the Web. XHTML is expected to become the standard format
for Web pages. XHTML also makes it possible for Web pages to be
developed with different sets of data, depending on the type of browser used
to access the Web. Increasingly, handheld devices used for the Web must
download abbreviated pages, because they do not have screen displays
large enough and are not capable of handling graphics. XHTML makes it
easier to do this.
6.2 Web application server
There are many models for Web application servers. We shall confine our
discussion to the JavaServer model that is based on the Java 2 Enterprise
Edition (J2EE).
This model is gaining widespread support in the market. It also addresses the
goals of the IBM Framework for e-business very well.

90
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 6-4 Web application server architecture
Figure 6-4 provides an overview of the Web application server architecture. The
server-side application can have different clients as we discussed in previous
pages. First, we discuss interaction from a browser-based (HTTP) client.
The client makes all its requests to the HTTP Server. Immediately behind the
HTTP server, the servlet engine forms the first execution layer. Different
programming artifacts run inside the servlet engine: servlets, which are pure
Java code, and JavaServer Pages (JSPs), which are markup tags blended with
scripts written in Java.
Core business logic in the application is often written as Enterprise Java Beans
(EJBs). EJB servers provide many of the enterprise services that these
application components are likely to need. The services include naming, security,
persistence, distribution, life-cycle management, etc.
CCF
HTTP
Server
Servlet
Engine
EJB
Server
Plug In
MOMs
(MQ Series)
LDAP
(SecureWay
Server,NES)
Legacy
Systems
(CICS,IMS)
CCF
Web Application Server
JNDI
JMS
JDBC
Enterprise
Services
EJBs
Servlets
JSPs
Native API
HTTP
IIOP
RDBMS
(DB2,
Oracle)
Browser
Client
Application
Client

Chapter 6. Technology options
91
Additionally, a Web application cannot exist in isolation. A number of open
standard APIs exist for communicating with the business back-end systems or
other e-commerce applications. We will cover some of these connectivity APIs in
6.4, “Connectivity” on page 108.
Before looking at the technologies and APIs available in the Web application
programming environment, a word about two fundamental operational
components on this node, the HTTP server and the Java Virtual Machine (JVM).
For production applications, these essential components should be chosen for
their operational characteristics in areas such as robustness, performance and
availability.
We shall talk about the constituent APIs next. For more details on the Java APIs
discussed in this section, see Java Enterprise in a Nutshell by David Flanagan,
Jim Farley, William Crawford and Kris Magnusson.
6.2.1 Java Servlets
Java Servlets (servlets) are small Java programs that run inside the servlet
engine on the Web application server. They interact with the Web users through
HTTP requests and responses, which are encapsulated as objects in the servlet.
The specification for writing servlets is provided by the simple and elegant Java
Servlet API. The most current level of the servlet API is 2.2. To learn more about
the Servlet API visit:
http://www.javasoft.com/products/servlet/
Servlets are a core technology in the Web application programming model. They
are the recommended choice for implementing the Interaction Controller classes
that handle HTTP requests received from the Web client.
For more details on the effective use of servlets, see Chapter 7, “Application
design guidelines” on page 115.
Note: Although most of the server side APIs are now standard, different
versions of these API exist and are supported by existing products. J2EE
makes a good effort to standardize the API version levels but the picture is still
far from perfect.
Care must be taken to match compliant versions of these APIs across
products, especially when selecting products from different vendors. In this
book, unless otherwise specified, we refer to the versions supported by
WebSphere Application Server V3.5.2, Advanced Edition.

92
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
6.2.2 JavaServer Pages (JSPs)
JSPs were designed to simplify the process of creating pages by separating Web
presentation from Web content. In the page construction logic of a Web
application, the response sent to the client is often a combination of template
data and dynamically generated data. In this situation, it is much easier to work
with JSPs than to do everything with servlets.
The chief advantage JSPs have over Java servlets is that they are closer to the
presentation medium. JSPs can contain all the HTML tags that Web authors are
familiar with. A JSP may contain fragments of Java code embedded within the
HTML. This code encapsulates the logic that generates the dynamic content for
the page. The code fragments may use beans to access reusable components
and back-end data. To learn more about JSPs visit:
http://www.javasoft.com/products/jsp/
JSPs are compiled into servlets before being executed on the Web application
server. The most current level of the JSP API is 1.1, although WebSphere
Commerce Suite V 5.1 supports level 1.0.
JSPs are the recommended choice for implementing the “view” that is sent back
to the Web client. For those cases where the code required on the page will be a
large percentage of the page, and the HTML minimal, writing a Java servlet will
make the Java code much easier to read and therefore maintain.
While the most common use for JSPs is to display HTML pages, they can also
be used for other types of markup, such as XML and WML.
The messaging subsystem makes excellent use of JSPs as templates for
generating an outbound XML message for MQSeries. For more information, refer
to Chapter 14, “Messaging integration” on page 361.

Chapter 6. Technology options
93
6.2.3 JavaBeans
The JavaBeans architecture describes an API and a set of conventions for
reusable, Java-based components. Code written to JavaBeans architecture is
called Java beans or just beans. One of the design criteria for the JavaBean API
was support for builder tools that can compose solutions that incorporate beans.
Beans may be visual or non-visual.
Beans are recommended for use in conjunction with servlets and JSPs in the
following ways:
As the client interface to the “model layer”. An “Interaction Controller” servlet
will use this bean interface.
As the client interface to other resources. In some cases this may be
generated for you by a tool.
As a component that incorporates a number of property-value pairs for use by
other components or classes. For example, the JSP specification includes a
set of tags for accessing bean properties.
For more details on the effective use of beans see 7.5, “Application
component design” on page 132.
A note about API versions:
As has been noted before, API version issues often arise when working with
JavaServer applications. For example, although the latest version of the JSP
API is 1.1, WebSphere Commerce Suite supports level 1.0.
One of the big changes in 1.1 is the support for custom tags in JSPs, which
allow for much cleaner JSP code. You cannot use custom tags with the
WebSphere Commerce Suite JSPs.
This is because of the fact that the WebSphere Application Server 3.5.2 or
higher can be run either in compatibility mode (support for the older versions)
or in J2EE compliance mode where it supports the newer versions of the API.
WebSphere Commerce Suite works in compatibility mode.
For more information on this subject, please refer to the WebSphere
Application Server InfoCenter.

94
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
6.2.4 Enterprise JavaBeans (EJBs)
Enterprise JavaBeans (EJBs) make up the component model prescribed by
J2EE. From our earlier discussion (Figure 6-4 on page 90) we know that EJBs
are ideally used to implement core business logic in a central place so that all
applications throughout the enterprise can use these components.
The nomenclature is somewhat misleading, because EJBs do not really have a
lot in common with their far more lightweight cousins, JavaBeans. Enterprise
JavaBeans are distinguished from Java beans in that they are designed to be
installed on a server, and accessed remotely by a client.
EJBs are coarse-grained application components that have “enterprise services”
built in. The services include:
Life cycle management (to manage both load and high availability)
Naming
Security management
Transaction management
Workload management
Persistence management
All EJBs run inside EJB containers that plug into the bean with all these services.
The intent is that the “plumbing” required to implement transactions or database
access can be implemented by the EJB container. The EJB developer specifies
the required transactional and security characteristics of an EJB in a deployment
descriptor (this is sometimes referred to as declarative programming). In a
separate step, the EJB is then deployed to the EJB container provided by the
application server vendor of your choice.
There are two types of Enterprise JavaBeans:
Session beans
Entity beans
Session beans
These are process or “worker” beans. Enterprise Javabeans by Richard
Monson-Haefel refers to these beans as those business entities that you can
model as verbs.
A typical session bean has the following characteristics:
Executes on behalf of a single client.
Can be transactional.
Can update data in an underlying database.
Is relatively short lived.

Chapter 6. Technology options
95
Is destroyed when the EJB server is stopped. The client has to establish a
new session bean to continue computation.
Does not represent persistent data that should be stored in a database.
Provides a scalable runtime environment to execute a large number of
session beans concurrently.
Entity beans
These are “data” beans. Enterprise Javabeans by Richard Monson-Haefel refers
to these beans as those business entities that you can model as nouns.
A typical entity bean has the following characteristics:
Represents data in a database.
Can be transactional.
Shared access from multiple users.
Can be long lived (lives as long as the data in the database).
Survives restarts of the EJB server. A restart is transparent to the client.
Provides a scalable runtime environment for a large number of concurrently
active entity objects.
Typically an entity bean is used for information that has to survive system
restarts, while in session beans, the data is transient and does not survive when
the client's browser is closed. For example, a shopping cart containing
information that may be discarded uses a session bean, and an invoice issued
after the purchase of the items is an entity bean.
An important design choice when implementing entity beans is whether to use
Bean Managed Persistence (BMP), in which case you must code the JDBC logic,
or Container Managed Persistence (CMP), where the database access logic is
handled by the EJB container.
The business logic of a Web application often accesses data in a database.
Entity beans are a convenient way to wrap the relational database layer in an
object layer, hiding the complexity of database access. Because a single
business task may involve accessing several tables in a database, modeling
rows in those tables with entity beans makes it easier for your application logic to
manipulate the data.
The latest EJB specification is 1.1. The most significant changes from EJB 1.0
are the use of XML-based deployment descriptors and the need for vendors to
implement entity bean support to claim EJB compliance.

96
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
To learn more about Enterprise JavaBeans visit:
http://www.javasoft.com/products/ejb/index.html/
6.3 Commerce Server
The Commerce Server is the software engine that actually runs the e-commerce
site. WebSphere Commerce Suite V5.1 is a complete, scalable, and extendable
solution for creating robust, secure, dependable and scalable e-commerce
solutions of all sizes. Constructed with a new open Java architecture,
WebSphere Commerce Suite provides all the tools a company needs to launch
and run comprehensive e-commerce solutions, whether it is building a business
on the Web, expanding existing business to the Web, or integrating Web
business with back-end business systems.
The Commerce Server should enable us to:
Increase customer value on a global scale
Collaborate with customers, suppliers and trading partners
Create effective targeted-marketing programs
Strengthen customer relationships
Open your business to new audiences of mobile users
Customize e-commerce solutions to specific business needs without
spending a lot of money and time
Enable powerful interactions with enterprise databases and transaction
systems
The technical foundation of the e-commerce engine enables us to gauge its
scalability, manageability, ease of customization, etc. While providing a majority
of the features out of the box, the commerce engine will often need
customization and integration with the rest of the business. The commerce
engine should have a well-documented and robust internal architecture that
allows for these customizations without excessive overhead.
Note: IBM WebSphere Application Server V3.5, Advanced Edition (and
WebSphere Commerce Suite V5.1) officially only support EJB V1.0.
However, in most aspects the WebSphere Application Server complies with
the 1.1 specification and in some respects even implements features that are
likely to be found in EJB V1.2, which is in beta testing at the time of writing.
As the J2EE specification matures, this picture will hopefully get clearer.

Chapter 6. Technology options
97
On the other hand, an e-commerce server is not just a technical solution. The
Commerce Server also needs to provide tools for the day-to-day administration
and management of the store.
We will now examine some of the support that WebSphere Commerce Suite
provides for this.
6.3.1 WebSphere Commerce Suite architecture
The WebSphere Commerce Server Engine is built on top of the WebSphere
Application Server runtime. This means that it utilizes the robust and hardened
services of WebSphere for important enterprise services such as:
Transactions
Work load management
Persistence management
Security infrastructure (although WebSphere Commerce Suite makes
significant additions to this)
Session management
Connectivity
Clustering and scaling
In addition to using proven core technology, this architecture has an additional
advantage. Customization of WebSphere Commerce Suite can now be done
using industry-standard technologies such as JSP, EJB, etc., which increase the
maintainability of the system.
Figure 6-7 on page 103 shows the major parts of the WebSphere Commerce
Server Engine.

98
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 6-5 WebSphere Commerce Suite components
Member subsystem
The member subsystem handles organizations, users, member groups and
organizational entities. This includes the business logic for registration, profile
management, access control authentication, etc.
The WebSphere Commerce Suite member subsystem supports different types of
members -- buyers or organizations. This allows a great degree of flexibility in its
use. Member data can be obtained from an LDAP server for integration with
other applications.
The member subsystem also provides out-of-the-box functionality for customer
profiles, address books, and a role-based security model.
HTTP
Server
Order
Subsystem
WAS
E - Mail
Configuration
Manager
Member
Subsystem
Negotiations
Subsystem
Catalog
Subsystem
File
MQSeries
Common
Server
Runtime
System
Management
Messaging
Subsystem
Scheduling
Subsystem
Commerce
Acclerator
Commerce
Administrator
Store
Services
Configuraton
Manager
Server
Configuration
Files

Chapter 6. Technology options
99
Catalog subsystem
The catalog subsystem is a component of the WebSphere Commerce Server
that provides online catalog navigation, partitioning, categorization, and
associations. In addition, the catalog subsystem includes support for
personalized interest lists and custom display pages.
The catalog system in WebSphere Commerce Suite supports:
Groupings
You can categorize various products using a generic grouping system. The
owner of a catalog group does not necessarily have to be the owner of all the
catalog entries in the group.
Online catalog entries
Catalog entries are the base set of objects that represent merchandise for
sale. Common types of online catalog entries are products, items, packages,
and bundles. Also, trading positions are used for dynamic pricing based on
contracts, and opening and reserving prices for negotiation.
Merchandising associations
This feature enables associations for merchandising purposes. These
become cross-sells, up-sells, and accessories.
Order subsystem
The order subsystem is a component of the WebSphere Commerce Server that
provides shopping carts, order processing, and management function support.
Related services, such as pricing, taxation, payment and fulfillment, are also part
of the order subsystem.
Order processing capabilities include quick order or buy, scheduled orders,
multiple pending orders, and reorders.
Payment subsystem
All payment functionality in WebSphere Commerce Suite comes from
WebSphere Payment Manager.
Payment Manager is a protocol-independent payment transaction server for an
online merchant. It provides cash register-like functionality to a site, supporting
multiple payment methods using protocol-specific cassettes. These cassettes
are software components that can be attached to the Payment Manager
framework to interpret generic payment and administrative commands into
payment protocol-specific requests, which are then forwarded to the appropriate
recipient, such as the payment gateway of an acquirer institution. The end result

100
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
is similar to when a cashier swipes a payment card at the checkout counter in a
traditional store. Cassettes for CyberCash, SET and offline payment processing
are included with Payment Manager. Numerous other cassettes are available as
add-ons.
The Payment Manager handles all the background details of Internet payments
on behalf of the merchant (or a group of merchants, such as a shopping mall),
and provides a graphical interface to simplify the transaction management.
Other features
WebSphere Commerce Suite also provides support for additional features that
support the online store.
Marketing campaigns
WebSphere Commerce Suite V5.1 provides an extensive set of tools for driving
the marketing objectives of an e-commerce Web site. The tools included allow
the creation and organization of marketing campaigns.
The Commerce Suite Accelerator is a business intelligence system that can be
used to provide information on the demographics of the users of the system. This
valuable information can be used as input for the creation of marketing
campaigns. The implementation of marketing campaign features is available in
the Commerce Suite Accelerator. It can also be used to report on the success of
marketing campaigns.
Personalization
WebSphere Commerce Suite V5.1 includes several products to implement
personalization for your commerce Web site:
Blaze Advisor V3.1 (rules-based)
Macromedia LikeMinds V5.1 (collaborative filtering)
WebSphere Personalization V3.5 (rules-based)
These personalization products can be used to personalize content of your Web
site for the user, and provide support of a marketing campaign by implementing
selling techniques, such as cross-selling, up-selling, specials, etc.
Auctions
Commerce Suite provides tools to help create and manage auctions for your site.
You can choose from one of the existing auction types (open cry, sealed bid, and
Dutch auction) or create custom auction styles.
The tools for creating and managing auctions are included in the Commerce
Suite Accelerator.

Chapter 6. Technology options
101
Multicultural support
Support for a culturally diverse customer base is now built in to WebSphere
Commerce Suite. Stores can tailor their operations to the location or cultural
preference of the user, by using the same database and Web assets (JSPs) with
different language files (properties files). The key multicultural features include
support for multiple languages, multiple currencies, culture-specific data (formats
for dates, addresses, and numbers), different taxation rules, different shipping
rules, multiple payment methods, and different prices.
Multicultural support is implemented using a combination of database
enhancements and property files.
6.3.2 Development technology considerations
No matter how many features the commerce system provides out of the box,
there is always a need to customize it. This is usually necessary for:
Integrating the e-commerce site with the rest of the business.
Extending or changing existing functionality to suit business requirements.
WebSphere Commerce Suite has a rich and flexible architecture to support
customization.
Programming model overview
Figure 6-7 on page 103 shows the programming model for WebSphere
Commerce Suite V5.1. It is a very powerful layered architecture that makes it
easy to support features such as multiple client types, multicultural support,
extending and overriding existing commands and connecting to back-end
systems.
Model-View-Controller (MVC)
The WebSphere Commerce Suite application architecture is based on the
Model-View-Controller (MVC) architecture. MVC is a very useful model for
applications with a heavy user interface (UI) component. MVC allows the
application to adapt easily to changes in the UI or the implementation of the
business logic.

102
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 6-6 Model-View-Controller architecture
As shown in Figure 6-6, MVC divides the application into three layers:
Model
The model implements the core business logic in the system. In the
WebSphere Commerce Server, it is implemented by EJBs and Java classes
(task commands and databeans).
View
The view is the component that is responsible for the output to the client. In
the WebSphere Commerce Server, the view is implemented by JSPs.
Controller
The controller is the layer that establishes isolation between the model and
the view. It plays the role of a traffic cop, intercepting all incoming requests
and invoking the right commands on the model and the view. In the
WebSphere Commerce Server, the primary implementation of the controller
is the Web controller.
Let us take a brief look at the different layers in the architecture shown in
Figure 6-7.
Model
URL Commands
View
Controller
HTML
JSPs
Commands,
EJBs
Web
Controller

Chapter 6. Technology options
103
Figure 6-7 WebSphere Commerce Suite 5.1 programming model
Protocol listeners
In Figure 6-7, the first layer is the protocol listener. The protocol listeners manage
the various inbound protocols that the Commerce Server might have to
communicate with, for example MQSeries or HTTP.

104
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Adapter framework
Supporting the protocol listeners are the various device adapters. These
adapters convert the incoming request to a format that the command framework
can understand. They may also perform additional functions to support session
management, persistence etc. required to support a specific device. A device
may be a physical entity (such as a WAP phone or a browser) or a logical entity
(such as the Scheduler subsystem).
Web controller
The Web controller is an application container that follows a design pattern
similar to that of an EJB container. This layer simplifies the role of commands, by
providing such services as session management (based upon the session
persistence established by the adapter), transaction control, access control and
authentication. The Web controller, as the name suggests, performs the basic
roles of the MVC controller.
The inclusion of the Web controller layer in the architecture means that the
individual commands (which we can customize) implicitly get important services
such as transactions and session management.
By the time the client request reaches the Web controller, it is in a device- and
protocol-independent format. The Web controller then looks at the command
registry and determines which controller command to invoke. Developers can
easily override the default implementation of WebSphere Commerce Suite
commands.
Command registry
The command registry is a set of three database tables that allow the Web
controller to dynamically map an incoming request to the right command
depending on the client device and the store for which the request is intended.
This way, different stores can implement different commands, for example
OrderProcess, differently.
The command registry is one of the primary tools available for customization. It
also allows for very easy isolation between the view and the model, as you can
map an incoming URL request to any command implementation. The view JSP
that is presented to the client can also be easily changed using the command
registry.
Controller commands
A controller command encapsulates the logic related to a particular business
process. Controller commands represent the coarse-grained business logic in
the Commerce Server. Examples of controller commands include the
OrderProcessCmd command for order processing and the
UserRegistrationAddCmd command for creating new registered users.

Chapter 6. Technology options
105
In general, a controller command contains the control statements (for example,
if, then, else) and invokes task commands to perform individual tasks in the
business process. Upon completion, a controller command returns a view name.
The Web controller then determines the appropriate implementation class for the
view task and executes the view task.
Task command
Fine-grained business logic is implemented by task commands, which are
invoked in the correct order by the controllers. Task commands communicate
with the back-end database using an elaborate framework of access beans and
Enterprise JavaBeans.
Enterprise JavaBeans
All access from the Commerce Server to the back-end database schema is
mediated by Enterprise JavaBeans. In addition to providing uninitiated
object-oriented access to the e-commerce data, this layer allows for scalability
and robustness for the entire system.
The advantages of an EJB-based application have already been discussed.
Access beans and databeans
Access beans and databeans form the mediation layer that allows the commerce
application to communicate efficiently and easily with the access beans.
Access beans have a one-to-one relation to EJBs. Access beans simplify the
task of accessing an EJB by hiding a lot of the access code. In addition they also
implement various levels of caching to allow more efficient access to the EJBs.
Databeans package data objects into manageable beans for use by the view
layer JSPs. The life cycle of databeans is managed by the data bean manager.
View command
Finally, output is handled using device-specific JSPs, which form the view. A
single view command can map to different implementation JSPs depending on
device type and store. Since the JSP technology is well known, this minimizes
the learning curve for the most common type of customizations.
Configuration data for the system is implemented as XML files.
For more detailed coverage of this framework, refer to the IBM WebSphere
Commerce Suite V5.1 Programmer’s Guide. Additional information can also be
found in 7.1, “WebSphere Commerce Suite programming model” on page 116.
We can see that the Commerce Server is based on a robust MVC architecture
and provides various levels of customization.

106
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Tool support
WebSphere Commerce Suite is built completely on top of WebSphere
Application Server. This allows us to use the entire WebSphere development tool
set for Commerce Suite customization. The WebSphere Commerce Studio
includes the following tools.
VisualAge for Java
VisualAge is IBM’s Java IDE. It includes such tools as:
WebSphere test environment
EJB development environment
JSP execution monitor
These allow developers to write, unit test, debug and deploy servlets, JSPs and
EJBs without ever leaving VisualAge. For more information, see Chapter 8,
“Application development guidelines” on page 147.
WebSphere Studio
WebSphere Studio is IBM’s tool for creating, managing and deploying Web
assets. It includes:
Page Designer -- for creating and editing HTML and JSP files
Graphics tools for working with Web page graphics
Wizards, rule editors and tools for working with personalization servers
JSP wizards
Extensions that allow for working with commerce assets such as SAR files
For more information, refer to Chapter 8, “Application development guidelines”
on page 147.
6.3.3 Runtime technology considerations
After the store has been created and deployed, it must be constantly maintained
as a part of day-to-day business and IT functions. One of the important features
of a Commerce Server is the tools and interfaces that it provides for such
maintenance.
WebSphere Commerce Suite provides a number of tools for configuration,
administration and management of the stores from an I/T as well as business
operations perspective.

Chapter 6. Technology options
107
WebSphere Commerce Suite Configuration Manager
The WebSphere Commerce Suite Configuration Manager is a Java
application-based tool used to create and configure a WebSphere Commerce
Suite instance. The Configuration Manager provides the administrator the ability
to configure WebSphere Commerce Suite instances, WebSphere Application
Server, Web Server, Payment Manager, messaging, and session management.
WebSphere Commerce Suite Store Services
The WebSphere Commerce Suite Store Services is a Web browser-accessible
tool. It allows you to quickly create a store archive based on a sample store.
Once the store archive has been created, Store Services can be used to publish
the archive and make general changes to store properties such as tax, shipping
information, etc.
WebSphere Commerce Suite Administration Console
The WebSphere Commerce Suite Administration Console is a Web
browser-accessible tool that allows you to maintain your online stores by
completing day-to-day administrative operations. These include:
– Managing users and access groups
– Restricting customer commands from stores
– Transports and messaging for the site and store
– Monitor performance of the site
– Payment Manager settings
– Administering Blaze rules
WebSphere Commerce Suite Accelerator
The WebSphere Commerce Suite Accelerator is a Web browser-accessible tool
that allows business users to perform day to day business operations on the
store. This tool has various access control roles that can be used to access it:
– Merchant
– Marketing manager
– Merchandising manager
– Order clerk
– Customer service representative
These users can do various business operations ranging from completing orders
for customers and checking order status to deploying and monitoring a storewide
marketing campaign.

108
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Catalog management
After the initial deployment of the store and database assets, the catalog must be
maintained and updated with new data. This is one of the crucial administrative
functions for any commerce site.
There are different ways to add, update and maintain data for a WebSphere
Commerce Suite Web site depending upon the amount of data to load, number
of tables that will be impacted, the type of runtime environment, available
hardware infrastructure and possibly other parameters that affect performance
and system downtime.
With WebSphere Commerce Suite, the catalog can be updated as follows:
As a part of the Store Archive (SAR) publish process
Using XML files and the Loader utilities, which can be accessed
programmatically or using a command line
Using Catalog Manager
Individual catalog entries can be modified using the Commerce Suite
Accelerator interface.
For more information, refer to:
Chapter 12, “Catalog management” on page 303
WebSphere Commerce Suite V5.1 Handbook, SG24-6167
6.4 Connectivity
An e-commerce server cannot exist in isolation. It needs to connect to data
sources, back office systems, other e-commerce systems etc., to form an
effective business solution. In this section we explore some of the connectivity
technologies available.
6.4.1 Java Database Connectivity (JDBC)
The business logic in a Web application will access information in a database for
a database-centric scenario. JDBC is a Java API for database-independent
connectivity. It provides a straightforward way to map SQL types to Java types.
With JDBC you can connect to your relational databases, and create and
execute dynamic SQL statements in Java.

Chapter 6. Technology options
109
JDBC drivers are RDBMS specific, provided by the DBMS vendor, but implement
the standard set of interfaces defined in the JDBC API. Given common schemas
between two databases, an application can be switched between one and the
other by changing the JDBC driver name and URL.
An important technique used to enhance the scalability of Web applications is
connection pooling, which may be provided by the application server. When
application logic in a user session needs access to a database resource, rather
than establishing and later dropping a new database connection, the code
requests a connection from an established pool, returning it to the pool when no
longer required.
JDBC 2.0 implements connection pooling using data sources. Data sources are
typically created by the administrator. Java programs just look up the data source
using JNDI and then use it to obtain connections to the database.
6.4.2 Java Messaging Service (JMS)
The JMS API enables a Java programmer to access message-oriented
middleware such as MQSeries from the Java programming model. Such
messaging middleware is a popular choice for accessing existing enterprise
systems and is one of your options if you are implementing a solution based on
Application pattern 2.
The redbook WebSphere Commerce Suite V5.1 Handbook, SG24-6167 has
good coverage of MQ Series configuration for WebSphere Commerce Suite.
Additional material on customizing the messaging subsystem can be found in
Chapter 14, “Messaging integration” on page 361.
6.4.3 Java Transaction API (JTA)
This Java API for working with transaction services is based on the XA standard.
With the advent of EJBs, we rarely have to program directly to this API. However
it is an important consideration for determining the transactional behavior of our
systems and features such as the ability to support distributed transactions
across multiple back-end resources.
It is important to remember that in the case of RDBMS, the JDBC driver is the
Resource Manager for JTA as well, so care must be taken in choosing the right
driver that supports transactional characteristics such as two-phased commit
(2PC).

110
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
6.4.4 Java Naming and Directory Interface (JNDI)
This package provides a common API to a directory service. JNDI allows objects
to be “bound” and subsequently “looked up” in the directory.
JNDI allows for a complex hierarchy of contexts and subcontexts to be created.
Applications should take care in using this name space and this should be
considered as a part of the design process.
Service provider implementations include those for LDAP directories, RMI and
CORBA object registries. Sample uses of JNDI include:
Accessing a user profile from an LDAP directory
Locating and accessing an EJB Home
LDAP directories are used to provide central storage for member information
across different applications. For more information on using LDAP databases
refer to Chapter 11, “User management and security” on page 261.
6.4.5 XML
Since its introduction, XML has been hyped tremendously as the panacea for
e-commerce. The human-readable XML tags provide a simple data format, but
the intelligent defining of these tags and common adherence to their usage will
determine their value. For example, commercial XML (cXML) from Ariba and
Common Business Library (CBL) from Commerce One are some of the first XML
vocabularies for business data. DSML is a set of XML tags that defines the items
in a directory. XML tags are defined in an XML schema, which defines content
type as well as name. XML tags can also be described in the original SGML DTD
format, since XML is a subset of the SGML language. There are several Web
sites that provide repositories for publishing and reviewing XML schemas. Web
Services also uses XML messaging.
In WebSphere Commerce Suite, XML is used in the following ways:
Configuration files
When you use the Commerce Suite configuration manager to create or
modify a WebSphere Commerce Suite instance, it generates the
configuration as XML files. These files are then read by the Commerce Server
on startup for configuration. A lot of other configuration data is also stored as
XML files.
Data files
Data loading into the Commerce Server is done using XML files. For
example, when a store is published using the Store Services tool, catalog
data is supplied using XML files.

Chapter 6. Technology options
111
Presentation layer
XML is also used in the presentation layer inside of JSPs. For example,
composition of an outbound XML message is done using a JSP that writes
dynamically generated XML.
6.4.6 Common Connector Framework (CCF)
e-business connectors are gateway products that enable you to access
enterprise and legacy applications and data from your Web application.
Connector products provide Java interfaces for accessing database, data
communications, messaging and distributed file system services.
IBM provides a significant set of e-business connectors with tool support, for
CICS, Encina, IMS, MQSeries, DB2, SAP and Domino. IBM bases its tool
support on the Common Connector Framework (CCF). For resources on z/OS,
IBM delivers native connectors based on CCF.
The command bean model allows you to code to the specific connector
interface(s) of your choice while hiding the connector logic from the rest of the
Web application.
Connectors are particularly important if you are implementing Application pattern
2 in your solution, which requires back-end integration to legacy systems.
6.4.7 Web Services
Traditionally, connecting two e-business applications together has required a lot
of custom configuration and coding. One of the latest trends in this field is a
cross-platform multi-vendor effort called Web Services.
Web Services are modular business applications that use a combination of open
standards and protocols to allow e-business applications to describe, register,
advertise their capabilities and then communicate with other e-commerce
applications across platform and language boundaries.
Web Services are based on three foundational technologies:
Simple Object Access Protocol (SOAP)
SOAP is a lightweight, XML-based messaging protocol that was developed
cooperatively by IBM and Microsoft. The SOAP framework allows
heterogeneous systems to communicate with each other in combination with
a variety of network protocols such as HTTP, FTP, RMI/IIOP, or MQ.
Web Services Description Language (WSDL)

112
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
WSDL is an XML protocol that allows a “Web Service” to describe itself.
WSDL separates the service interface from its implementation, so industry
standards organizations can define standard service interfaces for those
industries.
Universal Description, Discovery and Integration (UDDI)
UDDI is a mechanism for holding descriptions of Web Services. Like a
conventional directory entry, a UDDI entry might hold information about the
business hosting the service, service attributes offering taxonomies, etc.
Although this is still a very nascent technology, the possibilities are very
promising. While the initial impact of Web Services is likely to be B2B
applications, B2C applications may also derive significant value.
6.4.8 Electronic Commerce Markup Language (ECML)
ECML is a standard that allows merchant applications to collect customer data
from online wallets. If the commerce system is implemented using an
ECML-enabled wallet, then customers do not have to fill out a lengthy form for
purchase.
This standard was released by an industry consortium in 1999. However, given
the widespread acceptance of online commerce, the use of wallets is not
pervasive in e-commerce scenarios today. Hence, the value of ECML support
may not be remarkable in many e-commerce applications.
6.5 Where to find more information
Enterprise JavaBeans by Richard Monson-Haefel

http://www.ibm.com/developerworks/webservices
/
http://www.ibm.com/software/solutions/webservices/
http://www.ecml.org
e-Commerce Patterns using WebSphere Commerce Suite, Patterns for
e-business Series, SG24-6156
Patterns for e-business: User-to-Business Patterns for Topology 1 and 2 using
WebSphere Advanced Edition, SG24-5864
WebSphere Commerce Suite V5.1 Handbook, SG24-6167
WebSphere V3.5 Handbook, Using WebSphere Application Server V3.5
Standard and Advanced Editions, SG24-6161
WebSphere Commerce Suite V5.1 Customization and Transition Guide,
SG24-6174

Chapter 6. Technology options
113
Fundamentals, IBM WebSphere Commerce Suite V5.1
IBM WebSphere Commerce Suite V5.1 Programmer’s Guide

114
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
115
Chapter 7.
Application design
guidelines
The main objective of this chapter is to describe design guidelines for
WebSphere Commerce Suite applications.
The WebSphere Commerce Suite programming model describes the necessary
background for the EJB component architecture, Model-View-Controller design
pattern, error handling, session management, and access control. In addition, we
describe the application components and provide guidelines on the design of
JSPs, commands, and EJBs for WebSphere Commerce Suite applications.
The chapter is organized into the following sections:
WebSphere Commerce Suite programming model
Requirements specification
Use case model
Navigation flow
Application component design
7

116
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
7.1 WebSphere Commerce Suite programming model
There are a number of new concepts at the heart of the WebSphere Commerce
Suite V5.1 programming model, all of which shape the approach of the
application designer when designing commerce applications with WebSphere
Commerce Suite. The following sections outline these key concepts. A good
understanding of these concepts and technology options is required for the
successful design and development of a WebSphere Commerce Suite
application.
7.1.1 Enterprise JavaBeans
There is a large amount of persistent data within the WebSphere Commerce
Suite database. Enterprise JavaBeans provide a persistent object layer on top of
the database layer, which in turn provides a framework for the use of and
extension to the WebSphere Commerce Suite business model.
There are two sets of Enterprise JavaBeans in WebSphere Commerce Suite:
private and public. The private beans are used by the WebSphere Commerce
Suite runtime and tool set; the public beans can be used and extended when
modifying the business logic of the system. The WebSphere Commerce Suite
Enterprise JavaBeans consist of both session and entity beans. The session
beans perform intensive database operations usually within the scope of a given
transaction. It is the entity bean that provide an object model over the underlying
data that is persistent across multiple transactions. An example of this is the
catalog bean that provides an object model for the logical catalog entity within
the store. The Enterprise JavaBeans also provide an additional shield in front of
the database so that each reference to the commerce application data may not
necessitate a direct connection to the database. All data within the WebSphere
Commerce Suite system is derived from the underlying Enterprise JavaBeans.
Figure 7-1 on page 117 shows the layered data access model implemented in
WebSphere Commerce Suite and the interfaces between each entity and the
underlying database schema. This WebSphere Commerce Suite model more
tightly governs the manner in which customizations are carried out on the
application logic and describes the data held in the tables in terms of logical
entities within the commerce system rather than using the raw table definitions.
Once populated, the Enterprise JavaBeans reduce the need for repetition of
common database requests and thus reduce the number of transactions on the
underlying database.
Note: For more detailed information, refer to Chapter 6, “Technology options”
on page 79.

Chapter 7. Application design guidelines
117
Figure 7-1 WebSphere Commerce Suite layered data access model
7.1.2 Model-View-Controller application structure
The WebSphere Commerce Suite application architecture uses the
Model-View-Controller design pattern throughout and as such it is the
recommended approach for commerce application development using
WebSphere Commerce Suite.
The Model-View-Controller pattern separates display logic (in WebSphere
Commerce Suite, this is handled by JavaServer Pages) from the underlying
business logic and data model. The component parts of the
Model-View-Controller pattern are implemented as shown in Figure 7-2 on
page 118.
The controller component of the WebSphere Commerce Suite architecture is
implemented by the WebSphere Commerce Suite Request Servlet. This servlet
is the focal point of all requests on the WebSphere Commerce Suite system and
as such is the interface between the outside world and the system’s underlying
business logic and data model.
Database
Enterprise JavaBeans
Data Beans
Access Beans
View Commands
JSP
Controller Commands
Task Commands

118
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 7-2 Model-View-Controller implementation in WebSphere Commerce Suite V5.1
The model element of the pattern is implemented in WebSphere Commerce
Suite using two key application components: controller commands and entity
Enterprise JavaBeans.
The Enterprise JavaBeans provide a persistent object model over the underlying
database. The persistent data model in WebSphere Commerce Suite is
described in more detail in 7.1.1, “Enterprise JavaBeans” on page 116. The
controller commands provide the mechanism for performing business logic on
the persistent data model within the system. They are targeted using a URL via
the Request Servlet and they themselves are constructed according to a specific
design pattern.
Each command class consists of two components: an interface class and an
implementation class. The de-coupling of the command interface and the
command implementation allows multiple implementations of the same
command according to the store invoking the command. The business logic
contained within the command classes can be further subdivided into task
commands, each of which perform a specific unit of work within the business
function.
For each function call, the Request Servlet has to map together the correct
interface and implementation classes. This is done using the CMDREG and
URLREG tables. The URLREG table defines the command name (that is, the
name used in the URL to invoke the command) and maps this to the interface
class of the command. In turn, the CMDREG table maps the interface class
Web
controller
Controller
URL
Controller
command
View
command
WCS
Database
Entity bean
View
Model
Access
bean
Task
command
Task
command
JSP template
Data bean
invokes
invokes
R/W
invokes
invokes
invokes
invokes

Chapter 7. Application design guidelines
119
together with the correct implementation class for the given store. Both the
interface and implementation classes have defined superclasses,
ControllerCommand and ControllerCommandImpl. The task commands also
inherit from a defined pair of superclasses. This defines a standard interface
between WebSphere Commerce Suite and the underlying command business
logic. Having performed the business logic, the command then provides a view to
the user using a third table, VIEWREG. This table defines a specific JavaServer
Pages template for display for a given store and task.
Figure 7-3 on page 120 shows how the Request Servlet maps the correct
implementation class for a given command request, executes the command and
provides a view of the action to the user.
When creating custom business logic, new commands and views must be
registered in the relevant tables.
The Model-View-Controller approach segregates data and business logic, which
has benefits with regard to reusing the business logic both within the application
and across platforms and applications. Beyond the scope of an individual
commerce application, common business-specific components in the business
model can be reused independently across applications within the enterprise.
Note: In WebSphere Commerce Suite V5.1 there is no administrative
interface to perform command registration. All command registration is made
using the DB2 command-line interface or the DB2 Control Center.

120
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 7-3 Command execution process in WebSphere Commerce Suite V5.1
7.1.3 Error handling and messages
Error handling is a critical element to consider during the design phase of a new
application. Within WebSphere Commerce Suite there is a defined error handling
framework for processing runtime errors and exceptions.
The exception handling framework
The exception handling process flow implemented in WebSphere Commerce
Suite is constructed according to the same Model-View-Controller pattern
described in Figure 7-2 on page 118. A command can throw one of two
exceptions according to the nature of the underlying problem. An
URLREG
Table
CMDREG
Table
Controller
Command
implementation
class
VIEWREG
Table
JSP template
queries
return interface
name
queries
return interface
name
invokes
return view
name
queries
return JSP
name
invokes
return Web
content
RequestServlet
URL command
request
User view of
command

Chapter 7. Application design guidelines
121
ECApplicationException is thrown if the root cause of the exception condition is
related to an action performed by the user. An ECSystemException refers to an
error resulting from a problem within the system, such as null-pointer exceptions
or database rollback conditions. In this instance, the Request Servlet will retry
the command if the command is designated as retriable and was caused by a
database deadlock or rollback. When any exception is thrown, its occurrence is
logged by the system in the ecmsg_<node>_<date>.log file. By default this log
file can be found in <wcs_install_path>/instances/<instance_name>/logs
directory.
Error messages are stored independently of the application and display logic in
stand-alone properties files. This is to facilitate message maintenance and
implementation of multilingual stores. In the case of a multilingual store, the
Request Servlet determines the correct language from the specified language
identifier. The properties files define two sets of messages: user messages as
they are reported to the application user, and system messages that are
captured in the system message log.
Error reporting is implemented by having error view tasks registered in the
VIEWREG table. When an exception thrown by a command is caught by the
Request Servlet, the error view command corresponding to the task name
defined within the exception is invoked and the display logic processed to report
the error to the user. The JavaServer Pages template to display the message is
registered in VIEWREG. This template is passed with name-value pairs of
command parameters passed to the original command, together with any
additional parameters added for error handling (such as an error code). On the
template, an error databean is used to present the error details in the appropriate
format. To do this, a message helper object retrieves the required message from
the appropriate properties file using the error parameters and the message
contained in the error databean.
Customizing error handling and messages
For a customized store with heavily customized business logic, the error
reporting will require a similar level of customization. The application developer
must create three components to implement custom error messages:
A class containing message keys.
A class containing the message objects to be thrown and caught and a
reference to the message text resource bundle.
A resource bundle containing the message keys and message text for each
exception key.

122
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
The key names are stored independently of the exception objects to facilitate
maintenance of the messages and message keys independently of the exception
classes that they refer to. The resource bundle consists of key-value pairs to
map the message key to the error-specific text message.
For debugging purposes, WebSphere Commerce Suite provides a mechanism
for trace logging during execution of components running within the WebSphere
Commerce Suite server. The ECTrace class within com.ibm.commerce.ras
defines class methods for reporting entry and exit points and runtime messages
in the system trace log.
7.1.4 Application session management
Web browsers and e-commerce sites use the HTTP protocol to communicate.
Since HTTP is a stateless protocol (meaning that each command is executed
independently without any knowledge of the commands that came before it),
there must be a way to manage sessions between the Web browser client and
the application server.
WebSphere Commerce Suite supports two types of session management:
cookie-based and URL rewriting. The administrator can choose to support either
cookie-based session management only or both cookie-based and URL rewriting
session management. If WebSphere Commerce Suite site is configured to
support cookie-based only, users' browsers must be able to accept cookies. If
both cookie-based and URL rewriting are selected, WebSphere Commerce Suite
first attempts to use cookies to manage sessions; if the user's browser is set to
not accept cookies, then URL rewriting is used.
Cookie based session management
When cookie-based session management is used, a message (cookie)
containing a user's information is sent to the browser by the Web server. This
cookie is sent back to the server when the user tries to access certain pages. By
sending back the cookie, the server is able to identify the user and retrieves the
Notes:
All error message objects are instances of the ECMessage superclass.
These objects are passed to the constructors of ECApplicationException
and ECSystemExceptions when they are thrown at runtime and therefore
on to the designated error display logic.
For classes involving error handling, the com.ibm.commerce.ras package
should be imported.

Chapter 7. Application design guidelines
123
user's session from the session database, thus maintaining the user's session. A
cookie-based session ends when the user logs off or closes the browser.
Cookie-based session management is secure, has performance benefits, and is
recommended for user sessions.
For security reasons, cookie-based session management uses two types of
cookies:
A non-secure session cookie
Used to manage session data. Contains the session ID, negotiated language,
current store and the shopper’s preferred currency when the cookie is
constructed. This cookie can flow between the browser and server under
either SSL or non-SSL connection. There are two types of non-secure
session cookies:
– WebSphere Application Server session cookie is based on the servlet
HTTP session standard and can be found in any document in the
WebSphere Application Server. WebSphere Application Server cookies
persist to the memory or to the database in a multi-node deployment.
– WebSphere Commerce Suite session cookie is internal to WebSphere
Commerce Suite and is not persisted to the database.
A secure authentication cookie
Used to manage authentication data. An authentication cookie flows over
SSL and is timestamped for maximum security. Whenever a sensitive
command is executed, this cookie is used to authenticate the user (for
example, the DoPaymentCmd that asks for a user’s credit card number).
There is minimal risk that this cookie could be stolen and used by an
unauthorized user. Authentication code cookies are always generated by
Commerce Suite whenever cookie-based session management is in use.
Both the session and authcode cookies are required to view secure pages.
For cookie errors, the CookieErrorView is called under the following
circumstances:
The user has logged in from another location with the same logon ID.
The cookie became corrupted, or was tampered with or both.
If cookie acceptance is set to
true
and the user's browser does not support
cookies.

124
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
URL rewriting
With URL rewriting, all links that are returned to the browser or that get redirected
have the session ID appended to them. When the user clicks these links, the
rewritten form of the URL is sent to the server as part of the client's request. The
servlet engine recognizes the session ID in the URL and saves it for obtaining
the proper object for this user. To use URL rewriting, HTML files (files with .html
or .htm extensions) cannot be used for links. To use URL rewriting, JSPs must be
used for display purposes. A session with URL rewriting expires when the
shopper logs off.
7.1.5 Access control
WebSphere Commerce Suite uses access control policies to protect the
component parts of the application architecture. The reason for this protection is
to ensure that all legitimate requests to the WebSphere Commerce Suite
application are handled by the Request Servlet, and that the commerce
controller and view commands, EJBs and JSPs are not accessed directly by
malicious third parties. Figure 7-4 on page 125 shows the route that requests
could potentially follow to access WebSphere Commerce Suite resources.

Chapter 7. Application design guidelines
125
Figure 7-4 WebSphere Commerce Suite access control mechanisms
WebSphere Commerce Suite access control
At the application level, WebSphere Commerce Suite provides an authentication
framework over the commands and JSPs. Access groups are defined according
to role definitions. Access to commands and JSPs are in turn assigned access
groups according to the roles of those using them (customers, administrators or
additional administrative roles such as order clerk). Customer commands can be
accessed by both customers and administrators. Administrative commands can
be subcategorized into specific administrative role groups. WebSphere
Commerce Suite introduces the concept of an owning identity for each given
resource, such that the access to a command is granted to members of a given
access group against resources owned by a specific owning organization. This
then permits further subdivision of access control within the assigned
administrative roles.
Unauthorized
request
Unauthorized
request
COBRA
client
RequestServlet
JSP template
WCS
access control
¨
Request Servlet
or
Web Controller
Controller
command
Entity bean
Data bean
View
command

126
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Access to commands for given users is governed by the WebSphere Commerce
Suite Request Servlet. Fine-grain access control is implemented at class level by
the checkPermission() method implemented in each controller command. A
boolean return value of true means that access will be granted to the command
while a return value of false means that access is denied and an
ECApplicationException exception is thrown.
The access group model compares with that of the old versions of WebSphere
Commerce Suite in that administrative users are assigned to defined
administrative groups with access to a defined set of commands. The
WebSphere Commerce Suite model introduces the concept of an organization
for the users within their access groups. It is now possible for administrators to be
allowed to administer all stores belonging to a given organization. The
introduction of the organization concept, together with the access groups in
WebSphere Commerce Suite, allows the stores to be grouped under their owning
organization rather than on either one store or all stores.
Firewall protection
When a WebSphere Commerce Server runs behind the firewall, Internet clients
are not able to directly access the entity beans. Using this approach, protection
for JSP templates is provided by the data bean that is included in the page. The
data bean is activated by the data bean manager. The data bean manager
detects if the JSP template was forwarded by a view command. If it was not
forwarded by a view command, an exception is thrown and the request for the
JSP template is rejected.
7.2 Requirements specification
The main objective of this section is to give an idea of the functionality included in
the WebSphere Commerce Suite sample stores. The most recent sample store
is called WebFashion. This sample store in a successor to InFashion. As
explained in Chapter 5, “e-business life cycle” on page 59, each WebSphere
Commerce Suite implementation must accommodate individual client
requirements. We recommend that you analyze the requirements documented
for the WebFashion sample store. Understanding WebFashion will allow you to
make better decision based on the features that have already been implemented
in WebFashion.
The initial requirements for the WebFashion store model are documented in the
following use cases:
Home page use case
Registration use case
Logon use case

Chapter 7. Application design guidelines
127
Manage personal account use case
Change personal information use case
View product category use case
Display product page use case
Display package page use case
Display bundle page use case
Display shopping cart use case
Checkout shop cart use case
Quick checkout use case
Edit an address use case
Add new address use case
View orders use case
Add item to the wish list use case
View wish list use case
Create quick checkout profile use case
These use cases are described in detail in the IBM WebSphere Commerce Suite
WebFashion: Installation, Configuration, and User Documentation contained in
the WebFashion.zip download found at:
http://www.ibm.com/software/webservers/commerce/wcs_pro/downloads.html/
WebSphere Commerce Suite design and development is component based. This
type of approach opens the possibility for reusing the components that have
already been developed, such as components included in WebSphere
Commerce Suite V5.1 or WebFashion.
7.3 Use case model
The main objective of this section is to give an example of use case modeling
and provide a starting point for the practical application design and application
development guidelines elaborated in following sections. New use cases have
been created to address the B2C guideline examples elaborated in this book.
Table 7-1 shows a list of these use cases, which are used for demonstration
purposes and use case modeling.

128
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Table 7-1 List of use cases
Figure 7-5 shows the relevant store and directory components and the relevant
use-cases involved in the integration.
Figure 7-5 Component use case model
Note: Please refer to Appendix A, “Use cases” on page 531 for a complete list
of use cases for this book.
Use case ID Use case name Use case description
UC#1 Log on with LDAP User requests a login into the
store specifying user ID and
password (see Table 7-2 on
page 129).
UC#2 User login authentication User’s credentials are verified in
directory and JNDI object and
user profile is sent to WebSphere
Commerce Suite (see A.1, “UC#2
logon with LDAP” on page 532).
UC#3 User profile update User data are inserted/updated
into WebSphere Commerce Suite
database (see A.3, “UC#3 user
profile update” on page 533).
Front-End
(WCS 5.1)
Client
User Services
WCS Store
UC#2
UC#1
Database
UC#3
LDAP

Chapter 7. Application design guidelines
129
Use case number 1 (UC#1) is described in Table 7-2.
Table 7-2 Sequence diagram for UC#1 - User Login
ID UC#1
Name User login with LDAP
Description User is required to log in to the store by entering a user ID and
password. The authentication will be done by the LDAP directory.
Primary Actor(s) A user from Web browser or from a mobile device.
Secondary
Actor(s)
WebSphere Commerce Suite login command with LDAP
AuthenticationCmd task.
Input(s) A user ID and password is provided by the user.
Output(s) An OK or error page is returned to the user’s browser.
Preconditions SecuryWay Directory (SWD) is running.
Success End
Condition
The specified user ID and password have been successfully
validated by a directory. The user profile has been successfully
retrieved from directory and successfully replicated to the
WebSphere Commerce Suite database. The user has been
successfully logged into the WebSphere Commerce Suite
application.
Failure End
Condition
User login failed, due to any of the following conditions:∙
UserID and/or Password are not valid
An error/exception condition occurred in the directory

WebSphere Commerce Suite error/exception con
dition
occurred
Steps
See also
Figure 7-6 on
page 130.
1. User submits user ID and password to log in to the store via the
store login page.
2. The WebSphere Commerce Suite store command will call the
LDAP AuthenticationCmd task command (see Appendix A.1,
“UC#2 logon with LDAP” on page 532).
3. If user’s authentication fails, a login error page is returned to the
user.
4. The user profile information is retrieved from the directory.
5. The use profile information is replicated to the WebSphere
Commerce Suite database (see Appendix A.3, “UC#3 user profile
update” on page 533).
6. A login OK page is returned to the user or a mobile device. The
user is now authenticated (logged in).

130
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Login functionality is a good example of how to apply UML for the requirements
specification. As displayed in Figure 7-6, three use cases have been created to
document each interaction between the application components involved in the
user’s login process. For every use case there is a sequence diagram created
similar to the diagram in Figure 7-6.
Figure 7-6 UC#1 - User login with LDAP- Sequence diagram
Front-End
(WCS 5.1)
WCS Shop
Database
(DB2 7.1)
Directory
(SWD 3.1.1.2)
User Services
Go shopping as authenticated user
Send Page
LDAP AuthenticationCmd
Authentication failed
LoginCmd (Userid,Passwd)
Update User Profile
LogonCmd
Login OK:Send Login OK Page
Go to bookmarked Login Page
Send Login Page
User Profile
UC#1
UC#2
UC#3
User
1
2
3
4
5
6
Send Error page

Chapter 7. Application design guidelines
131
7.4 Navigation flow
The navigation flow for the Web Fashion store shown in Figure 7-7 is typical of B2C stores.
Figure 7-7 Navigation flow
Log
in
Alternatives
View
wish
list
Help page
Help page
Product
page
Help page
Category
pages
Contact
us
Private
policy
Registr.
or login
page
Registrati
on page
Order
confirmat
ion
Shopping
cart
Choose
billing
address
Choose
shipping
address
Choose
shipping
method
Order
summary
New
billing
address
Select
product
New
billing
addres
s
New
shipping
address
New
shipping
address
Checkout
Next
Next
Next
Quick
Checkout
Order
summary
Home
page
Order
Now
Order
Now
Main
account
Forgot
pasword
Password
reset
Login
Register
Forgot
your
password
Wish list
Add
to
wish
list
Wish list
sent
Choose
a
language
Update
totals
Change
personal
info
Order
status
Address
book
Edit
address
Address
book
Add new
address
View
orders
Change
personal
information
Edit my
address
book
Quick
checkout
profile
Create or
update
profile
Package
page
Bundle
page
Add a
new
address
Edit
Delete
Add to
shopping
cart
These pages can be
accessed from any page
in the site
Send wish list

132
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
7.5 Application component design
This section elaborates on the design features of WebSphere Commerce Suite
application components. Figure 7-8 provides an overview of the logical view
between commands and the WebSphere Commerce Suite database. This flow
shows involved components that will be discussed in the following sections in
more detail.
Figure 7-8 Command flow
Web controller
Controller
command
View
command
Task
command
Access bean
Entity bean
WCS
Database
JSP page
Access bean
Data bean
invokes
invokes
invokes
R/Wdata
extends
Entity bean
invoke
s
invokes
R/Wdata
invokes
invokes
return
view
name

Chapter 7. Application design guidelines
133
7.5.1 JSP design
JSPs provide a simple yet powerful mechanism for inserting dynamic content into
Web pages. The JSP specification achieves this by defining a number of
HTML-like tags that allow developers to insert server-side Java logic directly into
HTML or XML pages that are sent to HTTP Web browser clients.
It is important to note that JSP technology is an extension of the Java Servlet
API. In fact, application servers compile JSPs into HttpServlets before executing
them. Essentially, the JSPs represent the service() method of the automatically
generated HttpServlet. Hence JSPs automatically get access to certain implicit
objects without having to declare them. Table 7-3 lists some of the key implicit
objects.
Table 7-3 JSP implicit objects
WebSphere Commerce Suite product documentation use the term “JSP
template”, which is the same as a JSP. However, using the term “JSP template”
emphasizes the fact that the JSP is used to generated dynamic pages rather that
static pages.
When designing the JSP, it is important to understand where the particular JSP is
used in the concept of the overall site flow. The fine-grain diagram, seen in
Figure 7-9 on page 134, is usually necessary for understanding all design
aspects of JSPs and for creating a comprehensive design document for
developers. This activity diagram covers the login and registration functionality.
Object
Name
Object Type Description
request javax.servlet.HttpServletRequest Represents the HTTP request
received from the client.
response javax.servlet.HttpServletResponse Represents the HTTP response to
be sent to the client.
session avax.servlet.HttpSession Represents the session object
created for the requesting client (if
any).
out javax.servlet.jsp.JspWriter Represents the output stream to be
sent to the client as part of the
response.

134
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 7-9 The activity diagram for login functionality
The designer should specify the following information for every JSP page that is
going to be developed or reused:
A title. A JSP is used to generated the response to the client in HTML format
and where the title is HTML tag. For example, login for the WebFashion login
page.
JSP file name and the relative path. For example:
<jsp_root_path>/webfashion/myaccoung.jsp
The view command name registered in VIEWREG table associated with this
JSP if it exists. The database update information to insert or update the view
command registration should be specified as well. One of the parameters is
the SSL support flag.
Input parameters. This is a set of parameters needed to support the
presentation logic of JSP.
Home page
LogonForm.jsp
Register
myaccount.jsp
account.jsp
Login
Forget
password
forgetpassword.
jsp
Resetpassword
Form.jsp
Send pswd
Continue
Does not display to the customer.
[user is not logged in] [user is logged in]
LogonForm.jsp
Register
RegisterForm.jsp

Chapter 7. Application design guidelines
135
The list of commands called from this JSP. In the case of myaccount.jsp it is
the logon command.
Session information. In WebSphere Commerce Suite the session
management is handled by WebSphere Commerce Suite or WebSphere
Application Server and usually there is no need to consider sessions during
JSP design and development.
The list of data beans used in this JSP (for example, ErrorDataBean). The list
of available data bean can be found in IBM WebSphere Commerce Suite V5.1
online documentation.
Implementation details including files, properties files, design of the core
presentation logic, the presentation layout, and error handling.
The specification for multi-language support. The WebFashion sample uses
the getResource.jsp to implement support for multi-language solutions. This
JSP is included by all JSPs that are displayed to the users.
Security consideration and access controls
JSP are compiled and executed on the server side to help avoid many traditional
security concerns. However, there are still some considerations when creating
secure pages:
1.SSL is needed for any page where the user needs to type in the password or
financial information, such as credit card numbers.
2.The sessionID should be never sent out to the client in the pure HTML form. If
somebody else gets the sessionID, it might lead to misuse of that sessionID.
When the controller commands completes, it returns a view and a JSP in
invoked. There is no further access control check to verify that a user should be
allowed to view the JSP when it is launched as a result of the return value of a
controller command.
A JSP can also be invoked directly, without a corresponding controller command.
If a JSP that is invoked directly is to be invoked under access control, it must be
registered in the VIEWREG table.
7.5.2 Controller command design
When creating new business logic for your e-commerce application, it is
expected that you may need to create or modify controller commands.
New controller commands must implement their corresponding interface. To
simplify command writing, Commerce Suite includes an abstract implementation
class for each type of command. A new controller command should be extended
from these classes.

136
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Table 7-4 provides information about which implementation class a new
controller command should extend from, and which interface it should implement.
Table 7-4 New controller command template
The designer should specify the following information for the controller
command:
1.Packaging of new code.
It is important to specify a particular code organization structure. In general,
customized code is maintained in packages and projects that are separate
from those included with Commerce Suite.
The following are example package names:
com.bigbusiness.storeA.commands
com.bigbusiness.storeB.commands
com.bigbusiness.commands
For example, the logon command’s package name is
com.ibm.commerce.security.commands.
2.The database registration specification.
This is how the command will be registered in CMDREG and URLREG table.
For example the registration for the Logon command looks as follows:
URLREG.URL = Logon
URLREG.INTERFACENAME= com.ibm.commerce.security.commands.Logon.
URLVIEW.HTTPS=1
CMDREG is the command registration table. This table provides a
mechanism for mapping the command interface to its implementation class.
Multiple implementations of an interface allow for command customization on
a per-store basis.
The URLREG table maps URIs (Universal Resource Indicator) to controller
command interfaces. URIs provide a simple and extensible mechanism for
resource identification.
Command
type
Example command
name
Extended from Implements
example
interface
Controller
command
MyControllerCmdImpl com.ibm.commerce.co
mmand.ControllerCom
mandImpl
MyControllerCmd

Chapter 7. Application design guidelines
137
3.Command context.
The command context is accessed by calling the getCommandContext()
method of the command’s superclass. The command context is set to the
controller command when the command is invoked by the Web controller. A
controller command should propagate the command context to any task or
controller commands that is invoked during processing. A command can get
such information as user ID, user object, store ID and language ID.
4.The parameters.
The list of parameters that must be passed to the command. These
parameters can be treated as the command context.
5.Implementation details for the command’s methods.
As mentioned in Table 7-4, a new controller command should extend from the
abstract controller command class
(com.ibm.commerce.command.ControllerCommandImpl). When designing a
new controller command, the following methods should be defined.
– isGeneric()
– isRetriable()
– setRequestProperties(com.ibm.commerce.datatype.TypedProperty
reqParms)
– checkParameters()
– getResourceOwners()
– checkPermission()
– performExecute()
6.The view command that is called at the end of the controller command’s
transaction.
The Web controller determines the view command to be used for the view by
looking up the view name in the VIEWREG table.
There are three type of view commands:
– Forward view command
– Redirect view command
– Direct view command
7.The list of the access beans used by the controller command.
The list of all access beans is available in IBM WebSphere Commerce Suite
V5.1 online documentation.
For performance reason the developer should avoid using a direct connection
to a database and rather use the access beans.

138
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
8.Error handling. Refer to 7.1.3, “Error handling and messages” on page 120 for
more information.
Customization of existing commands
If the already existing command is going to be customized there are several
ways to do it, including the following controller command customization
techniques:
– Replacing one or more task commands. This allows you to modify how a
particular step in the business process is performed.
– Inserting logic at the beginning of a controller command by overriding the
checkParameters() method. In the new method, super.CheckParameters()
is invoked and then the new logic is added.
– Extending the controller command by overriding the performExecute()
method. In the new method, first super.performExecute() must be invoked,
then the new business logic can be added or the view name can be
changed.
More information on the design and development of the controller command can
be found in the IBM WebSphere Commerce Suite V5.1 Programmer’s Guide.
Security consideration and access control
The controller commands are compiled and executed on the server, which can
be considered a protected area. For every command registered in the URLREG
table can the SSL flag can be set to 1. This means that the request for the
command must be already protected; if it is not, the command will not be
executed.
All controller commands must be registered in the URLREG table.
7.5.3 Task command design
A task command implements a specific unit of application logic. In general, a
controller command and a set of task commands together implement the
application logic for a URL request. A task command is executed in the same
container as the controller command.

Chapter 7. Application design guidelines
139
Table 7-5 provides information about which implementation class a new task
command should extend from, and which interface it should implement.
Table 7-5 New task command template
The architect should provide the developers with additional information for the
Controller command specification from which the task command is called,
including:
1.Packaging of new code.
The same rules apply to the packaging of the task command as for the
controller command.
2.Input and output properties.
These properties must be defined in the task command interface, rather than
the task command implementation class. This enables multiple
implementations of the task command (one for each store) without the caller
being concerned about which implementation class to call.
3.Implementation details for command’s methods.
All the methods defined in the interface must be implemented in the
implementation class. Since the command context should be set by the caller
(a controller command), the task command does not need to set the
command context. The task command can, however, obtain information from
the Web controller by using the command context.
The task command should override the following methods from
com.ibm.commerce.command.TaskCommadImpl class:
– checkParameters()
– performExecute()
The description of the command logic performed by the task command can
be supported by the sequence diagram or class diagram. The graphical
explanation can be a great help to developers.
4.The parameters.
The list of parameters that must be passed to the command. These
parameters should be defined in the task command interface.
Command
type
Example command
name
Extended from Implements
example
interface
Task command MyTaskCmdIml com.ibm.commerce.co
mmand.TaskComman
dImpl
MyTaskCmd

140
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
5.The database registration specification.
The designer should specify how the command will be registered in the
CMDREG table.
6.Error handling. Refer to 7.1.3, “Error handling and messages” on page 120 for
more information.
Security consideration and access control
The task commands are compiled and executed on the server and invoked only
by controller commands.
Task commands do not use access controls. The access control for task
commands is implemented by setting the access control by the calling controller
command.
Customization of existing commands
There are several ways that a task command can be modified. The following list
provides an overview of task command customization techniques:
Write a new task command to replace the one you want to customize. In this
new command, the same interface should be implemented as the one that is
going to be replaced. Then, the CMDREG table should be updated with the
new command implementation class.
The logic can be inserted at the beginning of a task command by overriding
the checkParameters() method. In the new method,
super.CheckParameters() is invoked and then the new logic is added.
Extension of the task command by overriding the performExecute() method.
In the new method, super.performExecute() is invoked and then the new logic
is added.
7.5.4 Data bean design
A data bean normally extends an access bean. The access bean, which can be
generated by VisualAge for Java, provides a simple way to access information
from an entity bean. When modifications are made to an entity bean (for
example, adding a new field, a new business method or a new finder), the update
is reflected in the access bean as soon as the access bean is regenerated. Since
the data bean extends the access bean, it automatically inherits the new
attributes. As a result of this relationship, no coding is required to enable the data
bean to use new attributes from the entity bean.
Note: Task commands are not registered in the URLVIEW table.

Chapter 7. Application design guidelines
141
However, if a new entity bean was created, a new data bean must be developed
as well. Table 7-6 provides information about which implementation class a new
DataBean should extend from, and which interface it should implement.
Table 7-6 A new databean template
The architect should specify the following information for the data bean which is
going to be developed:
1.Packaging information.
The names of the implementation and interface classes that are going to be
created or modified.
2.The specification of the access bean which is going to be extended.
7.5.5 Entity bean design
The persistence layer within the Commerce Suite architecture is implemented
according to the EJB component architecture. The EJB architecture defines two
types of enterprise beans: entity beans and session beans. Entity beans are
further divided into Container-Managed Persistence (CMP) beans and
Bean-Managed Persistence (BMP) beans. Further information on EJBs is found
in 6.2.4, “Enterprise JavaBeans (EJBs)” on page 94.
Commerce Suite provides two sets of enterprise beans: private and public.
Private enterprise beans are used by the Commerce Suite runtime environment
and tools. These beans cannot be used or modified. Public enterprise beans, on
the other hand, are used by commerce applications, and can be both used and
extended. These public enterprise beans are organized into the following EJB
groups:
WCSCatalog
WCSCommon
WCCSFulfillment
WCSOrder
WCSOrderStatus
WCSPayment
Command
type
Example command
name
Extended from Implements
example
interface
DataBean MyDataBeanCmdImpl com.ibm.commerce.co
mmand.DataBeanCo
mmandImpl
MyDataBean

142
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
WCSPVCDevices
WCSTaxation
WCSUserTraffic
WCSUser
Some of the EJB groups listed above contain session beans. A small number or
stateless session beans are used to handle intensive database operations, such
as performing a sum of all the rows in a particular column. In order to simplify
migration in the future, a session bean class should not be modified. If required,
a new session bean can be created in a new EJB group. For more information on
creating new session beans, refer to IBM WebSphere Commerce Suite V5.1
Programmer’s Guide.
The designer has basically the following three options for extending the
WebSphere Commerce Suite object model:
Extend the Commerce Suite’s public enterprise beans
Write a new entity bean
Write a new stateless session bean
The chosen approach to design and development is based on the application
requirements versus the framework provided by WebSphere Commerce Suite.
Object model extension methodologies
As was mentioned, the application requirements may lead to extension of the
existing WebSphere Commerce Suite object model. One example of such a
requirement is adding additional attributes to your application. This can be
accomplished by one of the following ways:
1.Without modifying an existing WebSphere Commerce Suite public entity
bean.
First a new database table is created, then a new entity bean for that table is
created. The new fields and methods are added to the new entity bean to
enable manipulation with the new attributes. Finally the deployable code and
an access bean for the new entity bean is generated.
For example, consider an application that requires extending user
demographic information by additional attributes. The attribute may contain
such information as the type of home the user owns, and is stored in
USERRES table as shown in Figure 7-10. This type of information is related
to the existing WebSphere Commerce Suite USERDEMO. The demographic
enterprise bean is already developed for this table and it is a part of WCSUser
EJB group.

Chapter 7. Application design guidelines
143
Figure 7-10 Extended demographics object model
A new entity bean interacting with the USERRES table is created to
accommodate requirements. When the application requires the user’s
residence type, the Userres access bean object is instantiated and data is
retrieved. If the application requires other demographic information at the
same time, the Demographics access bean object must be instantiated as
well. Figure 7-11 displays this approach to extending the object model.
Figure 7-11 Extending of the object model by adding a new entity bean
2.By modifying an existing WebSphere Commerce Suite public entity bean.
First a new database table is created. Then a table join is created as seen in
Figure 7-12. This table join is between the new table and the existing table
that corresponds to the existing enterprise bean that is going to be modified.
New fields and methods are added to the existing entity bean to enable
manipulation with the new attributes. The files are mapped to the
corresponding columns in the new table, using a secondary table map. Finally
the deployable code and an access bean for the updated entity bean is
generated.
Member
Demographics
0..1
Userres
0..1
USERDEMO
Table
USERRES
Table
Demographic
entity bean
Userres
entity bean

144
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 7-12 Extended demographics object model
If the new USERRES table is used, and the demographic entity bean is
modified, only one access bean object is instantiated. Figure 7-13 on
page 145 displays this approach to extending the object model.
This approach has better runtime performance because only one entity bean
object is instantiated and a single fetch is used to retrieve all the required
attributes.
The disadvantage is that the existing WebSphere Commerce Suite code was
modified. Migration issues might arise when a new WebSphere Commerce
Suite code repository is released. The IBM WebSphere Commerce Suite
V5.1 Programmer’s Guide gives an explanation of migration procedures.
Member
Demographics
0..1
Userres
0..1

Chapter 7. Application design guidelines
145
Figure 7-13 Extending of the object model by modifying the existing entity bean
Design considerations for entity beans
The architect should focus on the following information for the extension of a
public data bean:
1.Packaging information.
The names of the implementation and the interface classes that are going to
be created or modified.
2.The database update specification.
The specification should cover:
– Table name
– Column name
– Column data type
The following data type can be used:
• BIGINT
• INTEGER
• TIMESTAMP
• CHAR
• VARCHAR
• LONG VARCHAR
• CLOB
• BLOB
• DECIMAL (20,5)
– Index specification.
3.Details of the fields and methods implementation.
USERDEMO
Table
USERRES
Table
Demographic
entity bean
foreign key

146
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
147
Chapter 8.
Application development
guidelines
This chapter explains the development guidelines and best practices for
WebSphere Commerce Suite V5.1 application development. The guidelines refer
to the use of WebSphere Commerce Studio products and external tools, but
many of the principles can be applied to any Web application development
environment.
The main topics discussed are as follows:
Development tools
This section describes the tools provided within WebSphere Commerce
Studio and third-party tools for WebSphere Commerce Suite V5.1 store
development.
Development environment
In a team with various people and skills working on the same project, sharing
resources and assets is a requirement. A strategy is needed to set up a
development environment and develop a process for development. We
examine different development strategies and analyze the pros and cons.
Commerce application development
8

148
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
This section describes the approach to WebSphere Commerce Suite V5.1
customization. We provide guidelines on how to create new customizations,
and leverage existing samples as a base for your customization needs.

Chapter 8. Application development guidelines
149
8.1 Development tools
To help developers customize and develop new functionality and new stores IBM
has provided WebSphere Commerce Studio. Commerce Studio ships in two
packages, Developer Edition and Professional Developer Edition. The basic
difference between the two packages is that the Professional Developer Edition
has all the features of the Developer Edition, as well as the ability to develop
business logic using Enterprise JavaBeans.
The recommended development environment package, which we used while
creating this redbook, is the WebSphere Commerce Studio V5.1, Professional
Developer Edition for Windows NT and Windows 2000. Commerce Suite
business logic makes extensive use of EJBs. In order to make custom changes
for the business logic, we need tools that will let us develop and test EJBs. The
best tool for this task is IBM VisualAge for Java V3.5, Enterprise Edition. This
version of VisualAge for Java is included in the WebSphere Commerce Studio
V5.1, Professional Developer Edition for Windows NT and Windows 2000.
VisualAge for Java also includes the integrated WebSphere Test Environment
(WTE), which allows developers to run Commerce Suite function code within
VisualAge for Java without exiting the application for debugging purposes.
When developing a store for WebSphere Commerce Suite V5.1, it is important to
understand the level of customization needed and the development tools
provided with WebSphere Commerce Studio V5.1, Professional Developer
Edition for Windows NT and Windows 2000.
This section provides a description of the following development tools:
Development tools for customization needs
WebSphere Commerce Studio
– WebSphere Studio V3.5, Advanced Edition
– WebSphere Commerce Studio V5.1 extensions
– VisualAge for Java V3.5, Enterprise Edition
Other development tools
– XML editor
– Store Services
– IBM PerfectPhoto
– Rational Rose
– Rational ClearCase

150
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
8.1.1 Development tools for customization needs
As described in the WebSphere Commerce Suite V5.1 Handbook, SG24-6167,
there are different levels of skills needed for the customization of a store.
Different tools are required to implement different types and levels of
customization.
We have classified the development tools into the following categories:
Basic customization tools
Intermediate customization tools
Advanced customization tools
Basic customization tools
Basic customization often requires creating or modifying existing JSPs.
WebSphere Studio plus the Commerce extensions are used for JSP
development.
In WebSphere Commerce Suite V5.1, you will need an XML editor to modify and
create your store catalog data files for such tasks as adding products or product
groups. The IBM XML Tool beta is included on the WebSphere Commerce Studio
CD. Other XML editors may be used as well, such as XML Spy. As an alternative
to managing your catalog data via XML files, IBM sells a separate product called
WebSphere Catalog Manager that provides a GUI front-end for managing your
catalog. Information on WebSphere Catalog Manager can be found at:
http://www.ibm.com/software/webservers/commerce/catalogmanager/
Tools such as Store Services can be used to modify basic informational settings
for your running store. Depending on your graphic customization needs, IBM
Perfect Photo can be used for creating or modifying images.
Intermediate customization tools
Intermediate customization tools includes the basic customization tools. In
addition, IBM VisualAge for Java V3.5, Enterprise Edition is used to create
custom WebSphere Commerce Suite commands. The use of the WebSphere
Test Environment to debug your WebSphere Commerce Suite commands written
in Java is also very useful.
Advanced customization tools
Advanced customization includes the intermediate customization tools. In
addition, IBM VisualAge for Java V3.5, Enterprise Edition is used to create
custom EJBs.

Chapter 8. Application development guidelines
151
8.1.2 WebSphere Commerce Studio
WebSphere Commerce Studio V5.1, Professional Developer Edition for Windows
NT and Windows 2000 contains the majority of the tools required to develop
stores for WebSphere Commerce Suite V5.1, Pro Edition, including WebSphere
Studio V3.5.2, WebSphere Commerce Studio extensions V5.1, and VisualAge
for Java V3.5, Enterprise Edition. This development suite is available for the
Windows NT and Windows 2000 platforms. Stores developed with this
development suite can be deployed to any WebSphere Commerce Suite V5.1
platform (for example Windows NT, Windows 2000, AIX, and Solaris).
WebSphere Studio V3.5, Advanced Edition
This tool provides visual layout of dynamic Web pages. Studio supports JSPs,
HTML, JavaScript and DHTML. It uses wizards for generating database-driven
pages, and updates and corrects links automatically when content changes.
WebSphere Studio allows developers to integrate their favorite content creation
tools, and provides local and remote JSP debuggers.
Some common uses of WebSphere Studio include the following:
Used to create and modify JSPs and static HTML.
Used as a repository for all Web assets, including JSPs, HTML, images, Java
classes developed in VisualAge for Java.
Used during development to publish Web assets to WebSphere Commerce
Suite V5.1 runtime environment.
For information on how to use and program in WebSphere Studio, refer to the
following redbooks:
Version 3.5 Self Study Guide: VisualAge for Java and WebSphere Studio,
SG24-6136
Servlet and JSP Programming with IBM WebSphere Studio and VisualAge for
Java, SG24-5755
WebSphere Commerce Studio V5.1 extensions
The WebSphere Commerce Suite Studio extension tools allow you to quickly and
easily edit Web assets. For instance when editing Web assets using WebSphere
Studio Page Designer, the assets can be either exported back to the original
store archive, published to a running store, or both.
Note: We will refer to WebSphere Commerce Studio as Commerce Studio
throughout the redbook.

152
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
WebSphere Commerce Studio adds the following extensions to WebSphere
Studio:
Store archive tools
– Store archive template
This allows you to create a Studio project based on a store archive
template. When you create a store archive project, you can import certain
file assets from a store archive into WebSphere Commerce Studio.
– Import store archive
This allows you to import certain file assets from a store archive into a
Studio project based on a store archive.
– Export store archive
This allows you to export file assets from WebSphere Studio to a store
archive on the WebSphere Commerce Server.
– Store archive publish preferences
Use the store archive publish preferences to select your preferences when
you publish the file assets from WebSphere Studio to a running store.
Blaze Advisor
The Blaze Advisor is the development component for creating personalization
rules (cross-sells, up-sell, etc.) for the Blaze Advisor Rules Server to
implement personalization for your store.
VisualAge for Java V3.5, Enterprise Edition
IBM VisualAge for Java V3.5, Enterprise Edition is used to develop and
customize WebSphere Commerce Suite commands (Java classes) and EJBs.
For information on how to use and program in VisualAge for Java, refer to the
following redbooks:
Version 3.5 Self Study Guide: VisualAge for Java and WebSphere Studio,
SG24-6136
Programming with VisualAge for Java V3.5, SG24-5264
Servlet and JSP Programming with IBM WebSphere Studio and VisualAge for
Java, SG24-5755
Note: We recommend that the store archive publish preference is set to
always update the store archive.

Chapter 8. Application development guidelines
153
8.1.3 Other development tools
This section describes development tools used for developing a store that are not
installed as part of the WebSphere Commerce Studio, but in some cases
included with WebSphere Commerce Studio V5.1, Professional Developer
Edition for Windows NT and Windows 2000, and in other cases third-party tools.
XML editor
WebSphere Commerce Suite V5.1 makes use of XML in many places within the
store, catalog data population, and WebSphere Commerce Suite configuration.
An XML editor is an essential part of developing a store. While writing this
redbook, we used the IBM XML Tools and XML Spy to edit and create XML files.
IBM XML Tools
The IBM XML Tools package is an early technology release for providing XML
tooling. It is not intended for production use. The IBM XML Tools will be
enhanced via a series of ongoing updates. This tool can be found in the
xmltools directory of the WebSphere Commerce Studio V5.1, Professional
Developer Edition for Windows NT and Windows 2000 CD.
XML Spy
This is an integrated development environment (IDE) for markup language
that has all the major aspects of XML, including XML editing and validation,
schema/DTD editing and validation, and XSL editing and transformation. A
30-day trial version of XML Spy with instructions to register for the product for
a fee, can be found at:
http://download.cnet.com/
Store Services
After developing the store in Commerce Studio, it is desirable to export your store
as a SAR file that can be deployed several ways. Store Services is a tool that can
be used to publish (deploy) your store to the WebSphere Commerce Suite
runtime environment. In addition, settings such as the store profile, shipping, and
tax information can be changed using Store Services.
For more detailed information on Store Services, refer to the online help and
Store Developer: Creating a Store Using the Store Services, IBM WebSphere
Commerce Suite V5.1, product guide found on the WebSphere Commerce Suite
V5.1 CD.

154
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
IBM PerfectPhoto
IBM PerfectPhoto is a complete digital image software package that allows you
to manage, create, enhance, touch up, and print images of any kind (images
taken with a digital camera, scanned images, bitmap images, or others), in one
super-simple and easy-to-use application.
This tool can be used for product display and group display images as well as
any other images for your store. IBM PerfectPhoto CD is included in the
WebSphere Commerce Studio V5.1, Professional Developer Edition for Windows
NT and Windows 2000 package.
More detailed information on IBM PerfectPhoto can be found at:
http://www.ibm.com/jp/esbu/E/perfectphoto/index.html/
IBM HotMedia
HotMedia is a Java applet technology for placing rich interactive media on Web
pages quickly and easily. It supports the industry's widest array of media types
including 3D, panoramas, multi-track animations, and streaming audio and
video. HotMedia includes a toolkit that consists of a simple assembly tool and a
set of supporting utilities for authoring HotMedia files. It provides Java applet
players that deliver HotMedia objects to any Web browser without the need for
plug-ins or special servers, and using today's network bandwidths. Content
creators can easily author HotMedia files and seamlessly add a multitude of rich,
interactive media effects to any Web page.
This tool can be used to enhance the content display pages of your store. IBM
Media is installed by default by the WebSphere Commerce Suite V5.1, Pro
Edition for Windows NT and Windows 2000 install.
More detailed information on IBM HotMedia can be found at:
http://www.ibm.com/software/net.media/
Store archive
The store archive or SAR is a compressed file that contains all the assets to
create a store. The outputs of the development of a store are packaged into a
SAR file. This is not a tool in itself but a packaged unit that is used to publish your
store.
For more detailed information on the store archive refer to:
WebSphere Commerce Suite V5.1 Handbook, SG24-6167
Store Developer: Building a Store Archive, IBM WebSphere Commerce Suite
V5.1 product guide found on the WebSphere Commerce Suite V5.1 CD.

Chapter 8. Application development guidelines
155
Rational Rose
Visual modeling captures business processes by defining the software system
requirements from the user’s perspective.
Rational Rose is a visual modeling tool to design and visualize object-oriented
and component-based application. The Rational Rose provides visualization,
modeling, and tools for developing Web applications.
Visual modeling has one communication standard: the Unified Modeling
Language (UML). The UML provides a smooth transition between the business
domain and the computer domain. Using the UML, all members of a design team
can work with a common vocabulary, minimizing miscommunication and
increasing efficiency.
Rational Rose’s model-diagram architecture facilitates use of the Unified
Modeling Language (UML), Component Object Modeling (COM). Using semantic
information ensures correctness by construction and maintaining consistency.
A trial version of Rational Rose can be downloaded from:
http://www.rational.com/tryit/
More detailed information on Rational Rose can be found at:
http://www.rational.com/
Rational Rose and VisualAge integration
Seamless integration between the Rational Rose modeling tooling and
VisualAge for Java finally became a reality with the release of Rational Rose
2000e ("e" for e-development). This means that you can generate Java code
from partial or complete Rose models into a VisualAge for Java repository, a
process known as forward engineering. Conversely, you can go from Java code
in a VisualAge for Java project to a Rose model via reverse engineering.
No longer must you use the XMI Toolkit to perform such tasks, or go through the
process of exporting and importing code between the two products. The XMI
Toolkit does, however, provide a very powerful forward engineering feature that
supports rapid application development of VisualAge for Java EJB components
from Rose models.
More detailed information on Rational Rose and VisualAge integration can be
found at:
http://www.ibm.com/vadd/

156
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Rational ClearCase
As software application development continues to become increasingly complex
due to diverse platforms and distributed environments, the need increases for
controlling software, version, and configuration. All these task are accomplished
by Software configuration management (SCM).
Software configuration management tools are the glue that holds together the
various components and phases of the application life cycle. SCM tools organize
and control the process and artifacts of application development and
deployment.
Rational ClearCase is an SCM tool supporting version control, workspace
management, build and release management, and process configurability.
Rational ClearCase supports parallel development through automatic, unlimited
branching and a merge manager that effectively eliminates the typical problems
found in parallel development, such as lost code and recurring bugs.
ClearCase uses a common VOB (Versioned Object Base) where all development
artifacts are stored. ClearCase's most basic mechanism for team development is
to have different users on a project use different views on the VOB. These are
work areas that transparently provide dynamic, private access to the
development directory structure and files. A user views this VOB through specific
views he can set up. The views have rules that determine which particular
version of the files a user will see.
More detailed information on Rational ClearCase can be found at:
http://www.rational.com/
8.2 Development environment
The development environment includes the development tools described in the
previous section, the WebSphere Commerce Suite V5.1 runtime, team servers,
build and test systems.
This section is organized into the following topics:
Team development strategies
Development environment installation
Team development environment with VisualAge for Java
Team development with WebSphere Commerce Studio
Publishing targets
Packaging a SAR
Source Control Management and build guidelines
Unit testing guidelines

Chapter 8. Application development guidelines
157
8.2.1 Team development strategies
Any project that involves two or more developers working on the same code
needs a versioning scheme, often addressed by a tool, in order to keep the code
coordinated among the programmers. Some types of control mechanisms are
needed so that the developers do not change the same section of code
simultaneously, and so that consistency and correctness in the code is
preserved.
There are many variations of the following two development strategies that we
will describe:
A full commerce development environment, where every development
workstation has WebSphere Commerce Suite installed with its own
WebSphere Commerce Suite instance in addition to the development tools.
A light commerce development environment, where the development
workstation does not have WebSphere Commerce Suite installed, but only
VisualAge for Java and WebSphere Studio and uses a WebSphere
Commerce Suite instance on a remote server.
Full commerce development environment
Figure 8-1 on page 158 shows a development environment where every
development workstation has its own WebSphere Commerce Suite instance. The
main features of this configuration are as follows:
One WebSphere Commerce Suite instance per development workstation
Shared (or local) WebSphere Commerce Suite database
Shared (or local) WebSphere Application Server database
Shared (or local) VisualAge for Java repository
Shared (or local) WebSphere Studio directory
External SCM Tool

158
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 8-1 Full WebSphere Commerce Studio development environment
Ideally each developer has a full development environment set up on his or her
workstation, including WebSphere Commerce Suite and WebSphere Commerce
Studio. This provides developers with full functionality and testing capabilities.
Using shared databases located on a remote database server reduces resource
utilization on the developers’ workstations. The presence of one WebSphere
Commerce Suite instance per workstation makes development workstations
independent of each other.
Within this environment, Java developers work with a unique repository and can
share code. Page developers can get beans from the same repository. This
allows for code consistency and updates can be maintained.
Note: Although we are describing a development environment with shared
resources (database and repository) it is possible to set up an environment
with a database on every development workstation and every developer
working with his/her own VisualAge for Java repository. For more detailed
information, refer to WebSphere Commerce Suite V5.1 Customization and
Transition Guide, SG24-6174.
Tip: Having your own WebSphere Commerce Suite instance is most helpful if
you need to restart the WebSphere Commerce Suite application server or
even the machine.
WCS
WAS
IHS
DBClient
VAJ
WSStudio
WCS
Server
WCS
WAS
DBServer
IHS
EMSRV
Rational ClearCase
WSStudio
StagingArea Production
Development
Workstation1
WCS DB
WASDB
Development
Workstation2
Development
Workstation3
WCS

Chapter 8. Application development guidelines
159
For more details on how to set up a team environment with WebSphere Studio
and VisualAge for Java, please refer to the following redbooks:
WebSphere Commerce Suite V5.1 Handbook, SG24-6167
Version 3.5 Self Study Guide: VisualAge for Java and WebSphere Studio,
SG24-6136
WebSphere Commerce Suite V5.1 Customization and Transition Guide,
SG24-6174
Light commerce development environment
WebSphere Commerce Suite together with WebSphere Commerce Studio can
be a very resource-intensive development environment. Together, the two can
require almost 1 GB of RAM on a development machine. However, not all the
development team members need to be running a WebSphere Commerce Suite
instance in order to be productive.
In this section, we have outlined a WebSphere Commerce Suite development
that does not require running a WebSphere Commerce Suite instance on the
same developer machine, as shown in Figure 8-2 on page 160.
The main features of this configuration are as follows:
Central server with WebSphere Commerce Suite
Developer workstation without WebSphere Commerce Suite instance
installed (instance on a common server)
Shared (or local) WebSphere Commerce Suite database
WebSphere Application Server database on server
Shared (or local) VisualAge for Java repository
Shared (or local) WebSphere Studio directory
Note: It is important to establish clear roles in the development team to avoid
problems with lost code, inconsistency, and recurring bugs.

160
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 8-2 Light WebSphere Commerce Studio development environment
Please refer to WebSphere Commerce Suite V5.1 Customization and Transition
Guide, SG24-6174 for more details on how to set up this environment.
Figure 8-1 and Figure 8-2 show that developers should also use the server
machine where all their code can be tested as one solution. In a full team
development environment, all developers can use the same code, and test it in
their own WebSphere Test Environment; however, to test the store it is better to
use the WebSphere Commerce Suite server machine. After your e-commerce
solution is fully tested and functional, it is then deployed to the staging area
where it can be accessed and tested by the customer. Once the customer has
agreed to the changes, it can be deployed to the production WebSphere
Commerce Suite runtime environment.
WAJ
WS Studio
DB Client
Development
Workstation
WCS
Server
WCS
WAS
DB Server
IHS
EHSRV
Rational ClearCase
VAJ
WS Studio
Staging Area Production
WCS DB
WAS DB

Chapter 8. Application development guidelines
161
To implement the right strategy for your environment, we have provided a
summary of considerations in Table 8-1.
Table 8-1 Pros and cons of team development approaches
The light development environment is best suited for small teams and basic
customization goals. For intermediate and advanced customization and for
bigger teams, we recommend a full development environment.
8.2.2 Development environment installation
This section provides high-level installation guidelines for the WebSphere
Commerce Suite development environments.
Topic Full development
environment
Light development
environment
Resources Heavy resources requirements
(at least 512 MB RAM for each
development workstation and 1
GB on WebSphere Commerce
Suite server) and external tools
(SCM).
Fewer resource constraints:
basic HW and SW
requirements should follow the
recommended environment for
VisualAge for Java V3.5.
Performance, however,
decreases quickly on
decreasing of resources.
Independence in
development
Workstations are independent
of each other and don’t need
WebSphere Commerce Suite
running on the server (except
for database)
Workstations are strongly
dependent on server
installation. A crash on the
server could mean problems for
all development teams.
SSL testing Possible if server and
workstations use separate
databases
Not possible because the
WebSphere Test Environment
has to be installed on the
server.
Note: We chose to have a central database to preserve consistency of data. A
similar configuration can be set up with a database on each workstation. This
second choice could cause problems in keeping data up-to-date. On the other
hand having a separate database and WebSphere Commerce Suite server on
your workstation can allow testing the application in SSL mode before going
on the staging server, because WebSphere Test Environment is not needed
on the server (the full development environment configuration).

162
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
WebSphere Commerce Studio installation
Another benefit of a shared development environment is to offload resources to a
common system. This kind of environment can accommodate development
shops that may be hardware resource constrained, as described by the
requirements of the WebSphere Commerce Studio.
There are several methods for installing and configuring the WebSphere
Commerce Studio components:
WebSphere Commerce Studio - umbrella install
The procedure installs and configures WebSphere Commerce Studio and
VisualAge for Java by using the product-supplied umbrella-like install. If you
are not familiar with these tools we recommend that you use this method of
installation. This method of installation works well in an environment that is a
clean install (no existing components).
For detailed instruction on installing refer to Installation Guide, IBM
WebSphere Commerce Studio V5.1 Professional Developers Edition for
Windows NT and Windows 2000, found in the /docs/<locale> directory of the
WebSphere Commerce Studio V5.1, Professional Developer Edition for
Windows NT and Windows 2000 CD.
WebSphere Commerce Studio - manual component install
This procedure installs and configures the WebSphere Commerce Studio
components manually. The configuration of VisualAge for Java is done
manually. This method of installation is available for developers who may
already have IBM VisualAge for Java V3.5, Enterprise Edition installed or
decide to install it separately.
For detailed instruction on installing refer to WebSphere Commerce Suite
V5.1 Handbook, SG24-6167.
Team development environment - manual distributed install
This procedure involve setting up a shared development environment. This
shared environment may have multiple WebSphere Commerce Suite
instances on a shared WebSphere Commerce Suite runtime environment
server and requires the installation of some external SCM tool (for example,
Rational ClearCase).
This is the ideal development environment, because developers can work
together on a single body of code. It makes the best use of the version and
source control available in WebSphere Studio and VisualAge for Java. This
environment allows you to share data too, which assures uniform behavior of
code and better testing performance. However, you have to balance between
features and complexity of configuration. For example, a small team may not
need a versioning tool, since everything could be done with good team
organization.

Chapter 8. Application development guidelines
163
8.2.3 Team development environment with VisualAge for Java
IBM VisualAge for Java ships with an integrated team development environment
based on a shared repository. This repository is managed by the team server
(EMSRV). Using EMSRV does not require an external SCM tool and can be set
up fairly easily.
Change control within VisualAge is not file based, but it works at the object level
and is based on object ownership. In the VisualAge for Java team development
environment, every project, package, and class has one person who is
responsible for the quality of that program element, and who has the most
authority over it. That person is the program element’s owner.
Team members connect from their clients to the shared repository. Once
connected, they can perform the following tasks:
Find program elements in the shared repository, including those developed or
owned by other team members.
Bring various editions of those program elements into their workspaces.
Create, change, test, and version program elements.
Release editions of program elements that they own for other team members
to use as a common baseline.
Selectively replace editions of program elements in their workspace with
other editions released by other members of the team.
VisualAge for Java’s team features are optimized for object-oriented
development in fast-moving, iterative, prototyping development environments.
They are flexible and offer a high level of programmer productivity, while also
providing stability.
For more detailed instructions and information on team programming and
EMSRV, refer to:
VisualAge product documentation: IBM VisualAge for Java, Version 3.5 Team
Programming
IBM VisualAge developer domain home page at:
http://www.ibm.com/vadd/
8.2.4 Team development with WebSphere Commerce Studio
WebSphere Studio can be integrated with an SCM tool such as Rational
ClearCase or MERANT PVCS Version Manager to have full control of software
releases. If you don not have a tool for SCM, WebSphere Studio provides a team
environment with basic features such as file check-in and access control.

164
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
WebSphere Studio does not provide real source code management with
versioning and other SCM facilities.
Basically, if you place the project files on a LAN drive that is accessed by all team
members using the same shared folder, you can share the process and you can
manage the project for the team.
When editing files, they are checked out, and only one team member can have a
file checked out. Make sure that files are checked in quickly again after editing.
Checking out a file is done automatically if the file is edited by launching it from
WebSphere Studio. Developers can also manually check out a selection of files
by highlighting them and selecting Project -> Check Out (or use the pop-up
menu). Files that are checked out have a small red check mark placed in front of
the file name, providing a visual clue to other developers as to which resources
are checked out. This mechanism is very useful in a team environment to
prevent simultaneous edits to the same project resource, which may result in
loss of data. A checked-out file remains that way until a check-in option is
performed on the file. When a file is checked out, a copy of the file is placed in
the checkout directory:
x:\<WebSphere Studio_install_path>\check_out\<projectname>\folder\
Any editing of the file is performed on this copy of the file. Only when the file is
checked in does the edited file get copied back into the original project directory.
This feature allows the developer to publish the file for testing and easily undo
any changes made to a file if desired (Project -> Undo Check Out). When a
check-in or an undo check-out operation is performed, the copy of the resource
in the checkout directory is deleted.
For more detailed information on WebSphere Studio and team development
please refer to:
How about Version 3.5? VisualAge for Java and WebSphere Studio Provide
Great New Function, SG24-6131
More information on WebSphere Studio can be found at:
http://www.ibm.com/software/webservers/studio/
Figure 8-3 on page 165 shows how assets (images, JSPs, Java files) should flow
in a distributed development environment with an external SCM tool. In
WebSphere Studio it is possible to use and associate different editors for
Note: In WebSphere Studio there are no differentiated roles, such as
administrator or developer, so you need to clearly establish the roles among
your team members.

Chapter 8. Application development guidelines
165
different file types. As seen in Figure 8-3 on page 165, you could use another
HTML editor instead of Page Designer, an image editor for multimedia files.
Figure 8-3 Asset flow within a team development environment
8.2.5 Publishing targets
WebSphere Studio provides the capability to publish one, several, or all assets in
a project. In addition, by setting up different stages and servers within Studio,
you can publish different store assets to different servers and target paths. As
seen in Figure 8-4 on page 166, a sample distributed development environment
with a local WebSphere Test Environment, a local/remote WebSphere
Commerce Suite environment and a store archive. In a similar scenario you can
set WebSphere Studio to manage the requirements.
Create andDebugCommands,EJB
Create HTML and JSPViewCode
Other Tools
Used During
Development
(Word,Notes,etc.)
VisualAge
for Java
WebSphere
StudioPage
Designer
WebSphere
Studio
WCS
Rational
Clearcase
Creation and Use
of Files
Source Control
Management
Publishing

166
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 8-4 Publishing settings on WebSphere Studio
Each developer can publish from his/her machine: locally to the WebSphere Test
Environment or on the remote server machine on WebSphere Commerce Suite
runtime. The administrator then checks on the server and publishes to a SAR file
or to the staging server.
This strategy allows each developer to be independent in his WebSphere Test
Environment and not interfere with others. If WebSphere Studio is the only
source control tool used for Web assets (JSPs, properties files, images, etc.)
developers should be careful when publishing, since versions are not controlled.
However, WebSphere Studio can be configured for multiple publishing targets
according to the requirements.
For more detailed information on WebSphere Studio and team development,
please refer to the WebSphere Commerce Suite V5.1 Handbook, SG24-6167.
Note: Be warned that during re-publishing your store using Store Services,
command line or via Studio (exception: publishing single files in Studio!) your
assets in the following folders will be deleted automatically, because
WebSphere Commerce Suite deletes the whole folder, including all content,
and recreates them anew.
Your store’s property folder under <wcs_install_path>\stores\properties\
Your store’s folder and subfolders under <wcs_install_path>\stores\web\
Tip: In this case the Software Version Controller (role explained in “Roles” on
page 169) could force developers to publish only one file at a time in their
WebSphere Test Environment.
Development
Workstation
Commerce
Server
Staging
Server
Production
Publish:Local (WTE)
Publish.Remote (WCS)
Publish Remote (Production)
Publish Local (SAR)
Publish Remote (Staging)

Chapter 8. Application development guidelines
167
8.2.6 Packaging a SAR
A store archive file, called a SAR file (with a file extension .sar), is a compressed
archive file that contains all the assets necessary to create a store. The SAR file
consists of the following:
Web assets: The files used to create your store pages, such as HTML, JSP
files, images, graphics and include files. Web assets are grouped together as
a compressed archive file in the store archive. When a store archive is
published, the Web assets are published to the Web application document
root.
Property resource bundle: A file containing all of the text on your store pages.
If your store supports more than one language, the resource bundle will
contain multiple bundles, that is, one bundle per language. Property resource
bundles are grouped together as a compressed archive file in the store
archive. When a store archive is published, the text assets are published to
the classpath.
Store database assets: The data to be loaded into the database. Store
database assets include the following data: campaign, catalog, command,
currency, fulfillment, offering, shipping, store, tax and quantity units. For a
complete list of required data, refer to Store Developer: Building a Store
Archive, IBM WebSphere Commerce Suite V5.1, product guide found on the
WebSphere Commerce Suite V5.1 CD.
The store database assets must be of well-formed XML files valid for the
Loader Package.
Payment assets: Configuration information for the WebSphere Payment
Manager.
Descriptor: An XML file, sarinfo.xml, that describes the store archive,
including the names of the Web assets compressed archive file, the resource
bundles, and the store database asset XML files. The sarinfo.xml file also
contains the names of include files and consistency checking files, as well as
information about the archive file that is needed during the publishing
process.
For more detailed information about the contents of a SAR file and publishing
targets, please refer to the WebSphere Commerce Suite V5.1 Handbook,
SG24-6167.
Most of the assets in the SAR file, such as JSP pages, HTML pages, graphics
and include files, can be customized, managed, and deployed by WebSphere
Commerce Studio. Using Commerce Studio, you can edit the store pages and
other file assets using Page Designer, other Studio tools, or with tools registered

168
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
with Studio such as XML Spy. From Studio you can publish the files to a
VisualAge for Java WTE, a WebSphere Commerce Suite runtime environment
for testing, or to the local file system PackageSAR directory in preparation for
creating your own SAR file.
For more detailed information about the store assets, refer to the following
redbooks:
WebSphere Commerce Suite V5.1 Handbook, SG24-6167
WebSphere Commerce Suite V5.1 Customization and Transition Guide,
SG24-6174.
8.2.7 Source Control Management and build guidelines
The interface for VisualAge for Java to external version control systems uses
Microsoft's Source Code Control Interface (SCCI) API. Currently VisualAge for
Java supports the following SCM systems:
ClearCase for Windows NT Version 4.0, from Rational Software Corporation.
PVCS Version Manager Version 6.0, from MERANT (formerly INTERSOLV).
Visual SourceSafe Version 6.0, from Microsoft.
IBM VisualAge TeamConnection Version 3.03.
If you select to install the interface when you install VisualAge for Java, you can
use the External Version Control menu for convenient access from the VisualAge
for Java IDE to an existing SCM tool. There is no relationship between external
SCM functions and the version control provided by VisualAge for Java. If you use
another SCM tool to manage program elements developed in VisualAge for
Java, you will have to correlate the names, contents, and versions of program
elements in the two systems.
Note: At the time of writing this redbook, the Commerce Studio extensions for
import and export only support the Web application store assets (webapp.zip).
For this reason, we unzip all SAR store assets manually to the local file
system and then import these assets to Studio manually.

Chapter 8. Application development guidelines
169
Figure 8-5 VisualAge for Java installation - External version control
Here are some hints on how to apply SCM in a WebSphere Commerce Suite
project:
Roles
Naming conventions
Clock settings
Roles
Below are described the roles that are fundamental in a team development
environment; obviously, each team member can play different roles.
Team leader: Create and validate the functional specifications for each
component to be developed. Once approval of the functional specification has
Note: If you decide to use an external SCM tool you have to select the
optional feature, External Version Control, during VisualAge for Java
installation (see Figure 8-5). Installing this interface does not disable or
interfere with the built-in software management features of VisualAge for Java.

170
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
been given, the specification is versioned and placed under change control.
Participate in code walkthroughs to verify the validity of the design and the
code being written. Once code has been verified and approved, it is versioned
and placed under change control.
Developer: Check out and check in files, as necessary, during the
development life cycle. When versioning files, follow the correct
version-naming scheme. When checking in files, provide comments on the
changes made to each file. Work with open and versioned editions in
VisualAge for Java. Creating scratch editions of program elements to
experiment within VisualAge for Java. Participates in code walkthroughs.
Software Version Controller: Monitor the version control repositories and
perform any required maintenance, when needed. Periodically purge program
elements that are no longer required. Work with the Network Administrator to
ensure that the necessary files are being backed up on a nightly basis.
Manipulate versions and editions of program elements.
Build Manager: Working with the Software Version Controller, create
baselines of code assets; if different tools are used (for example, VisualAge
for Java code and Rational ClearCase for other assets) the different baselines
must coincide. Communicates with the development team, to identify the
baseline that future development should occur on. This allows the developers
to re-baseline their VisualAge for Java workspace with the most recent
approved set of assets. Working with the Software Version Controller provides
the ability to roll back the assets in any environment to any specified baseline.
This also includes communicating with the development team about which
baseline is being rolled back to.
Network Administrator: The Network Administrator manages the disaster
recovery of each tool involved in the source code management. This involves
the backing up and restoring all code repositories. The backup of the source
code management assets should be performed on a nightly basis.
Naming conventions
Careful organization of code is required, to ensure that deployment is successful.
As a standard, all names of repositories, projects and EJB groups should contain
the name of the company the project is for.
When creating new commands and data beans, you should place them in a
package that is named appropriately for your application. According to
WebSphere Commerce Suite naming conventions you could package your code
following type of class (command, bean, other) and the related subject (order,
member, catalog, etc.). To keep track of the custom package you could change
“ibm“ in package name with something else (name of customer, name of your
company, etc.) For example, you could create a new package by the name of

Chapter 8. Application development guidelines
171
com.myco.commerce.order.commands in which you keep your new commands
working on order processing. This package must be stored within a project that is
separate from the Commerce Suite projects (Commerce Server and Commerce
Server Enterprise Beans).
In customizing standard commands, you could maintain the same class name,
modifying the package name (if you have to customize the controller command
“OderItemAddCmdImpl“ by extending it, you could create a custom controller
command and call it by the same name, modifying the package containing it, as
shown in Example 8-1).
Example 8-1 Naming Conventions in extending standard command
package com.myco.commerce.orderitem.commands
public class OrderItemAddCmdImpl extends
com.ibm.commerce.orderitem.commands.OrderItemAddCmdImpl{
//custom code here
}
In the event that there are multiple projects for the same company, append an
underscore and a one- or two-word description to the end of the company name.
The same applies to Projects. Folder names for java, jsp, html, JavaScript,
properties, and XML files should match the file extension (for example, the
JavaScript file test.js should be in the js folder). All other project resources
should be maintained in a Project Resources folder. The directory structure
below project resources is open to each implementation.
When creating new entity beans or session beans, you must create them in an
EJB group that is separate from the Commerce Suite EJB groups. This new EJB
group should be stored in a new project that is separate from the Commerce
Suite projects. For example, if you are creating a custom EJB to work on order
Subsystem, you might create the “MyCoWCSOrder” EJB group within the
com.myco.commerce.order.objects package in the “MyCo Commerce Server
Enterprise Beans“ project. This new project must contain only EJB code and it
should not be used for any commands or data beans. This separation of types of
code is required for deployment purposes. By separating your own customized
code from the Commerce Suite code, you will minimize the impact of migrating to
future releases.
In case you decide to extend WebSphere Commerce Suite EJB (as explained in
“Customization approaches” on page 192) and you add new finder methods to
the public enterprise beans, you must follow a particular naming convention for
the methods. Name the new methods findX a_description where a_description is
a description of your choice. Some examples of names are findXByOwnerId and
findXByOrderStatus.

172
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Using this naming convention avoids the risk of name collision (duplicate names)
with Commerce Suite finder methods.
If you are planning to add custom tables to WebSphere Commerce Suite
database, there are some naming conventions on table and column names:
In order to avoid name collision (duplicate names) with Commerce Suite
tables and views in future releases, the first character in the table or view
name should be X (XTABLE). If you are extending standard WebSphere
Commerce Suite tables you could use an appropriate name (XE_ORDERS
extending standard table ORDERS). Table names should be no more than 10
characters in length.
In order to avoid name collision (duplicate names) with columns in Commerce
Suite tables in future releases, the first character in the column name should
be X (XCOLUMN). The column name should be no more than 18 characters
in length.
Working folders
To maintain file integrity, make sure that all users have their own working folders
for all projects. When multiple users share a working folder, a file checked out by
one user can be modified by anyone with access to that folder. Maintaining
separate working folders ensures that users modify only files they have checked
out themselves.
System clocks
Synchronize the dates and system clocks of all client computers with the server.
This prevents check-in and checkout operations from appearing to happen out of
sequence. Synchronizing dates and system clocks is particularly important when
users from different time zones access the same database.
8.2.8 Unit testing guidelines
Unit tests are informal tests that are generally executed by the developers on the
application code they are developing. They are often quite low-level in nature,
and test the behavior of individual software components such as individual Java
classes, servlets or EJBs. Because unit tests are usually written and performed
by the application developer, they are often “white-box” in nature, that is to say
they are written using knowledge about the implementation in mind (for example,
to test specific code paths). This is not to say all unit tests have to be written this
Note: If running Microsoft Windows NT you can set up the server to act as a
Domain Time Source server for users to synchronize their local date and time
with the network.

Chapter 8. Application development guidelines
173
way, one common practice is to write the unit tests for a component based on the
component specification before developing the component itself. Both
approaches are valid when defining your own unit testing policy; you may wish to
make use of both.
We test to find defects in our code, and to verify that changes that we have made
to existing code do not break that code. Often developers do not perform unit
tests because it is too hard, and because nobody forces them to. Writing an
effective set of unit tests for a component is not a trivial undertaking. Given the
pressure to deliver that many developers find themselves subjected to, the
temptation to postpone the creation and execution of unit tests in favor of
delivering code fixes or new functionality is often overwhelming.
This usually turns out to be a false economy: developers very rarely deliver
bug-free code, and the discovery of code defects and the costs associated with
fixing them are simply pushed further out into the development cycle. This is
inefficient; the best time to fix a code defect is immediately after the code has
been written, while it is still fresh in the developer’s mind.
Furthermore, a defect discovered during a formal testing cycle must be written
up, prioritized and tracked; all of these activities incur cost, and may mean that a
fix is deferred indefinitely, or at least until it becomes critical. Based on our
experience, encouraging and supporting the development and regular execution
of unit test cases ultimately leads to significant improvements in productivity and
overall code quality. The creation of unit test cases need not be a burden.
Developers often find the intellectual challenge quite stimulating and ultimately
satisfying. The thought process involved in creating a test can also highlight
shortcomings in a design that might not otherwise have been identified in a
situation where the main focus is on implementation. We recommend that you
take the time to define a unit testing strategy for your own development projects.
A simple set of guidelines and a framework that makes it easy to develop and
execute tests will pay for itself surprisingly quickly.
Test framework and test cases
Once you have decided to implement a unit testing strategy in your project, the
first hurdles to overcome are the factors that dissuade developers from creating
and running unit tests in the first place. A testing framework can help by:
Making it easier to write tests
Making it easier to run tests

174
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Tests are easier to write, because a lot of the infrastructure code that you require
to support every test is already available. A testing framework also provides a
facility that makes it easier to run and re-run tests, perhaps via a GUI. The more
often a developer runs tests, the quicker problems can be located and fixed,
because the delta between the code that last passed a unit test and the code that
fails the test is smaller.
Testing frameworks also provide other benefits:
Consistency
Because every developer is using the same framework, all of your unit tests
will work in the same way, can be managed in the same way, and report
results in the same format.
Maintenance
Because a framework has already been developed and is probably already in
use in a number of projects you spend less time maintaining your testing
code.
Ramp-up time
If you select a popular testing framework, you may find that new developers
coming into your team are already familiar with the tools and concepts
involved.
Automation
A framework may offer the ability to run tests unattended, perhaps as part of a
daily or nightly build
Tool integration
A framework may have the ability to integrate with existing development tools
such VisualAge for Java.
For more detailed information on unit testing and about test cases, refer to:
WebSphere Version 4 Application Development Handbook, SG24-6134
Servlet and JSP Programming with IBM WebSphere Studio and VisualAge for
Java, SG24-5755
8.3 Commerce application development
This section includes development guidelines for the following components of
WebSphere Commerce Suite applications:
JSP
Properties files

Chapter 8. Application development guidelines
175
Commands
EJBs
XML data files
SQL script files
8.3.1 JSPs
JavaServer Pages or JSPs are the principle method of formatting data for
display. A JSP is invoked by the view command specified in the view registry.
JSPs make use of data beans to display dynamic data from the database. They
carry out the view aspect of the Model-View-Controller design pattern. Ideally,
they have a very small amount of processing and are primarily concerned with
formatting the data presented by the data bean.
General information
JSPs are at the heart of the WebSphere Commerce Suite multicultural support
functions. JSPs templates are used in WebSphere Commerce Suite to do the
following:
Include whole page components dynamically using include statements (for
example, to include a complete header).
Retrieve static text from locale specific text-based properties files (for
example, to show labels for entry fields in different languages).
Retrieve dynamic data (for example, the calculation of taxes).
In order to take full advantage of the benefits provided in WebSphere Commerce
Suite, you should keep JSPs as language neutral as possible.
At runtime, each requested JSP includes the file getResource.jsp. Within this file,
the command context is retrieved, and from that, the locale is used to retrieve the
infashiontext properties Java object, which obtains its values from the
infashiontext.properties file in the appropriate locale-specific directory. The
template then has access to each of the properties as needed, through the use of
the getProperty() method of the properties object.
The template uses a similar method to display translated image files, such as
buttons or banners. The locale and language are retrieved at runtime to
determine the correct folder in which to look for the image file. In the example
above, the template might look for the file
Infashion/<language_Locale>/images/go_button.gif, where <language_Locale>
is replaced by the display format from the command context.
For example, the resulting page will display the image:

176
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Infashion/en_US/images/go_button.gif
or
Infashion/it_IT/images/go_button.gif
During the creation of a JSP, it is better to clearly separate the Java code from
formatting HTML. This is mandatory for maintenance of a store’s look and feel. It
is very difficult to review Web style in a page with a mix of programming and
formatting statements.
A typical JSP template should be composed of three parts:
Java code (data beans, variables, etc.)
Style scripts (JavaScript, libraries)
Display code
Sometimes it is impossible to separate the three parts. In this case, write
comments to help future developers to understand the flow.
Retrieve data within a JSP
To retrieve data from a WebSphere Commerce Suite store database you need to
use data beans.
A data bean is a Java bean that is used within a JSP template to provide
dynamic content. A data bean normally provides a simple representation of a
Commerce Suite entity bean. The data bean encapsulates properties that can be
retrieved from or set within the entity bean. As such, the data bean simplifies the
task of incorporating dynamic data into JSP templates.
A data bean is activated by the following call:
com.ibm.commerce.beans.DataBeanManager.activate(DataBean,HTTPServletRequest)
Example 8-2 shows how to manage a data bean. First an object (data bean) is
instantiated, then it is activated. Finally you can obtain data by its “getter”
methods.
Example 8-2 Data bean activation in LoginForm.jsp
UserRegistrationDataBean userRegistrationDataBean =
new UserRegistrationDataBean();
com.ibm.commerce.beans.DataBeanManager.activate( userRegistrationDataBean,
request);
String userType = userRegistrationDataBean.getRegisterType().trim();

Chapter 8. Application development guidelines
177
WebSphere Studio Page Designer generates the code seen in Example 8-2
automatically when a Commerce Suite data bean is inserted into a JSP template.
Modifying the store directory structure
The directory structure of WebSphere Commerce Suite sample stores InFashion
and WebFashion are fairly flat. The only subdirectories are “images” and
“<locale>”; however, it is possible to modify the subdirectory tree to meet
particular needs. In this case you have to modify the view registry, which is
contained in the VIEWREG table.
The VIEWREG maps a view name to a view command interface and
implementation. The key columns of the view registry are highlighted in
Table 8-2.
Table 8-2 VIEWREG table
The name of the JSP is specified in the PROPERTIES column. The
PROPERTIES column typically has the form: docname=<JSP_file_name>&
property1=value1&property2=value2. Where propertyN is the name of the
property and valueN is the value corresponding to the property.
Note: Store developers should consider properties of the store and
multicultural enablement issues when developing JSP templates. For more
information on multicultural enablement, refer to the Commerce Suite online
help, and the WebSphere Commerce Suite V5.1 Handbook, SG24-6167.
Database table column Description
VIEWNAME The name of the view.
STOREENT_ID The ID of the store.
DEVICEFMT_ID An integer specifying the device used to
access the view.
INTERFACENAME The name of the view command interface
to use.
CLASSNAME The implementation of the view command
interface.
PROPERTIES The default properties associated with this
view.
HTTPS Indicates if secure HTTP is required for
this URL.

178
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
The INTERFACENAME and CLASSNAME together indicate the method to use
to invoke the view. The class specified in the CLASSNAME implements a view
command interface to display the JSP specified in the docname property of the
PROPERTIES field, supplying additional properties as parameters to the JSP.
Figure 8-6 on page 179 shows the flow of a command. When the Web controller
needs to know the name of the JSP to be shown, it queries the VIEWREG table
and by default looks in the <StoreName> folder. You can specify an additional
path by editing the entry of the PROPERTIES column.
If you want to divide all order pages and put in the “order” subfolder you have to
do the following (for OrderDisplayPending.jsp):
Create an “order“ subfolder in the <wcs_install_path\stores\web\store_name>
folder.
Move order JSPs to that folder.
Update the entries in the VIEWREG table:
UPDATE VIEWREG SET PROPERTIES = 'docname=order\OrderDisplayPending.jsp'
WHERE PROPERTIES = 'docname=OrderDisplayPending.jsp'

Chapter 8. Application development guidelines
179
Figure 8-6 Flow of commands
Note:
A JSP can be called by more view tasks, so you have to modify all the
entries referring to it.
You will have to copy the GetResource.jsp in the sub folders, otherwise
you will have to modify JSP code.
URLREG
Table
CMDREG
Table
Controller
Command
implementation
class
VIEWREG
Table
JSP template
queries
return interface
name
queries
return interface
name
invokes
return view
name
queries
return JSP
name
invokes
return Web
content
RequestServlet
User view of
command

180
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
WebSphere Application Server tuning for JSP compiling
In WebSphere Application Server V3.5 and above, the JSP processing engine is
implemented as a servlet. The JSP servlet is invoked to handle requests
destined to all JSP files matching the assigned URL filter, such as /webapp/*.jsp.
Each time a JSP is requested, the corresponding disk file is checked to see if a
newer version is available. This can be an expensive operation. WebSphere
Commerce Suite V5.1 has two Web applications named WCS Stores and WCS
Tools. Change the rechecking interval by adding an init parameter,
minTimeBetweenStat, to the JSP servlet named “WCS JSP Compiler” in each of
the two Web applications.
To update WebSphere Application Server for the JSP compiling, complete the
following steps:
1.Start the WebSphere Application Server Administrator’s Console.
2.Select and expand

WebSphere Administrative Domain

-> <your node
hostname> -> WebSphere Commerce Server - <your instance name> ->
servlet engine WCS Web container.
3.Expand both Web applications named WCS Stores and WCS Tools.
4.Click each JSP servlet named WCS JSP Compiler, and select the Advanced
tab to display the WCS JSP.
5.Enter a new parameter name as minTimeBetweenStat in the Init Parameters
table and enter a value for it. The default value is 1000(ms), and 100,000 is
recommended. Then click Apply to save your changes.
For more information on tuning, please refer to WCS V5.1 Performance Tuning,
SG24-6258.
Batch compiling
It is possible to compile JSPs with a batch process. This is especially useful
when deploying to WebSphere Application Server for quicker setup of the
runtime environment.
To use batch compiler for JSP 1.0 files, you may enter the following command on
a single line at an operating system command prompt, or preconfigure the
batchcompiler.config file:
JspBatchCompiler -adminNodeName <node name> [-serverName <server name>]
[-application <application name> >] [-filename <file name>] [-keepgenerated
<true | false>]
Where:
– adminNodeName is the name of the node as shown on the Administrative
Console.

Chapter 8. Application development guidelines
181
– serverName (this is optional; may only be used if adminNodeName is set) is
the name of the Application Server in the WebSphere environment on
which you wish to perform this action. Unless you have set up other
servers, this will be "Default Server". (Note that from the command line,
you will need to include quote marks around the name of the server if that
name comprises two or more words separated by spaces. You do not
have to do this if you use the batchcompiler.config file described below.)
– application (this is optional; may only be used if serverName is set) is the
name of a particular Web application, should you wish to compile only
those JSP files under that application.
– filename (this is optional; may only be used if application is set) is the
name of a single file in the Web application you selected above, should
you wish to compile only a single JSP file in an application.
– keepgenerated (this is optional), if set to "yes", will keep the generated
.java files used for compilation on your server. By default, this is set to "no"
and the .java files are all erased after the class files have been compiled.
In lieu of specifying the parameters in a command line, you may specify them in
the batchcompile.config file, located in the WebSphere Application Server bin
directory. No quotation marks are necessary for any of the variables if you use
this file. Any values you enter on the command line will override the values
specified in the batchcompile.config file.
For example, suppose you want to precompile the JSP files associated with the
examples application shipped with WebSphere Application Server. Issue the
following command in the WebSphere Application Server bin directory:
D:\WebSphere\AppServer\bin>JspBatchCompiler.bat -adminNodeName mynode
-serverName "Default Server" -application examples
You should receive the following response from the server:
Server name: Default ServerApplication Name: examples JSP version: 1.0
docRoot: d:\WebSphere\AppServer\hosts\default_host\examples\web
Application Classpath:
d:\WebSphere\AppServer\hosts\default_host\examples\servlets; Application
output dir: d:\WebSphere\AppServer/temp/default_host/examples URL: .jsp
URL: .jsv URL: .jswAttempting to compile:
d:\WebSphere\AppServer\hosts\default_host\examples\web\debug_error.jspCompi
lation successful Attempting to compile:
d:\WebSphere\AppServer\hosts\default_host\examples\web\HelloHTML.jspCompila
tion successful.
Attempting to compile:
d:\WebSphere\AppServer\hosts\default_host\examples\web\StockQuoteWMLRequest
.jsp

182
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Compilation successful Attempting to compile:
d:\WebSphere\AppServer\hosts\default_host\examples\web\StockQuoteWMLRespons
e.jsp Compilation successful
If you look in the WebSphere Application Server temp directory (for example:
<was_install_path>\temp\default_host), you should see a directory named
examples. All of the compiled class files for the examples application will be in
this directory.
WebSphere Commerce Suite has its own version of the JSP batch compiler:
called WCSJspBatchCompiler.bat, located in the <wcs_install_path\bin> folder.
The batchcompiler.config should be left in the <was_install_path\bin> folder.
WCSJspBatchCompiler.bat has new JAR file entries for WebSphere Commerce
Suite classes, so it will pick up most of the needed classes, but still will not
compile all of the JSPs. The JSP compiler cannot handle some JSPs that include
other JSPs.
For more information on batch compiling, refer to:
http://www.ibm.com/software/webservers/appserv/
JSP template error handling
Error handling for JSP templates can be performed in various ways:
Error handling from within the page
For JSP files that require more intricate error handling and recovery, the file
can be written to directly handle errors from the data bean. The JSP file can
either catch exceptions thrown by the data bean or can check for error codes
set within each data bean depending on how the data bean was activated.
The JSP file can then take an appropriate recovery action based on the error
received.
Error JSP at the page level
A JSP file can also specify its own default error JSP template from an
exception occurring within itself through the JSP error tag (Example 8-3).
Note: Batchcompiler.config is case sensitive. You should use the exact case
in all of your entries.
Note: A JSP can use any combination of the following error handling
scopes.

Chapter 8. Application development guidelines
183
Example 8-3 Error handling at a JSP level, sample JSP
<!--JSP code -->
<!--the following directive in case of error redirects to MyError.jsp page-->
<%@ page isErrorPage="false" errorPage="MyErrorPage.jsp" %>
<% try {
//some Java code
}catch (Exception e)
{
e.printStackTrace();
throw new Exception("Error on JSP !!");
}
%>
This enables a JSP program to specify its own handling of an error. You will have
to create your own Error JSP (Example 8-4) showing the exception thrown. A
JSP file that does not specify a JSP error tag will have an error fall through to the
application-level JSP error template.
Example 8-4 Example of MyErrorPage.jsp
<?xml version="1.0"?>
<jsp:root>
<%@ page isErrorPage="true" %>
<HTML>
<HEAD> <TITLE>Error Page</TITLE> </HEAD>
<BODY >
<B> WARNING: EXCEPTION <B/>
<BR>
<B> THE EXCEPTION IS<B/>
<%=exception.toString() %>
</BODY>
</HTML>
</jsp:root>

184
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Error JSP at the application level
An application under WebSphere can specify a default error JSP when an
exception from within any of its servlets or JSP files occur. The
application-level error JSP can be used as a mall level or store level (for a
single store model) error handler. In the application-level error JSP, it must
call the servlet helper class to roll back the current transaction. This is
because the Web controller will not be in the execution path to roll back the
transaction.
Whenever possible, you should rely on the preceding two types of JSP error
handling. Use the application-level error handling strategy only when
required.
8.3.2 Properties files
Properties files form an integral part of WebSphere Commerce Suite’s
multicultural support. They contain a locale-specific collection of Java objects in
plain-text-ASCII-format. Potential elements of properties files are as follows:
Text to represent the content.
Labels (for example, used as form field labels).
Messages (for example, errors, confirmations, and status messages).
Alternate text for embedded objects (for example, pictures or Java applets
such as IBM HotMedia applets).
For more details on properties files and customization please refer to:
WebSphere Commerce Suite V5.1 Handbook, SG24-6167
WebSphere Commerce Suite online help
8.3.3 Commands
Commands are Java classes that implement the functionality of the store. Each
command has a single interface and one or more implementation classes. The
decoupling of the command interface and the command implementation allows
multiple implementations of the same command according to the context of the
invocation.

Chapter 8. Application development guidelines
185
The Commerce Suite programming model defines four types of commands:
controller, task, view and data bean commands. When creating new business
logic for your e-commerce application, it is expected that you may need to create
new controller, task and data bean commands. In this section we discuss
controller and task command customization. Data bean commands are treated in
8.3.1, “JSPs” on page 175. We will not discuss view commands, because you
should not need to create these type of commands.
In a typical command flow, a single controller command coordinates the required
processing, using the command factory to invoke task commands to implement
smaller pieces of logic.
A controller command is a focal point used to encapsulates the logic related to a
given business process. A controller command controls the logic flow of the
process using flow-control statements, such as loops and conditional
statements. Also, it invokes specific task commands to implement smaller pieces
of business logic.
Each task command should provide public methods to set the input variables and
public methods to get the output variables.
Customizing approaches
There are basically four approaches to customization of business logic:
Modifying input of a controller command
Modifying behavior of a controller command (usually the performExecute
method)
Modifying a task command
Writing new business logic (new controller/task commands)
WebSphere Commerce Suite controller commands are quite flexible and you can
change the behavior of a command by pushing particular values of input. For
example, suppose you want to force the creation of a new order for a user, even
if Commerce Suite would use the existing one. The OrderItemAdd command
allows for the forced creation of a new order by passing as a value the parameter
“oderId” as seen in Figure 8-7.

186
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 8-7 OrderItemAdd syntax
One way to set this parameter is to override setRequestPropertes() method of
the OrderItemAddCmdImpl controller command as shown in Example 8-5.

Chapter 8. Application development guidelines
187
Example 8-5 Forcing creation of new orders
package com.myco.commerce.orderitem.commands
public class OrderItemAddCmdImpl extends
com.ibm.commerce.orderitem.commands.OrderItemAddCmdImpl {
public void setRequestProperties(TypedProperty prop) throws ECApplication
exception {
boolean newOrderNeeded=false;
//Additional controls that set boolean flag “newOrderNeeded“
if (newOrderNeeded) {
prop.putUrlParam(orderId, “**“);
}
// perform the “real“ setRequestProperties()
super.setRequestProperties(prop);
}
}
If you have to change something in the behavior of a command and it is not
possible to do it with input customization, you can override the main method of
the command with the performExecute() as shown in Example 8-6
Example 8-6 Modifying performExecute() method of a command
package com.myco.commerce.security.commands
public class LogonCmdImpl extends
com.ibm.commerce.security.commands.LogonCmdImpl {
public void performExecute() throws com.ibm.commerce.exception.ECException{
//call standard performExecute
super.performExecute();
//additional code here
}
}
Sometimes you don’t need to alter all the business logic related to a controller
command. In this case, you can customize small parts of the process, acting on
task commands that are called by the controller command.
Modifying a task command is similar to modifying a controller command. They
implement the same interface “com.ibm.sfc.cmd.Command” and the examples
above are applicable with only small variations.

188
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
For heavy customization you can write new commands. This requires recreating
business logic from scratch. We will not treat new command creation in this
chapter. For more detailed information on writing new commands, please refer
to:
WebSphere Commerce Suite V5.1 Customization and Transition Guide,
SG24-6174
Product documentation, available online at:
http://www.ibm.com/software/webservers/commerce/library.html/
Command error handling
Commerce Suite uses a well-defined command error handling framework that is
simple to use in customized code. By design, the framework handles errors in a
manner that supports multicultural stores. The following sections describe the
types of exceptions that a command can throw, how the exceptions are handled,
how message text is stored and used, how the exceptions are logged, and how
to use the provided framework in your own commands.
A command can throw one of the following exceptions:
ECApplicationException: this exception is thrown if the error is related to the
user. For example, when a user enters an invalid parameter.
ECSystemException: this exception is thrown if a runtime exception or a
Commerce Suite configuration error is detected. Examples of this type of
exception include null-pointer exceptions and transaction rollback exceptions.
Both of the exceptions above are classes that extend from the ECException
class, which is found in the com.ibm.commerce.exception package.
In order to throw one of these exceptions, the following information must be
specified:
Error view name: the Web controller looks up this name in the VIEWREG
table.
ECMessage object: this value corresponds to the message text contained
within a properties file.
Error parameters: these name-value pairs are used to substitute information
into the error message. For example, a message may contain a parameter to
hold the name of the method which threw the exception. This parameter is set
when the exception is thrown, then when the error message is logged, the log
file contains the actual method name.
Error data: these are optional attributes that can be made available to the JSP
template through the error data bean.

Chapter 8. Application development guidelines
189
Exception handling is tightly integrated with the logging system. When an
exception is thrown, it is automatically logged.
In order to simplify error message maintenance and to support multilingual
stores, the text for error messages is stored in properties files. Commerce Suite
message text is stored in the ecServerMessages_<locale>.properties files
located in the <wcs_install_path>\properties\com\ibm\commerce\ras\properties
(for example, ecServerMessages_en_US.properties).
All system messages are predefined. You cannot create your own system
messages. Therefore, when customized code throws an ECSystemException, it
must specify a message key for one of the predefined system messages.
Customized user messages can be created. New user messages must be stored
in a separate properties file.
Execution flow tracing
When you are creating new business logic or modifying the existing one, it is very
important to trace the behavior of the application.
Commerce Suite includes the ECTrace class that is used to trace the execution
flow of components running in the WebSphere Commerce Server. The ECTrace
class is part of the com.ibm.commerce.ras package.
When creating new business logic, you can insert a trace within your code to
trace a method for debugging purposes. Information from the trace is captured in
the trace log (called ecmsg_<your_hostname>_<date>.log and located in
<wcs_install_path>\instances\<your_instance_name>\logs). You can specify an
entry and exit point for the trace.
In addition, you can specify that specific data be traced between those two
points. In order to use tracing, it must be enabled for the component in which you
would like to run the trace. To enable tracing for a particular component, use the
Configuration Manager.
When tracing customized code, you must use the EXTERN component. In the
Configuration Manager, this is called External.
To set the entry point for a trace within your code, use the following syntax:
ECTrace.entry (ECTraceIdentifiers.COMPONENT_EXTERN, myClassName,
myMethodName);
Where myClassName is the string representation of the class that contains the
traced method. Since this string can be used to trace file parsing, it should
contain the fully qualified class name.

190
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
If the method being traced is static, then an example declaration of
myClassName is:
String myClassName =”com.myco.commerce.commands.MyCustomCommand";
If the method being traced is not static, then an example declaration of
myClassName is:
String myClassName =this.getClass().getName();
To set the trace point to trace data within a method, use the following syntax:
ECTrace.trace (ECTraceIdentifiers.COMPONENT_EXTERN,myClassName,
myMethodName,myText);
where myText is the text to appear in the trace log.
To set the exit point for a trace within your code, use the following syntax:
ECTrace.exit (ECTraceIdentifiers.COMPONENT_EXTERN,myClassName,
myMethodName);
If you need to trace the object returned from the method being traced, then set
the exit point as follows:
ECTrace.exit (ECTraceIdentifiers.COMPONENT_EXTERN,myClassName,
myMethodName,returnedObject);
where returnedObject represents the Java object returned by the method. It
is recommended that tracing be used only on major functions.
Tracing is not enabled for multiple languages, since it is intended to be used by
store developers. This is in contrast to messages that are enabled for multiple
languages, because system messages are used for administration purposes and
user messages are displayed to customers.
For more detailed information on commands and customization of business logic
please refer to:
WebSphere Commerce Suite V5.1 Customization and Transition Guide,
SG24-6174
WebSphere Commerce Suite online library:
http://www.ibm.com/software/webservers/commerce/library.html/
8.3.4 Enterprise JavaBeans
This section includes the following development guidelines for EJBs:
General information
Deployment descriptors

Chapter 8. Application development guidelines
191
Customization approaches
General information
The Enterprise JavaBeans (EJBs) technology, referred to as beans, provides an
object layer for accessing the persistent data in the WebSphere Commerce Suite
database.
There are two sets of EJBs in WebSphere Commerce Suite, private and public.
The private beans are used by the WebSphere Commerce Suite runtime and
administrative tools. The public beans can be used by the application developer
as is or to extended when developing business logic applications for the store.
WebSphere Commerce Suite uses both session and entity beans. The session
beans perform intensive database operations, usually within the scope of a
single transaction or session with the client. The entity beans represent the
underlying data in the form of Java objects. They form an object layer that is
persistent across multiple transactions. For example, the catalog bean provides
an object model for the logical catalog entity within the store. Once the EJBs are
developed by the Java developer, they are deployed on the WebSphere
Application Server in the EJB container. One of the benefits of using EJBs is that
the WebSphere Application Server is capable of providing scalability.
By using EJBs, each reference to the commerce application data may not
necessitate a direct connection to the database, thus enhancing performance by
minimizing database access. All data within the WebSphere Commerce Suite
database is accessed by using the underlying Enterprise JavaBeans technology.
The EJB architecture defines two types of enterprise beans: entity beans and
session beans. Entity beans are further divided into container-managed
persistence (CMP) beans and bean-managed persistence (BMP) beans. Most of
the Commerce Suite entity beans are CMP entity beans. A small number of
stateless session beans are used to handle intensive database operations, such
as performing a sum of all the rows in a particular column. One advantage of
using CMP entity beans is that developers can utilize the EJB tools provided in
VisualAge for Java, Enterprise Edition. These tools allow developers to define
Java objects and their database table mappings. The tools automatically
generate the required persisters for the entity beans. Persisters are Java objects
that persist Java fields to the database and populate Java fields with data from
the database.

192
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Deployment descriptors
A deployment descriptor is a special class that is serialized and that contains
runtime settings for an enterprise bean. The deployment descriptors for
Commerce Suite enterprise beans are set in a particular way and should not be
modified.
When creating new enterprise beans (entity or session beans), set the
deployment descriptors within the EJB Development Environment (of VisualAge
for Java) by right-clicking the bean and selecting Properties. Deployment
descriptors for new enterprise beans should follow the same convention as those
for the Commerce Suite enterprise beans. In particular, ensure you set the
attributes as seen in Table 8-3.
Table 8-3 Deployment attributes and values for entity beans
An enterprise bean usually contains methods that only read information from the
database, but never perform database updates. These methods are known as
read-only methods. All read-only methods should be explicitly marked as such
(right-click the method and select EJB Method Attributes > Read-only
Method). If read-only methods are not marked in this manner, the EJB container
unnecessarily attempts to update the database at the end of a transaction and
causes a transaction rollback error in the read-only transaction. This causes
performance problems.
Customization approaches
The Commerce Suite object model can be extended in the following ways:
Extend the Commerce Suite’s public enterprise beans:
– Create a new database table.
Note: VisualAge for Java provides extensions to EJB specifications. One of
these is association (relationship between two CMP entity beans). It is
recommended, in order to minimize object model complexity, that you not use
this feature, since it is not used in the original EJBs. Instead, use explicit getter
methods in the enterprise beans.
Attribute Value
Transaction Attribute TX_REQUIRED
Isolation Level TRANSACTION_READ_COMMITED
Run-As Mode SYSTEM_IDENTITY or
CLIENT_IDENTITY

Chapter 8. Application development guidelines
193
– Create a table join between the new table and the existing table that
corresponds to the existing enterprise bean that you are modifying.
– Create new fields in the existing Commerce Suite public entity bean and
map the fields to their corresponding columns in the new table, using a
secondary table map.
– Add any methods required.
– Regenerate the deployed code and access bean for the existing entity
bean.
Write a new entity bean:
– Create a new database table.
– Create a new entity bean for that table.
– Add fields and methods to the entity bean to manipulate the new attribute,
as required.
– Generate deployed code and an access bean for the new entity bean.
Usually, the first approach has better runtime performance, since getting or
setting the new attribute only requires the instantiation of a single entity bean and
a single fetch is used to retrieve all required attributes.
Because the first approach modifies existing Commerce Suite code, a migration
issue arises when a new Commerce Suite code repository is released. You must
merge your customized code with the new code, but when importing the new
repository of code, the mapping information between the fields you added to the
enterprise bean and the new table is not preserved. As a result, when migrating
to a new release of the Commerce Suite code repository the following steps must
be performed:
Version your customized EJB code.
Import the new version of Commerce Suite code.
Using the tools in VisualAge for Java, compare the customized version of
code to the new release of Commerce Suite code. Merge your customized
code back into your workspace.
Manually remap any attributes you added to Commerce Suite public
enterprise beans to the appropriate columns in your database.
Note: You must not add new columns to existing Commerce Suite database
tables. You must create a new table for the new attribute. If you do attempt to
add new columns to existing tables, the new attribute will be lost when you
migrate to future releases of Commerce Suite.

194
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Regenerate deployed code and access beans for the enterprise beans you
modified previously.
You may select to use a mix of the two approaches when making many
extensions to the object model. You can use the first approach for areas of the
system that are less susceptible to perform degradation and use the second
approach were performance is an issue. In this manner, you can minimize effort
for future migration, while still maintaining good system performance levels.
As a general tip, the choice of extending or modifying WebSphere Commerce
Suite code may:
Require additional operations to maintain code in order to use future releases
Increase object model complexity
Therefore we recommend that you create new EJBs whenever possible.
For more detailed information on EJBs and customization of object models, refer
to:
WebSphere Commerce Suite V5.1 Customization and Transition Guide,
SG24-6174
Product documentation, available online at:
http://www.ibm.com/software/webservers/commerce/library.html/
8.3.5 XML data files
XML provides an open industry-standard means of describing the WebSphere
Commerce Suite system parameters and product catalog.
XML forms a vital component in architectures that use the Java 2 Platform,
Enterprise Edition (J2EE). It is the defined standard for asynchronous messaging
and information interchange within the platform and is used by other components
such as Enterprise JavaBeans to define deployment and initialization
parameters. It is used throughout WebSphere Commerce Suite, from store
parameter definitions to catalog creation and description.
Note: In order to make this migration simpler and as a general tip, it is
important to fully document your object model extensions at development
time.

Chapter 8. Application development guidelines
195
XML for store assets creation
The store archive file (SAR) contains all the data assets needed to publish a
store. This data is contained in several XML files that you need to modify if you
want to customize your store for publishing.
For example, the following catalog assets are contained in file catalog.xml:
Catalog entity
Catalog groups
Relationships between catalog groups
Products and items
Attributes and attribute values
List prices
Relationships between catalog groups and products
Relationships between products and items
All this information can be modified.
If you modify your XML data files, you will have the store already configured
when published, but you can also publish a standard store (WebFashion) and
modify it later.
XML for WebSphere Application Server configuration
WebSphere Application Server provides the XMLConfig tool that can be used to
deploy enterprise beans. This is a command-line utility that uses an XML file as
input. The XML file specifies the enterprise beans to be deployed.
A sample XML file is provided with Commerce Suite. This file,
was.customizable.EJB.xml, contains all of the deployment information for the
Commerce Suite public enterprise beans. If you are deploying modified
Commerce Suite public enterprise beans, you must change the name of the
deployed JAR file within the XML file to match your JAR file name and change
the following values to match your configuration:
DRIVER_NODE_NAME
DRIVER_INSTANCE_NAME
DRIVER_INSTALL_PATH
Tip: We recommend that you use an XML editing tool to modify your XML files
(XMLSpy, IBM XMLTools, etc.) to verify well-formedness and validity.

196
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
If you have created new enterprise beans, use the was.customizable.EJB.xml file
as a model for creating the deployment information for your new beans.
For more detailed information on XMLConfig tool and XML files please refer to:
WebSphere Commerce Suite V5.1 Customization and Transition Guide,
SG24-6174
Product documentation, available online at:
http://www.ibm.com/software/webservers/commerce/library.html/
8.3.6 SQL scripts
WebSphere Commerce Suite requires the use of many SQL scripts to implement
and manage a WebSphere Commerce Suite store and database.
SQL scripts can be used as follows:
To register new commands
To manage data (modify, load)
To customize the data model
Registering commands
Once your code is written to make WebSphere Commerce Suite or WebSphere
Test Environment use it, you have to update the command registry, which is in
the URLREG, CMDREG and VIEWREG tables.
If you want to register a new URL, you have to modify the URLREG table
referring to the logon process. If you have created a new interface called
com.myco.commerce.security.LogonCmd, you should follow Example 8-7.
Example 8-7 Registering a new URL in the URLREG table
insert into URLREG
( URL, STOREENT_ID, INTERFACENAME, HTTPS, DESCRIPTION, AUTHENTICATED)
values
('MyCoLogon', 10001, 'com.myco.commerce.security.LogonCmd', 0, 'MYCO
customization',
null)
Note: When retrieving an interface name for a URL, WebSphere Commerce
Suite will look first for a store-specific URL (with the STOREENT_ID column
valued to a particular store_id). If the query is unsuccessful, it will use the
general URL (with STOREENT_ID=0). We recommend that you value the
STOREENT_ID field.

Chapter 8. Application development guidelines
197
To register a new implementation of a command (controller or task) you have to
act on the CMDREG table (Example 8-8 shows how to modify the CMDREG
table to make WebSphere Commerce Suite use your custom implementation of
the command (com.myco.commerce.security.commands.LogonCmdImpl).
Example 8-8 modifying the command registry
insert into CMDREG (storeent_id, interfacename, classname, target) values
(10001,'com.ibm.commerce.security.commands.LogonCmd','com.myco.commerce.securit
y.commands.LogonCmdImpl','Local')
Managing data
The most important operation on a database is loading data. There are three
approaches:
Load: in this option, data is loaded into the database; if the data already
exists, it is deleted and replaced with new data. Consider this option in the
following situations:
– If you know the data is clean, and if the database does not contain any
data
– If you know the data is clean, and if you know the database does not
contain the data that is being loaded
– If you know the data is clean, if the targeted tables do not contain any
primary keys, and if you know the database does not contain the data that
is being loaded
– If the load time is your primary concern
– If the database is local
For more information on loading catalog data, please refer to Chapter 12,
“Catalog management” on page 303.
Import: in the import option for DB2, data is also loaded into the database; if
the data already exists, it is not deleted but is updated with new values.
Note: In the CMDREG table as for URLs, WebSphere Commerce Suite first
looks for store-specific implementation, and then for generic. Moreover, if no
implementation class is found then it will use the classname taken from the
field of the command interface defaultCommandClassName. So if you create a
new interface and value the field defaultCommandClassName with the name
of your implementation class, you don’t need to update the CMDREG table.
Note: The data must not exist in the database, or you risk losing data.

198
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Import is the default method for the Load command. Consider this option in
these situations:
– If you do not know whether the data is clean
– If the data already exists in the database
– If you have to update large sets of homogenous data at a column level
– If the load time is not your primary concern
– If the database is local
SQL import feature: in the SQL import option, JDBC or SQL statements are
used to update or insert data into the database. Data is inserted if it does not
already exist, and existing data is updated. Consider this option in the
following situations:
– If you are updating existing data and require column-level updates
(heterogeneous, data in different columns)
– If you know some of the data is not clean
– If database integrity is your primary concern
– If the database is not local
When analyzing the alternatives, consider also these features:
The import option checks for data consistency, including foreign references,
while the load option does not.
The import option uses native utilities that are optimized for DB2, while the
SQL import option uses JDBC calls, which are generic to many database
products.
The Loader invokes the native utilities using the Runtime.exec() method.
There are no Java APIs for invoking the load and import processes.
Import and SQL import perform similar functions, but SQL import may be
used for remote databases. The import option is typically faster but requires
disk space for temporary files.
For more detailed informations on databases and data loads, please refer to:
WebSphere Commerce Suite V5.1 Customization and Transition Guide,
SG24-6174
WebSphere Commerce Suite online help
Creating new tables
You may need to extend WebSphere Commerce Suite data model adding new
tables. In this case follow the naming conventions in “Naming conventions” on
page 170 to avoid any conflict with standard tables.

Chapter 8. Application development guidelines
199
The scripts used to create custom tables cannot be packaged in the SAR file,
therefore it is important to store them to have ‘ready for deployment’ assets.
8.3.7 Where to start?
The recommended approach for commerce application development using
WebSphere Commerce Suite is the Model-View-Controller (MVC) pattern.
The Model-View-Controller pattern separates display logic (in WebSphere
Commerce Suite, this is handled by JavaServer Pages) from the underlying
business logic and data model. The component parts of the
Model-View-Controller pattern are implemented as shown in Figure 8-8. This
separation of business logic from the user interface allows you greater flexibility
in your application. If your user interface (the Web pages) must change in look
and feel, then the other segments of the application need not be heavily affected,
if at all.
Figure 8-8 Model-View-Controller pattern
Note: Always create tables with an internal primary key. If you do not, you
could experience problems when creating the schema map for the Entity bean
within VisualAge for Java.
Web
controller
Controller
URL
Controller
command
View
command
WCS
Database
Entity bean
View
Model
Access
bean
Task
command
Task
command
JSPtemplate
Data bean
invokes
invokes
R/W
invokes
invokes
invokes
invokes

200
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Also, the very fact that you can split your application into fairly distinct sections,
each requiring different skills, allows you to better manage your development
cycle and team.
Moreover, WebSphere Commerce Suite is organized in subsystems (member,
order, catalog, etc.) and this allows you to separate tasks once more.
Using this approach it is possible to have concurrent development on each
subsystem and on different parts of the Model- View-Controller pattern.
Table 8-4 shows how the WebSphere Commerce Suite structure can be divided
by function and role. This classification tries to divide the customization of a
WebSphere Commerce Suite site into small tasks. You probably will not need all
this fragmentation and it is possible to have a lot of overlapping, but this could be
a starting point.
Table 8-4 Work fragmentation
SUBSYSTEM Topic User Interface
(stylesheets,
images, HTML,
WML)
Business logic
(commands, data
beans, JSPs)
Data (EJBs,
access beans)
MEMBER Login, SSL, LDAP,
SSO, session
management
Interface with
external tools and
customization of
commands and
JSPs
MEMBER Membergroups Development of
commands and
JSPs
New tables and
EJBs
MEMBER Personalizations
(WebSphere
Personalization,
Macromedia
LikeMinds, Blaze
Advisor)
front-end,
communication,
usability
Implementation of
features of
personalization
tools
Possible new
tables and EJBs
ORDER Order submission front-end,
communication,
usability
Development of
commands and
JSPs
New tables and
EJBs for
additional order
data
ORDER Order status front-end,
communication,
usability
Development of
commands and
JSPs
New tables and
EJBs for
additional order
data

Chapter 8. Application development guidelines
201
We classified the core JSP development as part of the command development.
The style part of the JSP development is grouped with the user interface Web
designer role.
ORDER Order back-end
processing
(MQSeries)
Implementation of
back-end process
ORDER Payments Implementation of
back-end process
ORDER Prices and
discounts
Development of
commands
New tables and
EJBs for price
customization
NEGOTIATION Auctions Front-end,
communication,
usability
Development of
commands and
JSPs
New tables and
EJBs
CATALOG Catalog display Front-end,
communication,
usability, style
Development of
commands and
JSPs
New tables and
EJBs for
additional product
data
CATALOG Catalog search Front-end,
communication,
usability, features
of the search
interface
Development of
features of search
engine
New tables and
EJBs or indexes
for search engine
CATALOG System
administration
Customization of
features of
administration
tools
CATALOG Multicultural
support
multicultural
interface,
communication
and style
Multicultural
support of JSPs
SUBSYSTEM Topic User Interface
(stylesheets,
images, HTML,
WML)
Business logic
(commands, data
beans, JSPs)
Data (EJBs,
access beans)

202
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
203
Chapter 9.
Systems management and
security guidelines
In this chapter we focus on the activities involved with systems management and
security for WebSphere Commerce Suite V5.1.
This chapter is organized into the following sections:
Systems management guidelines overview
System management tools
Security guidelines
Backup and recovery guidelines
9

204
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
9.1 Systems management guidelines overview
Once the application has been deployed in the production runtime environment,
the application needs to be managed. As part of the development process, a
systems management plan is created early in the planning cycle. We have
categorized a set of post-implementation systems management activities as
follows:
Application management
Performance monitoring
Availability management
Security management
Disaster recovery
Operating system and network administration
Asset management
Software distribution
Problem reporting
Change management
Looking at this list of activities, systems management is certainly not trivial. In
fact, each of these activities requires highly specific skills and professional
experience to perform them competently. Besides the skills factor, you will also
have to decide on a set of tools to manage the system management activities.
Beyond the technical challenge of systems management, there is also the added
pressure from management. In many situations, you will be bound by service
level agreements (SLAs). Such agreements typically cover system availability
hours, system utilization and problem resolution response time.
These measurements will be collected, tabulated, and reviewed on a regular
basis by management, to ensure accountability and a well-maintained system.
Thus, you will also require reporting tools to facilitate the SLA review. With all of
the management focus and targets to meet, it makes systems management
more daunting and challenging. Since it is important, it is our recommendation
that you start planning early. Incorporate system management requirements in
the early phases of your design, since the design will affect how you eventually
manage it. Conversely, what tools are available to manage your system also
affect your application design.
A detailed discussion of each topic is beyond the scope of this redbook. What we
will focus on are the key system management activities related to the B2C
e-commerce composite pattern using WebSphere Commerce Suite V5.1.

Chapter 9. Systems management and security guidelines
205
9.1.1 Managing your WebSphere Commerce Site
In the example seen in Figure 9-1, the network is divided into three segments: an
internal (or secure) network, a DMZ, and the public (or external) network. All
external user access will have to flow through the external (or protocol) firewall to
gain access to the WebSphere Commerce Server in the DMZ. Depending on the
type of user request, the WebSphere Commerce Server may forward the request
through the internal (or domain) firewall to the database server in the internal
network. The application server will process the request and send any response
back to the external customer through the protocol and domain firewalls.
Figure 9-1 Managing WebSphere resources
The WebSphere Commerce Suite application is a combination of HTML pages,
JSPs, servlets, EJBs and database resources. These resources will be deployed
and managed in the WebSphere Application Server and WebSphere Commerce
Server environment. In our scenario shown in Figure 9-1, the WebSphere
Application Server and the WebSphere Commerce Server will host JSPs,
servlets and EJBs. In the following discussion, we will refer to the
WebSphere-specific terms in Table 9-1.
Table 9-1 Description of WebSphere terms
WebSphere terms Description
Web resources Refers to servlets, JSPs, and HTML
pages.
Web application Application consisting of Web resources.
Enterprise application Application consisting of Web applications
and EJBs.
Application server A JVM runtime service that handles user
requests from Web applications.
Web
Browser
External
Firewall
Web
Browser
Internal
Firewall
WebSphere
Commerce
Server
DB2
Database
Server
Internal
Workstations
Public Network Demilitarized Zone (DMZ) Internal Network
Web
Server

206
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
9.1.2 WebSphere resource management
WebSphere resources use core underlying services such as the servlet engine,
EJB engines, security application, and cluster models residing in the application
server. These services manage the Web resources and applications that are
hosted by the WebSphere Commerce Server and the WebSphere Application
Server. Depending on application requirements, a stand-alone application server
or multiple application servers with failover support capability can be used. The
WebSphere Application Server Administrative Console is used to manage,
deploy, and configure the WebSphere resources. The WebSphere Commerce
Suite Administrator provides system management capability to the Site Manager
and Store Manager.
For more information, refer to the following Redbooks and product guides:
Application Server Solution Guide, Enterprise Edition: Getting Started,
SG24-5320
Patterns for e-business: User-to-Business Patterns for Topology 1 and 2 using
WebSphere Advanced Edition, SG24-5864
WebSphere V3.5 Handbook, Using WebSphere Application Server V3.5
Standard and Advanced Editions, SG24-6161
Fundamentals, IBM WebSphere Commerce Suite V5.1 product guide
Site Administrator, IBM WebSphere Commerce Suite V5.1 product guide
9.2 System management tools
This section provides information on all the tools used to fulfill the systems
management responsibilities, with the following objectives:
What are the tools used to manage a WebSphere Commerce Suite
environment?
How do you launch them?
What are they used for?
Where can you find more information?
9.2.1 WebSphere Application Server Administrator’s Console
The WebSphere Application Server Administrator’s Console is the graphical user
interface used to manage, deploy and configure the WebSphere resources of a
WebSphere Administrative Domain.

Chapter 9. Systems management and security guidelines
207
Administrative tasks
This section discusses the general administrative tasks for the WebSphere
Application Server.
Configuring applications and their components
The WebSphere Application Server provides support for servlets, beans, EJBs,
JSPs, and Web pages that work together to perform a particular business logic
function to create an enterprise application. After configuring an application, the
Administrative Console can be used to start and stop the application as a logical
unit. For example, when the application is started, all of the application
components such as servlets, enterprise beans, etc. are started.
Controlling access to applications (security)
After configuring applications, we will likely want to limit access to them. For
example, the public should not be permitted to use an application that accesses
a database containing sensitive company information. The WebSphere
Application Server can establish and enforce authentication, authorization, and
delegation policies to control access to the applications.
Day-to-day administration activities include the following:
Ensuring that resources are available (running)
Starting and stopping servers and servlets as necessary
Making incremental adjustments to the configurations of resources in the
administrative domain
Modifications can be small, such as granting permissions to access a new
application, reinstalling an enterprise bean after changing a JAR file, or changing
the frequency with which servers are queried to determine their state.
Large-scale modifications can include introducing new resources into the domain
or redefining the mix of resources in an application.
Analyzing usage statistics and performance
Resource analysis tools can be used to review current and historical information
about resources in the domain. You can monitor performance and load statistics
for servlets, enterprise beans, sessions, database connection pools, and server
resources.
Optimizing performance
Resources in an administrative domain can be cloned to improve performance or
availability. For example, application servers can be cloned to form a server
group (a collection of identical instances of application server processes).

208
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Cloning application servers improves the throughput of client remote-method
invocations by distributing the load among the members of the group. It also
improves availability and can prevent a single point of failure.
Cloning can be used to simplify configuration tasks. For example, you can
configure a resource, test the configuration, and then duplicate the resource for
use on other nodes in the domain.
Troubleshooting
Troubleshooting includes the following:
Monitor transactions, forcing outcomes when necessary
Analyze resources such as servlets and enterprise beans
Trace and debug applications
View traces, logs, and messages
Administrative terminology
The WebSphere Application Server provides administrators with a single-system
view of applications and resources, such as servlets, that are typically deployed
across multiple machines in a distributed environment. An administrator working
on one physical machine can remotely administer resources located on another
physical machine.
In the WebSphere administrative model:
Node
A physical machine is called a node.
Administrative server
Each node contains an administrative server for administering the resources
on it.
Administrative repository
Each administrative server stores its administrative data in an administrative
repository, typically a DB2 database. The person installing IBM WebSphere
Application Server specifies which administrative repository a given
administrative server will use.
Administrative domain
An WebSphere Administrative Domain is a set of one or more nodes called
WebSphere administrative servers that share a common administrative
repository. The administrative domain allows the nodes to be aware of one
another and distribute applications among themselves.

Chapter 9. Systems management and security guidelines
209
Topology
Each administrative domain has its own topology, comprised of the nodes in the
administrative domain and the resources those nodes contain.
Administrative resources
The resources on a node, such as servlets, class files, and enterprise bean JAR
files, are represented as administrative resources in the administrative domain.
An administrative resource, such as a servlet, holds configuration information
about a resource, such as servlets installed on a node. It provides a way to start,
stop, and otherwise manage the real resource, perhaps remotely.
Containment hierarchy
The topology reveals the containment hierarchy, which is simply a tree illustrating
how the administrative resources in the topology are related. The hierarchy
shows which resources are parents or children of other resources. The Types tab
of the WebSphere Administrative Console demonstrates the containment
hierarchy.
Console menu
The WebSphere Administrator’s Console allows you to turn on tracing for
problem determination, import and export files, view command history, and exit
the Administrator’s Console. There are three levels of tracing available: FATALS,
WARNINGS and AUDIT. The console also can clear the old trace messages.
WebSphere Administrator’s Console
The WebSphere Administrator’s Console enables administrators to access the
administrative server on each node in the administrative domain and provides a
view of the domain's topology. It supplies task wizards for managing and
combining resources in the topology.
Starting the Administrator’s Console
The WebSphere Administrative Server must be running before you start the
WebSphere Administrator’s Console.
Start the administrative server (or ensure that it is already running)
To start and stop the administrative server, click Start -> Settings -> Control
Panel, then double-click Services. When the Service window pops up, select
the service named IBM WS AdminServer and click the Start or Stop button
as required.
Start the Administrator’s Console:
From the Windows Start menu, click Programs -> IBM WebSphere ->
Application Server 3.5 -> Administrator’s Console.
To stop the Administrative Console, click Console -> Exit from the
Administrative Console.

210
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Tracing
In the Administrator’s Console click Console ->Trace -> Enabled. It is a
toggle. When set, a check mark will appears next to the Enabled menu item.
By reselecting Console ->Trace -> Enabled, the Enabled option disables
Trace.
Trace Settings
In the Administrator’s Console click Console ->Trace -> Trace Settings. The
Trace Setting window will pop up. Insert the class for which you want to
collect trace information and then click Apply.
Event View
To bring up the Event Viewer, click Console ->Trace -> Event Viewer in the
Administrator’s Console.
To clear old messages, click the Preferences tab in the Event Viewer window
and click the Clear button and then the Apply button.
To set the trace levels, click the Preferences tab in the Event Viewer window
and check the levels (FATALS, WARNINGS, AUDIT) as required and click
Apply.
Refresh
In some instances the changes to the administrative domain are not promptly
reflected in the console, especially in the Topology view. When that happens,
click the Refresh icon.
A refresh can be done at any time and at any level of the tree. The selected
subtree is typically refreshed. Watch for the refresh completion message in the
console messages area.
Backup configuration
Administrators can use Export function to back up the WebSphere production
configurations. WebSphere Application Server Administrator’s Console uses an
XML file for export or import configuration.
To export, from the main menu click Console -> Export.
Choose the directory or folder where you want the file saved. Type in the file
name. By default there is no extension given to the file name. The
recommendation is to use a .xml extension.
Click the Save button.
Restore configuration
Administrators can use the Import function to restore or replicate the WebSphere
production configurations.

Chapter 9. Systems management and security guidelines
211
To import, from the main menu click Console -> Import.
In the Open window, select the directory or folder and choose the XML file
containing a WebSphere configuration that you want to import.
Watch the Console messages window for the status of the import. Some of
the warnings, like those shown in Example 9-1, can be benign.
Example 9-1 Console messages for import configuration
8/15/01 9:58 AM : *m23caaax.import* running ....
8/15/01 10:00 AM : WARNIBG [m23caaax/_adminServer]: Encountered an exception:
com.ibm.ejs.sm.exception.DuplicateRelationInstanceException
8/15/01 10:00 AM : WARNIBG [m23caaax/_adminServer]: Encountered an exception:
com.ibm.ejs.sm.exception.DuplicateRelationInstanceException
8/15/01 10:00 AM : WARNIBG [m23caaax/_adminServer]: Encountered an exception:
com.ibm.ejs.sm.exception.DuplicateRelationInstanceException
8/15/01 10:00 AM : WARNIBG [m23caaax/_adminServer]: Encountered an exception:
com.ibm.ejs.sm.exception.DuplicateRelationInstanceException
8/15/01 10:00 AM : WARNIBG [m23caaax/_adminServer]: Encountered an exception:
com.ibm.ejs.sm.exception.DuplicateRelationInstanceException
8/15/01 10:00 AM : Command *m23caaax.import* completed successfully.
9.2.2 WebSphere Commerce Suite
WebSphere Commerce Suite provides several utilities to help manage your
commerce suite, as follows:
Configuration Manager
Administration Console
Store Services
Commerce Suite Accelerator
Configuration Manager
The WebSphere Commerce Suite Configuration Manager is a Java
application-based tool used to create and configure a WebSphere Commerce
Suite instance. The Configuration Manager (client) has a corresponding server,
called the Configuration Manager Server, which must be started to use the
Configuration Manager.

212
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
The Configuration Manager provides configuration tabs to enter information on
instances, WebSphere Application Server, Web server, Payment Manager,
messaging, and session management. The information entered in the
Configuration Manager is stored in the WebSphere Commerce Suite instance
XML configuration file, and the WebSphere Application Server repository
database.
Logging Service
WebSphere Commerce Suite's logging service notifies site or store
administrators when unexpected errors or abnormal conditions occur in the
Commerce Suite application. When such conditions or errors develop, the
information is captured into a file and a message is created to notify the user.
There are two types of logs found in the WebSphere Commerce Server:
diagnostic and activity. Diagnostic logs are used for problem determination and
are stored in log files. Activity logs record events that are stored in the
Commerce Suite database.
Logging service includes the following components:
Trace log
Tracing log is used for problem determination. Tracing assists store
developers in debugging the code during the developing stage and assists
the technical support team in solving customer problems.
Tracing data is filtered according to the component. You can enable certain
components for tracing. To enable or disable a trace log, you have to edit the
WebSphere Commerce Suite configuration file, which can be found at:
<wcs_install_path>\instances\<instanceName>\xml\<instanceName>.xml
Example 9-2 Code segment for tracing log enable or disable
<LogSystem>
<trace
traceFile="<wcs_install_path>\instances\<instanceName>\logs\ectrc.log"
fileSize="20" enable="true">
<component name="SERVER" />
<component name="CATALOG" />
<component name="DATASOURCE" />
<component name="USER" />
</trace>
</LogSystem>

Chapter 9. Systems management and security guidelines
213
In Example 9-2, the traced components are located under the component
name XML element. The enable attribute of the XML element affects the
status of the trace log. To collect trace log data, the enable attribute must be
set to true and to deactivate trace at load-time, set the enable attribute to
false.
The fileSize attribute specifies the maximum file size in MB for the log file. If
the actual file size exceeds the specified amount, a new file opens in which
traceFile provides the base name of the file.
File names are created based on the following naming convention:
<file name>_<clone ID>_<time stamp>.<ext>
For example, the ectrc.log file will produce system files with names such as:
ectrc_m23caaax_2000.08.08_18.17.47.768.log,
where m23caaax is the clone ID and the embedded timestamp is a variable
factor.
Message log
Commerce Suite logging messages are classified as user or system
messages.
User messages are displayed in the user's Web browser. These messages
inform the user about the state of the application, such as System
unavailable, or respond to customer input, such as Invalid credit card
number. A user message is generated as well as a result of invalid user input
and informs the user of the cause and possible recovery actions.
System messages provide diagnostic information for site administrators,
customer service representatives, and store developers. System messages
are generated from system malfunctions that obstruct the completion of a
user request. The messages are saved in log files for later reference.
Messages are filtered based upon their severity. To enable or disable a
message log you have to edit WebSphere Commerce Suite configuration file,
which can be found at:
<wcs_install_path>\instances\<instanceName>\xml\<instanceName>.xml
Example 9-3 Code segment for messaging log enable or disable
<LogSystem>
<messageLog
messageFile="<wcs_install_path>\instances\<instanceName>\logs\ecmsg.log"
fileSize="20"
enable="true"
notification="false">
<logSeverity type="ERROR" />
<logSeverity type="WARNING" />
<logSeverity type="STATUS" />

214
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
<logSeverity type="DEBUG" />
<logSeverity type="INFO" />
</messageLog>
</LogSystem>
In Example 9-3, the enable attribute of the XML element affects the status of
the message log. To collect message log data, the enable attribute must be
set to true. The fileSize attribute specifies the maximum file size in MB for the
log file. If the actual file size exceeds the specified amount, a new file opens.
The file names are created based on the following naming convention:
<fileName>_<cloneId>_<timeStamp>.<ext>.
For example, the ecmsg.log file will produce system files with names such as:
ecmsg_m23caaax_2000.08.08_18.17.47.768.log,
where wcsinst1 is the clone ID and the embedded timestamp is a variable
factor.
Message and trace data can be captured into the same file. The fileSize
attribute must also have the same value. The XML configuration file should
point to the same location.
User traffic activity log
User traffic activity logs record events and activities occurring at the site level.
The data is stored in the USRTRAFFIC database table. An activity is
represented by a set of logically related data. From the database perspective,
an activity represents a row in a specific table.
There are two types of activity:
– User activity, which is the data related to a user accessing the Commerce
Suite application, such as logging date and time, or the client's IP address.
– Marketing activity, which is generated by Commerce Suite in response to
user activity, such as browsing a store.
To enable or disable a user traffic activity log, you have to edit the WebSphere
Commerce Suite configuration file, which can be found at:
<wcs_install_path>\instances\<instanceName>\xml\<instanceName>.xml
Example 9-4 Code segment for user traffic active log enable or disable
<Components>
<component
compClassName="com.ibm.commerce.event.usertraffic.UserTrafficEventListener"
enable="true"
name="UserTrafficEventListener">
<property display="false">
<start enabled="true" />

Chapter 9. Systems management and security guidelines
215
</property>
</component>
</Components>
In Example 9-4, the enable attribute of the XML element affects the status of
UserTraffic activity. If the attribute is true, the component framework will
create the UserTrafficEventListener, and will pass the values contained within
the property element. To collect user traffic data, the start enabled attribute
must be set to true.
To configure logging for your Commerce Suite system, use the Log System panel
of the Configuration Manager which is under WebSphere Commerce Suite
instance. The log system panel has a two tab:
General tab
From the General tab you can set the trace file location, trace file size,
message file location, message file size, activity log cache size, and
notification enabled.
Advanced
From the Advanced tab you can select the components for which you want
errors recorded in the trace file (for example, server, transport adapter, order,
etc.). You can also select the level of errors that you want reported in the log
file. There are five levels of error: error, warning, status, debug, and
information.
For detailed information on creating a WebSphere Commerce Suite instance
using the Configuration Manager, refer to the WebSphere Commerce Suite V5.1
Handbook, SG24-6167 and for detailed information on WebSphere Commerce
Suite logging service, refer to the online documentation for IBM
WebSphereCommerce Suite 5.1.
Administration Console
The WebSphere Commerce Suite Administration Console is a Web browser
accessible tool that allows you to maintain your online stores by completing
administrative operations. When you log on to the Administrator Console, you
select the store and language with which you want to work, if you are authorized
to work with multiple stores and languages. The tasks that you are authorized to
perform are displayed on the Administration Console home page through various
menus. These tasks are based on the user roles and authority levels.
Note: By default, the user traffic log in WebSphere Commerce Suite is not
enabled.

216
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
The following list outlines what tasks can be performed by each role:
Site Administrator
– Manage administrators and access groups
– Restrict customer commands from stores
– Define transports and message types for the site
– Monitor performance of the site
– Specify Payment Manager settings
Store Administrator
– Configure messages
– Administer Blaze Rules
This tool is used after the store has been published from Store Services. To start
Store Services, enter the following URL in the Internet Explorer V5.5 browser:
http://<hostname>/adminconsole
Store Services
The WebSphere Commerce Suite Store Services Web browser accessible tool
allows you to quickly create a store archive based on a sample store. Once the
store archive has been created, Store Services can be used to perform the
following tasks:
– Publish (deploy) the store to the WebSphere Commerce Suite runtime
environment
– Change tax settings using the Tax notebook
– Change shipping settings using the Shipping notebook
– Change general store information using the Store Profile notebook
Once a WebSphere Commerce Suite instance has been created, Store Services
may be used. To start Store Services, enter the following URL in the Internet
Explorer V5.5 browser:
http://<hostname>/storeservices
For detailed information on using Store Services, refer to the WebSphere
Commerce Suite V5.1 Handbook, SG24-6167.

Chapter 9. Systems management and security guidelines
217
Commerce Suite Accelerator
The WebSphere Commerce Suite Accelerator is a Web browser accessible tool
that allows you to maintain your online stores by completing various store
operations. If you are authorized to work with multiple stores, when you log on to
the Commerce Suite Accelerator you select the store and language with which
you want to work. If you are authorized to work with a single store, the store
name is pre-selected during logon, and if the store supports more than one
language, you select the language with which you want to work.
Tasks that you are authorized to perform in your role are displayed on the
Commerce Suite Accelerator home page menus. These tasks are based on
access groups and authority levels, which are defined by the Site Administrator
by using the Administration Console. Table 9-2 outlines the available menus in
the Accelerator (WebSphere Commerce Suite V5.1, Pro Edition), who has
access to the menus, and what tasks can be performed using the menus.
Table 9-2 Commerce Suite Accelerator tasks based on access group
Menu
name
Access
group Task
Store Merchant
Marketing mgr
Merchandising
mgr
Manage business intelligence reports
Marketing Marketing mgr
Merchandising
mgr
Merchant
Manage customer profiles:
List customer profiles
Create, change, delete, and duplicate
profiles

Vie
w a summary of each profile
Manage campaigns:
List campaigns
Create, change, and delete campaigns
Publish campaigns
List campaign initiatives
Manage campaign initiatives:
Create, change, and delete campaigns
initiatives
Publish campaigns
View campaigns incentive statistics
Create, change, and remove campaigns
incentive conditions

218
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Merchandise Merchandising
mgr
Merchant
Manage products:
Find and list products
Change product details
List offers assigned to products
Change offer details
Manage auctions:
Find and list auctions
Create, change, and retract auctions
Close the bidding for auctions
List and withdraw bids
List discussion forums
Create and delete discussion messages
Respond to discussion messages
Make discussion messages public
List bid control rules
Create, change, and delete bid rules
List auction styles
Create, change, and delete auction styles
Manage discounts:
List discounts
Create and delete discounts
View a summary of each discount
Activate and deactivate discounts
View Product Advisor statistics
Customer
Orders
Order clerk
Merchant
Fulfill and process customer orders:
Find and list customer orders
View a summary of each order
Change the status of orders
Process payment
Add comments to orders
Access Payment Manager
Menu
name
Access
group Task

Chapter 9. Systems management and security guidelines
219
The WebSphere Commerce Suite Accelerator can be started by entering the
following URL in a Microsoft Internet Explorer V5.5 Web browser:
http://<hostname>/accelerator
9.2.3 WebSphere Commerce Analyzer
WebSphere Commerce Analyzer is an optional application included with the
WebSphere Commerce Suite, V5.1 Pro Edition. If installed, it provides a robust
business intelligence solution designed to analyze and report on the activities of
your customers.
Customer
Service
Customer service
representative
Merchant
Manage customer information:
Find and list customers
Change customer registration
information, including passwords
Manage orders for customers:
Find and list orders for customers
Place orders for customers
View a customer's order history
View a summary of each order
Change order details
Add comments to orders
Cancel orders
Manage auctions for customers:
Find and list auctions
Manage discussion forums, such as
creating and responding to discussion
messages, and making messages public
Withdraw bids for customers
Note: Once you have completed the tasks for a store, you should log out of
the Commerce Suite Accelerator rather than simply closing the browser.
When you log out, your SSL cookie is dropped and you no longer have secure
access to the Commerce Suite Accelerator. This is especially important if the
Commerce Suite Accelerator will be used by multiple users on a single
machine with different authorities. Logging out prevents unauthorized access.
Menu
name
Access
group Task

220
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
WebSphere Commerce Analyzer automatically extracts data from the production
database on a regular basis. It then processes logs and numerous database
records to compile reports based on customer traffic and site usage. These
reports, accessible from the Commerce Suite Accelerator, demonstrate
comparable success rates of your marketing campaigns, as well as demographic
distributions of your customers. These reports provide feedback that can be used
to evaluate recent campaigns and to initiate change for upcoming campaigns.
This completes the marketing campaign life cycle.
The data extraction schedule is fully configurable. A typical schedule would be to
run the data extraction process on a daily basis in order to minimize the amount
of data that is extracted during each run. WebSphere Commerce Analyzer is
typically located on a remote dedicated machine to reduce any performance
effects on the production machine.
When creating your next campaign it will be worthwhile to look at past campaigns
in order to fine-tune your strategy. Commerce Analyzer can help you achieve this
by providing feedback on:
Campaigns, initiatives and e-marketing spot
– What was displayed and clicked by customers?
– Did it lead to a sale or did the customer change his mind after putting it in
the basket?
Sales and customers
– Analyze sales by time period, geographic and demographic units
– Look at what products were the most popular/least popular
– Which products were looked at the most but not bought.
The data for the above reports is extracted from the WebSphere Commerce
Suite database and parsed into the WebSphere Commerce Analyzer Datamart.
After the extraction process runs, WebSphere Commerce Analyzer generates
the business reports. It can then be viewed or print from the Commerce
Accelerator tool.
Figure 9-2 shows the relationship between the components of WebSphere
Commerce Suite and WebSphere Commerce Analyzer.
Note: WebSphere Commerce Analyzer is available only for the Window NT
and Windows 2000 platform.

Chapter 9. Systems management and security guidelines
221
Figure 9-2 Commerce Suite and Commerce Analyzer components
For more information about business reports that are generated by WebSphere
Commerce Analyzer 5.1, refer to the IBM WebSphere Commerce Analyzer
User’s Guide, found on the WebSphere Commerce Analyzer product CD.
For more information about installing, configuring, and administering WebSphere
Commerce Analyzer, refer to 17.3, “Reporting” on page 518 or to the IBM
WebSphere Commerce Analyzer Installation and Configuration Guide, found on
the WebSphere Commerce Analyzer product CD.
Marketing
Manager
Customer
WebSphere
Commerce
Suite
WebSphere
Commerce
Analyzer
Server
Business
Reports
Reporting
Tools
Analytics
Logic
Marketing
Manager
Browser
Customer
Browser
Commerce
Accelerator
Database
Server
WebSphere
Commerce
Analyzer
Datamart
Restriction: WebSphere Commerce Analyzer provides information about one
store and support one language, one locale, and multiple currencies. Reports
cannot be customized.

222
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
9.2.4 SecureWay Directory management
The IBM SecureWay Directory Management Tool (DMT) provides a graphical
user interface that enables you to manage information stored in directory
servers.
The tool can be used for the following tasks:
– Connecting to one or more directory servers via SSL or nor-SSL
connections
– Displaying server properties and rebinding to the server
– Administering schema object classes and attributes
– Administering directory entries
– Administering directory entry ACLs
– Searching the directory tree
LDAP is a client/server protocol for accessing a directory service. It was initially
used as a front end to X.500, but can also be used with stand-alone and other
kinds of directory servers. LDAP can be used as a centralized information
repository to support information sharing among various clients.
For more information on SecureWay Directory integration with WebSphere
Commerce Suite, refer to the WebSphere Commerce Suite V5.1 Handbook,
SG24-6167.
9.2.5 HTTP Server Administration
The HTTP Administration Server greatly simplifies the once-manual task of
configuring your Web server. Once you select a server to configure, the
Administration Server prompts you for configuration values, which are written to
a configuration file when you click Submit.
9.2.6 DB2 UDB Management
The tools for administering DB2 are part of the Administration Client, a selectable
component with each of the DB2 Universal Database products. The
Administration Client is also available on a set of CD-ROMs that include the
Administration Clients for all the operating systems on which DB2 is available.
They allow you to install and use the Administration Client on any workstation. It
does not matter whether your database servers are local or remote, or what
operating system the database servers are running on. The tools enable you to
perform the same functions from a graphical user interface as you could from the

Chapter 9. Systems management and security guidelines
223
command line processor. These functions include the entering of DB2
commands, SQL statements, or system commands. With the tools, however, you
do not have to remember complex statements or commands and you get
additional assistance.
The following tools are available from the Control Center toolbar:
Control Center
The Control Center is the main DB2 graphical tool for administering your
database. From the Control Center, you get a clear overview of all the
systems and database objects that are cataloged locally.
Satellite Administration Center
The Satellite Administration Center allows you to administer DB2 Satellite
servers.
Command Center
The Command Center enables you to issue DB2 database commands, SQL
statements, and operating system commands, recall previous commands,and
scroll through access plans for SQL queries.
Script Center
The Script Center enables you to create, run, and schedule
operating-system-level commands, DB2 command scripts, and SQL
statement scripts.
Alert Center
The Alert Center notifies you when thresholds that you have set have been
exceeded or when a node in a multi-node environment is no longer
responding.
The Journal
The Journal allows you to view the status of jobs, reschedule jobs, and to
view the recovery history log and messages log.
Information Center
The Information Center gives you quick access to the information in the DB2
product manuals and sample programs and provides access to other sources
of DB2 information on the Web.
License Center
The License Center displays the status of your license as well as allows you
to configure your system for proper license monitoring.
Note: The Administration Client is an installation option.

224
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
For some functions that you can perform with the GUI tools, you are given the
option of using a wizard. Wizards are invoked from the pop-up menus in the
Control Center. They provide a greater level of help by prompting you
step-by-step on how to fill in the information necessary for the task you are doing
and even making calculations and recommendations based on information you
supply. Wizards are very useful if you are a new database administrator or
someone who only administers a database occasionally.
In DB2 Universal Database, the following wizards exist:
Backup Database
This asks you basic questions about the data in the database, the availability
of the database, and recoverability requirements. It then suggests a backup
plan, creates the job script, and schedules it. To invoke the Backup Database
Wizard, right-click the icon representing the database you want to back up
and select Backup -> Database using Wizard.
Create Database
This wizard allows you to create a database, assign storage, and select basic
performance options. To invoke the Create Database Wizard, select and
right-click the Databases icon in the Object Tree pane, and select Create ->
Database using Wizard.
Create Table
This wizard helps you to design columns using predefined column templates,
create a primary key for the table, and assign the table to one or more table
spaces. To invoke the wizard, select and right-click the Tables icon and select
Create -> Table using Wizard.
Create Table space
This wizard lets you create a new table space and set basic storage
performance options. To invoke it, select and right-click the Table Space icon
and select Create -> Table space using Wizard.
Index Wizard
Use the Index Wizard to determine which indexes to create or drop for a given
set of SQL statements. The recommendations are based on the workload that
you specify. To invoke the Index Wizard, select and right-click the Indexes
folder and select Create -> Index using Wizard.
Performance Configuration
This wizard helps you tune databases by requesting information about the
database, its data, and the purpose of the system. It then recommends new
configuration parameters for the database and instance and automatically
applies them if you wish. To invoke this wizard, select and right-click the icon
for a database and select Configure using Wizard.

Chapter 9. Systems management and security guidelines
225
Restore Database
This wizard walks you through the process of recovering a database. To
invoke the wizard, select and right-click the icon for a database and select
Restore -> Database using Wizard.
Configure Multi-site Update Wizard
This wizard lets you configure databases to enable applications to update
multiple sites simultaneously when it is important that the data at all the sites
must be consistent. To invoke this wizard, select and right-click an instance
and select Multisite Update -> Configure using Wizard.
Besides the graphical tools that you can invoke from the Control Center toolbar,
there are some additional GUI tools that are not invoked directly from the Control
Center toolbar.
Performance Monitor
Performance Monitor is a tool to monitor DB2 objects such as instances,
databases, tables, table spaces, and connections. You use this tool to detect
performance problems and tune databases for optimum performance. The
Performance Monitor is invoked as a selection on the pop-up menus in the
Control Center.
Event Monitor
Event Monitor is a tool that lets you analyze resource usage by recording the
state of the database at the time specific events occur. An Event Monitor is
created by typing db2emcrt on a DB2 command line.
Event Analyzer
Event Analyzer is a tool that allows you to analyze the data collected by the
Event Monitor. An Event Analyzer is invoked by typing db2evmon on a DB2
command line.
Visual Explain function
The Visual Explain function lets you view the access plan for SQL statements
as a graph so that you can tune your SQL queries for better performance.
Prior to Version 6, you used the Visual Explain tool to view the access plans.
Now, Visual Explain is no longer a separate tool; the function is available on
pop-up menus from various database objects in the Control Center, and also
from the Command Center.
Note: Wizards do not exist for the DB2 for OS/390 subsystem.

226
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
In addition to these tools, another useful tool for database administration that is
not part of the Control Center is the Client Configuration Assistant. The Client
Configuration Assistant is a tool that contains wizards to help users set up clients
to communicate with remote servers.
The task you can perform from the Control Center are as follows:
Manage database objects.
You can create, alter, and drop databases, table spaces, tables, views,
indexes, triggers, schemas. You can also manage users.
Manage data.
You can load, import, export, reorganize data, and gather statistics.
Schedule jobs.
Jobs may be pending, running or completed executions of scripts. You can
schedule jobs to start at particular times.
Perform preventive maintenance by backing up and restoring databases.
Monitor performance and perform troubleshooting.
Replicate data.
Configure and tune instances and databases.
Manage database connections, such as DB2 Connect servers and
subsystems.
Manage applications.
Analyze queries using Explain SQL to look at access plans.
Change the font used for displaying menus and text throughout the Control
Center.
You can change to another available font, and change the size of the font and
the color shown. The Control Center must be restarted for the changes to
take effect.
Launch other tools.
For example, you can launch the Satellite Administration Center or the
Command Center.
To see all the actions that you can perform on an object, simply select and
right-click the object from the Object Tree pane or the Contents pane. A pop-up
menu appears showing all the functions that you can perform on that type of
object; for example, if you select the tables folder, you can create a new table
with or without the help of a wizard, monitor the performance of tables, filter
which tables appear in the Contents pane, and so on. The functions you can
perform are different, depending on the object you select.

Chapter 9. Systems management and security guidelines
227
All these tools are described in greater detail in the online DB2 Administration
Guide.
9.3 Security guidelines
Once your application is running in production mode, you can expect a lot of user
access to the system. If we lived in a perfect world where all users were law
abiding, then we would not have to worry about security. Unfortunately, this is not
the case and your system will constantly face security threats, both external and
internal.
The Web site you have developed is only one component of the total security
system. The golden rule is that the security strength of your system is only as
strong as its weakest link. Thus, it is necessary to ensure that the other
components in the system are configured securely.
With this in mind, end-to-end security will consist of physical, operating system,
network and application security, as seen in Table 9-3.
Table 9-3 End-to-end security components
9.3.1 Physical systems security
Physical systems security is the foundation of the end-to-end security building
blocks. Access to the hardware has to be controlled and monitored proactively.
Anyone gaining unauthorized physical access to your servers could halt your
server, steal valuable information from your storage, plant viruses, install harmful
software, etc. All of these activities are disruptive to your operations and will
cause damage to your system. If the hardware is not secured properly, it will void
the other security measures taken.
Security type Description
Physical Control access to the hardware equipment
hosting your application.
OS Security at the operating system level.
Network Secure connectivity flow among external,
DMZ, and internal networks.
Application Configure WebSphere security.

228
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
9.3.2 Operating systems security
After securing your physical systems, the operating system (OS) must be
secured. As the OS grows richer in function and features, new bugs are
discovered or are waiting to be exploited (for example, a bug that allows a user
with non-privileged access to perform privileged operations).
At the operating system level, we recommend the following practices for
administering your system:
1.Keep yourself updated on new information security glitches.
There are public Web sites that provide detailed information about newly
discovered glitches. Fortunately, there is also a wealth of public information
available that provides temporary or permanent remedies for these glitches.
As an administrator, you need to be warned quickly about these loopholes
and to take immediate actions to rectify the problem. As a service to their
customers, most OS vendors provide updated information related to security
hacks. A good source of information is the CERT Web site
(http://www.cert.org). You can subscribe to their mailing lists to receive
regular updates and news flashes by e-mail.
2.Access privilege account needs
Your OS security policy will need to consider who has access to the privileged
accounts and determine the roles and level of responsibility each person has.
For example, you may want to separate the role of an OS administrator from
the application administrator.
3.Enforce good password policies
Many security hacks are the result of simple passwords. You will have to
enforce good password policies and practices for all accounts in your system,
whether they are privileged or non-privileged. Besides having this policy,
educate your users on their role in the overall system security. Another policy
that you could implement, at the OS level, is forcing the passwords to expire
or force them to change after some predefined period. Also you should not
allow reuse of passwords.
4.Enable logging and auditing
Remember to turn on OS system logging and auditing. In the event of a
system break-in, hopefully you will have some trails to start off your
investigation.

Chapter 9. Systems management and security guidelines
229
9.3.3 Network security
Once you have the physical hardware and the operating system secured, you
need to turn your attention to security between interconnected systems. Network
security involves protecting resources residing in your internal network and DMZ
from the external network. You need to restrict and prevent unauthorized user
access to your internal systems. At the same time, you do not want to make it
difficult for legitimate users to access your systems. The key technologies
available to achieve this network protection include firewalls, intrusion detection
monitors, and anti-virus detection. The IBM SecureWay suite of products provide
a comprehensive security solution that will meet most requirements. Information
about SecureWay products can be found at:
http://www.ibm.com/software/secureway/
WebSphere in a firewall environment
How do you restrict and control network access? You can use firewalls between
two networks. When properly configured, the firewall acts as a choke point and
will force all traffic of a specific protocol to and from the Internet to flow through it.
By doing so, it can then scan the traffic and determine whether to allow or
disallow the packets based on a set of rules.
When designing your firewall configuration we recommend the following:
1.Make sure that there is no direct communication channel between the
applications on the intranet and the external Internet. In the example in
Figure 9-1 on page 205, all external user requests and application responses
flow through the Web server residing in the DMZ. If necessary, WebSphere
Commerce Server will forward the request to the DB2 server in the internal
network.
2.Keep it short and simple. Reuse pre-configured rules that exist. Define new
rules if necessary. Always remember to include a rule that excludes
everything else.
3.You should not allow information pertaining to the internal network to reach
the Internet. For example, you would not want the IP addresses of your
internal systems to be made available to external users. Hiding this
information will reduce the risks of external security hacks. You can use
network address translation to accomplish this.
4.At a minimum, you will need a firewall between the external network and your
DMZ, and a firewall between the DMZ and the intranet. Introducing a DMZ
configuration creates an additional security barrier that a network infiltrator
would have to overcome.

230
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Internet and intranet security considerations
The intranet environment may be a LAN-based departmental network or could
span geographic regions via a WAN-based Virtual Private Network (VPN). With
this distinction in mind, we can see that the WAN-based intranet environment
has similar characteristics to the Internet-based systems. The physical network
used in the VPN network is usually outside your management control. Thus, you
should continue to focus on network security.
For a LAN-based intranet that is segmented along departmental domains, you
could still implement a firewall between the various departments. A good
example would be to separate the production network environment from the
development network environment.
9.3.4 Web application security
The user requests will flow through your firewall to your application. The final
security checkpoint would be application security that decides who can invoke
specific application function. WebSphere provides an integrated security model
to configure security for your Web resources. This can be centrally configured
through the WebSphere Application Server Administrative Console. Table 9-4
lists the security components of the WebSphere Application Server.
Table 9-4 WebSphere security components
Together, the security components provide a unified security model, allowing a
single policy to govern the security of a diverse set of resources.
A realm is the domain in which a security system operates. All of the related
applications reside in the same realm. The administrator sets the name for the
realm, and applications and their supporting services, such as security, operate
within that single realm.
Note: When you implement the DMZ configuration, it is possible to implement
two or three firewalls on the same physical machine with two or three network
adapter cards. This is only done for cost savings, but not preferred.
Security component Location
Security server WebSphere Administrative Server
Security plug-in Supported Web servers
Security collaborator WebSphere Application Server

Chapter 9. Systems management and security guidelines
231
The security server
The runtime security components (the plug-in and the collaborator) consult the
security server, which controls security policies and provides authentication and
authorization services. The runtime components enforce these policies.
The security server has two primary purposes:
To centralize control over security policies such as permissions.
To provide application-wide services such as authentication and
authorization.
In both of these capacities, the security server acts as a trusted third-party for
security policy and control. The runtime components consult the security server
for policy information and for services such as authentication and authorization.
The security collaborator
The security collaborator is a component of the application server process, which
acts as a common runtime environment for servlets, JSPs, and EJBs. When a
Web browser client attempts to invoke a method on a servlet or an enterprise
bean, the security collaborator does the following:
Performs an authorization check
Logs security-tracing information
Enforces the delegation policy
For example, When a Java client invokes a servlet, the user is prompted for a
user ID and password, and the method invocation is passed to the application
server. The security collaborator authenticates the user against the user registry,
and if the authentication succeeds, the collaborator consults the security server
to determine if the user is authorized to invoke the servlet. If so, the collaborator
consults the security server for any delegation information. The security
collaborator builds a security context that contains the appropriate information for
the user.
Secure the WebSphere Commerce Suite System
We recommend the following to secure WebSphere Commerce Suite systems.
Protect configuration files
Configuration files contain the host name, database name, password, and
merchant key. If the Web server allows access to WebSphere Commerce Suite
configuration files, they can be visible through Web browsers and become a
security hazard. This information is so sensitive that WebSphere Commerce
Suite provides a method to encrypt it.

232
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Protect file servlets
File servlets serve static HTML pages. For example, the "file" servlet in the
default configuration under Web application called "examples" serves static
pages from the application's document directory (for example,
<WAS_HOME>/hosts/default_host/examples/web). If you access
http://<host>/webapp/examples/index.html, this servlet is invoked to serve the
page.
Now if you place a file containing confidential information within these directories,
someone who knows the filename but does not have access to it through the
operating system can invoke this servlet to obtain the file.
By protecting the URI associated with the "file" servlet, you can protect these
files. Such a URI typically ends with a "/" (for example /webapp/examples/).
Alternatively, if you want to protect only certain files (for example
/webapp/examples/test.html) served by this servlet, then protect the files
individually. To do this, you must:
Create a URI for each file.
Associate the URI with the file servlet by adding the URI to the web-path list
of the servlet.
Secure access to the URI.
Protect properties files
The WebSphere Application Server depends on several configuration files
created during installation. These files contain password information and should
be protected accordingly. Although the files are protected to a limited degree
during installation, this basic level of protection is probably not sufficient for your
site. You should ensure that these files are protected in compliance with the
policies of your site.
The files are found in the bin and properties subdirectories in the WebSphere
<product_installation_root>. The configuration files include:
In the bin directory: admin.config
In the properties directory:
– sas.server.props
– sas.client.props
– sas.client.props.future

Chapter 9. Systems management and security guidelines
233
To secure the properties files on Windows NT, follow this procedure for each file:
1.Open the Windows Explorer for a view of the files and directories on the
machine.
2.Locate and right-click the file to be protected.
3.On the resulting menu, click Properties.
4.In the resulting window, click the Security tab.
5.Click the Permissions button.
6.Remove the Everyone entry.
7.Remove any other users or groups who should not be granted access to the
file.
8.Add the users who should be allowed to access the file. At a minimum, add
the identity under which the administrative server runs.
Disable samples and documentation
To increase the security of your production site, remove any databases used for
testing or educational purposes.
Specify security level for commands
Security levels define whether SSL security and login authentication are required
to run a particular WebSphere Commerce Suite command. The command
security level can only be changed by the site administrator.
Choose the appropriate option below:
Assign security levels for commands
Change the security assignment
Remove the security assignment
Auctions
A high degree of security is built into the auctions component. In multi-store
malls, merchants or administrators of one store cannot set up or modify auctions
for another store. Likewise, the bids received for an auction can be viewed only
by authorized user roles, such as the merchant, marketing manager, or
merchandising manager. Bidders are required to log on to the site prior to bid
submission. All sensitive transactions are protected through encryption.
Important: Failure to adequately secure these files can lead to a breach of
security in your WebSphere applications.

234
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
9.3.5 WebSphere security model and policy
This section briefly describes some of the features of WebSphere Application
Server that you can use to secure your applications. Understanding this allows
you to make informed decisions in configuring and managing WebSphere
security.
The IBM WebSphere Application Server security system provides a number of
features.
WebSphere security model
At the server level, WebSphere Application Server, Advanced Edition provides a
security mechanism so that JavaServer Pages and the methods of Enterprise
JavaBeans can be invoked only by a system-level identity. When requests are
received by the WebSphere Commerce Suite Request servlet, the requisite
authority is applied to the request to ensure that requests to the commands and
templates are made only through the designated channel.
If the server is running behind a firewall, requests to the Enterprise JavaBeans
can be denied at this level. In this instance, it is the data beans within the
JavaServer Pages that provide the security. When the data bean is activated, the
data bean manager detects whether the page was invoked by a view command.
If it was not requested in this way, the request is rejected.
Authentication policies
Authentication is the process of verifying that users are who they say they are.
You can indicate how you want WebSphere Application Server to verify the
identity of users who try to access your resources. You can specify the supported
directory service of your choice or use the operating system registry to verify the
identity of users and groups.
Authorization policies
Authorization is the process of determining what a user is allowed to do with a
resource. You can specify policies that give different users differing levels of
access to your resources. If you define authorization policies, WebSphere
Application Server will enforce them for you.
Delegation policies
Delegation allows an intermediary doing work on behalf of a user to do that work
using the privileges of the user. This way, access can be granted according to the
privilege of a particular user. Without delegation, if an intermediary does work for
many users and some of those users have greater privilege than others, the

Chapter 9. Systems management and security guidelines
235
intermediary must have sufficiently generous privileges to satisfy all users, and
audit records can indicate only that the intermediary accessed a piece of data.
With delegation, access is based on the privileges of a particular user, and audit
records can track access back to that user.
A unified security administration model
The different components of WebSphere Application Server use the same model
for security, so after you learn how to set up security for one type of resource,
you can apply that knowledge to other resources. Enterprise beans, servlets,
JSP files, and Web pages are all administered similarly in terms of security. You
can combine all of these resources into an application for which you also
establish security.
Single sign-on support
The WebSphere Application Server supports third-party authentication, a
mechanism for achieving single sign-on across the Internet domain that contains
your resources. You can use single sign-on to allow users to log on once per
session rather than requiring them to log on to each resource or application
separately.
WebSphere authentication model
In WebSphere available authentication procedures include the following:
No authentication
If no authentication is used, users are not required to prove their identities.
The basic challenge
The challenge or basic authentication is a familiar form of authentication, in
which the security service requests an identifier and password combination
from a user when the user attempts to access a resource.
After a user provides an identifier and password, the security service
validates them against a database of known users, which can take the form of
a simple registry or a distributed directory service. If the user-provided
information is valid, the security system considers the user authenticated.
Digital certificates
Instead of requiring identifier-and-password combinations from users, an
application can require users to present digital certificates, which act as
electronic identification cards. The security service examines the information
in the certificate to authenticate the user.

236
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
The custom challenge
Instead of using identifier-and-password combinations or digital certificates,
application designers can write custom challenges for applications. The
authentication procedure in a custom challenge can take any form the
application developers can implement.
WebSphere authorization model
Authorization information is used to determine if a caller has the necessary
privilege to request a service. Authorization information can be stored in many
ways. For example, with each resource, you can store a list of users and what
they are permitted to do. Such a list is called an access-control list. Another way
to store the information is to associate with each user a list of resources and the
corresponding privilege held by the user. This is called a capability list.
WebSphere, like the Java security manager, uses a capability-based model for
security. In WebSphere, individual resources are collected into applications, and
methods are collected into method groups. Each user has a set of (application,
method-group) pairs, which indicates the methods within an application on which
the user has rights. Each (application, method-group) pair is called a permission.
The WebSphere administrator grants users access to applications by doing the
following:
Mapping sets of related resource into applications
Mapping sets of related methods into method groups
Granting users permissions lists
When a user attempts to perform an operation, the security runtime determines
the permissions that will grant access. If the requesting user has at least one of
the necessary lists, the authorization check succeeds and the user is permitted
to perform the operation.
WebSphere delegation model
The administrator specifies a delegation policy by setting the run-as mode for
each enterprise bean. For each bean, the administrator can choose among three
policies:
The client identity
The system identity
A specified identity, named in the delegation policy

Chapter 9. Systems management and security guidelines
237
For example, suppose that a client invokes a session bean that invokes an entity
bean. When the delegation policy states that methods are invoked under the
client's identity, the authorization checks for the entity bean ensure that the client
(rather than the session bean) has permission. When the delegation policy
requires the system identity, the authorization checks the entity bean to ensure
that the identity of the server in which the session bean resides (rather than the
client) has permission. And if the delegation policy requires a specified identity,
the authorization checks ensure that this identity (rather than either the client or
the session bean's server) has permission.
In WebSphere Application Server, every enterprise application (a collection of
resources) can have an associated identity. Therefore, you can use the
specified-identity delegation policy to run beans under the identity of the
application to which they belong.
9.4 Backup and recovery guidelines
Backup may seem a mundane and repetitive task, but it is absolutely necessary.
Its importance to you cannot be emphasized enough and typically you will only
realize it during a disaster. Imagine losing valuable transactional data due to a
hard disk failure and you do not have a backup. This section provides information
on the following:
Strategies for backup and recovery
Databases that need to be backed up
Configuration files that need to be backed up
Web assets that need to be backed up
What needs to be backed up in a development environment?
– VisualAge for Java repository
– Studio project archiving
Creating a backup image of the working environment using Symantec Ghost
9.4.1 Strategies for backup and recovery
We recommend the following when considering a backup solution:
1.Data to back up
You should consider the solution’s support for the various data you need to
back up. The data includes operating systems, application data, transaction
logs, configuration files, application databases and WebSphere Application
Server repository databases, and WebSphere Commerce Suite databases.

238
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
2.Available backup window time
In most situations, there is a limited window of time to complete the backup.
Thus, you will have to consider the performance of the backup solution.
Consider the performance of the solution as a whole, not the individual
pieces.
3.Required system recovery time
Not only should the backup be fast, but the recovery process should be
equally fast. Consider how the backup solution is able to provide fast
recovery.
4.Support for enterprise backup
The solution should be scalable to perform backups of new systems that you
may install, as a result of growth and upgrades. You may also want to use the
backup solution for other existing applications.
5.Integration with system management tools
It is very useful if the backup solution can be integrated with existing system
management tools to provide centralized administration.
6.Support for emerging technology
The software should be able to support emerging storage area network (SAN)
solutions. As your informational needs grow, these storage solutions will
provide large-capacity and high-performance data access.
9.4.2 Databases
When you install and configure the WebSphere Application Server, WebSphere
Commerce Suite, SecureWay Directory, and WebSphere Site Analyzer, you will
notice that they use DB2 as their default database. In this section, we will briefly
illustrate how a DB2 backup can be performed. For a comprehensive review of
DB2 backup and recovery, please refer to the DB2 administrative guides and
references.
In DB2, you can perform either an online or offline backup. When you do an
offline backup, the database needs to be shut down. The command for an offline
backup is:
backup db <instance name>offline=yes
If shutting down the database is not an option, then you will have to perform an
online database backup:
backup db <instance name>online=yes

Chapter 9. Systems management and security guidelines
239
When performing an online database backup, you will have to take into
consideration how the database logs will be managed, since they need to be
used in a recovery process. Losing the logs will complicate the recovery process.
For online backup, the databases need to be configured for forward recovery. To
do this you need to set either the userexit or logretain database configuration
parameter, or both. You can choose to let them be backed up automatically by
setting userexit on, if you specify logretain on so that all log files stay on disk
until you remove them. IBM supplies samples of the userexit parameter in the
sqllib/samples/c directory: one for moving log files to another directory and
moving them back when needed by DB2 (db2uext2.cdisk), the other one for
backing up the log files to ADSM (db2uext2.cadsm) and extracting them when
needed.
The following databases need to be backed up:
WebSphere Application Server database. You can use XMLConfig rather than
directly backing up DB2 to export the contents of the database (this can be
done online). Any form of backup of the admin repository need only be done
when a configuration change has been made, which shouldn't really be that
often on production machines. For details see 9.2.1, “WebSphere Application
Server Administrator’s Console” on page 206.
WebSphere Commerce Suite database.
LDAP (if SecureWay Directory is installed).
Payment Manager (if installed).
BIDM (if Commerce Suite Analyzer is installed). This is the WebSphere
Commerce Analyzer Datamart. This database contains information about the
store for which the business reports are generated.
DB2 Warehouse Center Control Database (if Commerce Suite Analyzer is
installed). This database manages the WebSphere Commerce Analyzer
extraction and report generation processed.
9.4.3 Web assets
Web assets include static HTML and images, store assets, Java resources and
configuration files. The following is a brief description of what to back up and
where to get all the contents in terms of WebSphere Commerce Suite.
Static HTML and images
If HTML, HTM, stylesheet and images outside of store contents exist, they also
need to be backed up.

240
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Store
Store assets contain the descriptor, Web assets, properties, database assets,
and document type definition. When you create a store from a sample, it bundles
everything in a SAR file. If you do not modify it, you will back up only the SAR file.
If you modify one or more elements, then you can make the SAR files with all the
contents and back it up, or you can back up all the contents separately.
Descriptors describe the store archive. The location of the file could be
<path>\SAR-INF\sarinfo.xml. If you use a Studio project, the path might be
c:\files\studio\<project_name>.
Web assets contain all HTML, JSP, images, JavaScript include files,
stylesheets, and images. Locations of these files could be
<wcs_install_path>\stores\web\<store_name>.
Properties contain the text files for the store. The location of these files could
be <wcs_install_path>\stores\properties\<store_name>.
Database assets contain all the store database assets. The location of these
files could be <path>\data\<name>.xml. If you use a Studio project, the path
might be c:\files\studio\<project_name>.
Document type definition (DTD) contains the document type definition
information for the custom XML files. For the descriptor DTD, the location
could be <path>\SAR-INF\sar-inf. For the DBLoadMacros.dtd file, the location
could be <path>\data. If you use a Studio project, the path might be
c:\files\studio\<project_name>.
For detailed information on creating a SAR file, refer to the WebSphere
Commerce Suite V5.1 Handbook, SG24-6167.
Java resource
If you customized any existing task or control command, or Enterprise Java Bean
(EJB), you need to back up the following files:
<was_install_path>\lib\<CustomEJBDeployed>.jar: deployable EJB
<was_install_path>\lib\<CustomEJBImpl>.jar: implementation of EJB
<was_install_path>\lib\<CustomCommand>.jar: task or control command
<was_install_path>\bin\<WAS_Customizable>.xml: XML file for deployment
of custom EJB
9.4.4 Configuration files
For the WebSphere Commerce Suite you need to back up the HTTP Server,
WebSphere Application Server and WebSphere Commerce Suite configuration
files.

Chapter 9. Systems management and security guidelines
241
HTTP Server
The following files need to be backed up for the HTTP Server:
<http_server_install_path>\conf\httpd.conf: store configuration information
<http_server_install_path>\conf\admin.passwd: stores password information
<http_server_install_path>\ssl\<key_file>.kdb: store certificate information
<http_server_install_path>\ssl\<key_file>.sth: store password encrypted
<http_server_install_path>\ssl\<key_file>.rdb
WebSphere Application Server (admin.config)
The following files need to be backed up for WebSphere Application Server:
<was_install_path>\bin\admin.config
<was_install_path>\bin\xmlconfig.dtd
<was_install_path>\jdk\jre\lib\security\java.security
WebSphere Commerce Suite
The following files need to be backed up for WebSphere Commerce Suite:
<wcs_install_path>\instances\<instance>\xml\<instance>.xml
9.4.5 Development environment
It is also very crucial to back up the WebSphere Commerce Suite development
environment for customization. This includes any Studio project, VisualAge for
Java, and any other environment you use for customization. For example, if you
use graphics tools to create or modify any existing images, you need to back up
all the source files.
Studio project
It is useful for routine backups to keep previous versions of Web site projects for
historical purposes. In WebSphere Studio you can do the project backup by
using the Save As Archive option. This archiving process creates a .wsr file,
which is a proprietary format that can only be opened in WebSphere Studio. The
archived file contains all the information Studio needs to recreate the project,
including publishing stages, publishing servers, and bookmarks. Archiving saves
Studio projects in a compressed format.

242
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
VisualAge for Java repository
As a VisualAge for Java developer or administrator in team development
environment, you should back up the following two files on a regular basis:
The source code repository
The repository file, ivj.dat, is the most important file to back up. It contains all
of the source code that you have developed, except for editions that are
purged prior to compacting the repository. It also contains Visual Composition
Editor information and the byte code for .class files imported from the file
system.
Resource files used by your application
When resources are released in VisualAge for Java, they are stored in a
directory in the same location as the repository (for team development it will
be a shared repository). The name of the directory is the name of the
repository with the suffix .pr. For example, if your repository is called ivj.dat,
your directory would be called ivj.dat.pr.
It is recommended that you back up resource files, such as images or sound
files, at the same time as the source repository. This is easiest to coordinate if
team developers use a shared resource directory.
You may wish to back up two additional files to avoid having to manually
reconstruct them after a system failure:
The workspace
The workspace file, ide.icx, contains the byte code for the specific editions
that you have added from the repository. If the ide.icx file is corrupted or lost,
you do not lose source code that you have saved, because it is always stored
in the repository.
The VisualAge for Java initialization file
The ide.ini file contains information about the server and repository to which
you were connected the last time that you exited the IDE or saved the
workspace. You should back up ide.ini at the same time as ide.icx.
Note: While archiving a project, Studio locks the files to prevent other people
from changing them.
Note: Never delete files directly from the file system. You should always work
in VisualAge for Java to purge, copy or back up resource files.

Chapter 9. Systems management and security guidelines
243
To back up a source code repository, use the emadmin copy command without
stopping the repository server (EMSRV). This command locks the source
repository to ensure that no one changes it while it is being copied.
Use operating system commands or a backup utility to copy the repository file,
perhaps to offline media. If you take this approach, you are responsible for
ensuring that no one can change the repository while it is being backed up.
Use operating system commands or a backup utility to copy all resources files,
and workspace (ide.icx) and initialization files (ide.ini).
Ghost
In a development environment it is very annoying to spend several days installing
everything and then one of the developing tools corrupts the system and forces
you to reinstall everything. To avoid this situation, it is recommended that you
ghost your machine after installing and configuring all the developing tools, so
that if a disaster occurs it will take only a few minutes to reestablish your working
environment.
Once the development system is configured and working properly, we
recommend that you back up the system by using a product such as Symantec
Ghost. Ghost can create an image of the hard disk that can be restored if your
system gets corrupted.

244
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
245
Part 3
B2C working
example
Part 3

246
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
247
Chapter 10.
B2C store working example
This chapter provides an overview of the B2C store working example. We
describe the ITSO sample store requirements, and how to implement the
runtime, development, and test environments. In addition, we provide
instructions on how to obtain the sample code, and create the base ITSO store.
The design and development of the ITSO store in the remaining working
example chapters builds upon the base ITSO store to meet the defined
requirements and highlight the various features of the B2C e-commerce
composite pattern using WebSphere Commerce Suite V5.1.
The chapter is organized into the following sections:
B2C store working example overview
Runtime environment
Development environment
Test environment guidelines
Sample code
Create the base store
10

248
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
10.1 B2C store working example overview
Currently, the ITSO store sells books and CDs only in retail stores. The ITSO
store needs the capability of selling its products online to retail stores. The ITSO
requires that the new online store have full integration to back-end systems for
fulfillment, inventory, and customer order status.
The ITSO sample store is intended to be used for prototyping to help generate
ideas for your business, and provide a base for creating a production-level
system. The ITSO store make use of many of the features available in
WebSphere Commerce Suite V5.1 to highlight the technology options. These
features use various commands, EJBs, and JSP display pages.
Structure of the working examples
This section describes the flow of the B2C working example chapters. The
examples presented in these chapters are consistent with the B2C Electronic
Commerce composite pattern. The examples contain requirements, solution
outline, use cases, and a description of the solution implementation and/or
source code.
Chapter 10, “B2C store working example” on page 247
This chapter describes the store requirements, runtime environment,
development environment, and sample code used to create the base ITSO
sample store.
Chapter 11, “User management and security” on page 261
The member subsystem within WebSphere Commerce Suite V5.1 has been
designed to represent the customer and human resources for a store. Some
common functions of the member subsystem include business logic for
registration, profile management, access control, authentication, session
management services, data for users, groups and organizational entities.
This chapter provides guidelines and examples for different methods of
registering users (Commerce Suite, LDAP, MQSeries) and controlling access
to the store.
Chapter 12, “Catalog management” on page 303
Catalog management includes the tasks for updating the product and store
data in the store database, and the techniques used to propagate data from a
staging server to the production server.
Chapter 13, “Order customizations” on page 329

Chapter 10. B2C store working example
249
The order subsystem is a component of the WebSphere Commerce Server
that provides shopping carts, order processing, and management function
support. Related services, such as pricing, taxation, payment and fulfillment,
are also part of the order subsystem. Order processing capabilities include
quick order or buy, scheduled orders, multiple pending orders, and reorders.
This chapter includes guidelines and examples for customizing orders, such
as reorder, scheduling orders, browsing and deleting orders.
Chapter 14, “Messaging integration” on page 361
To facilitate communication with external applications WebSphere Commerce
Suite V5.1 provides a powerful and flexible framework using the Common
Connector Framework (CCF). This communication includes the sending and
receiving of messages to and from back-end systems, and sending
notification to customers and administrators that events have occurred within
WebSphere Commerce Suite. Commerce Suite also defines well-known
messages used in the commerce systems such as OrderSend, and
InventoryUpdate. You can reuse and extend these messages or create
messages of your own type using the Framework.
This chapter includes guidelines and examples for MQSeries, e-mail, and a
news letter.
Chapter 15, “Personalization” on page 399
Implementing a personalization strategy is a great way to develop customer
loyalty and complement the marketing campaigns of your B2C Web site.
WebSphere Commerce Suite provides the infrastructure and development
tools for personalizing your Web site.
In this chapter, we explore personalization techniques for WebSphere
Commerce Suite and provide examples for rules-based personalization using
the bundled Blaze Advisor Rule Server.
Chapter 16, “Auctions” on page 443
Commerce Suite provides an auctioning component that lets you sell
products to the highest bidder. This component provides an environment for
implementing auctions as part of your B2C e-commerce solution or as a
separate auction type store.
This chapter includes guidelines and examples for implementing auctions as
part of a B2C store.
Chapter 17, “Managing a store” on page 489
Once the store has been deployed, there are many activities that need to be
performed to manage the store. We have included examples for the common
tasks, and describe how to use the Commerce Analyzer to access reports
that help examine how well your B2C store is performing.

250
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
10.2 Runtime environment
This section provides the high-level steps to implement the B2C e-commerce
composite pattern runtime environment. In addition, we provide references to
detailed instructions found in the WebSphere Commerce Suite V5.1 Handbook,
SG24-6167, and various product guides. For the purposes of illustration, we have
selected the Windows NT 4.0 Server platform; however, the main nodes of the
solution have been implemented on several other platforms (Windows 2000
Server, AIX 4.3.3, and Solaris 7).

Chapter 10. B2C store working example
251
Figure 10-1 Working example ITSO runtime environment
We have listed the key nodes in Figure 10-1, to provide a reference for detailed
instructions for implementing WebSphere Commerce Suite V5.1, Pro Edition on
Windows NT and Windows 2000, AIX, and Solaris.
Internet
Retail
customer
Cookie
Outside World
Demilitarized Zone
(DMZ)
Internal Network
IBM HTTP Server
1.3.12 for Windows
+ WAS plug-in
Windows NT or 2000 Server
WCS 5.1
WAS 3.5 + Fixpack 2 + E-fixes
DB2 Client 7.1+ Fixpack 2a
MQSeries Client 5.2
Intel-based RAID Disk
Windows NT or 2000 Server
Network Dispatcher 3.6
Protocolfirewall
nodes
Windows NT or
2000 Server
SecureWay Directory
(LDAP) 3.21
Systems
management
Security
Directory
Windows NT or 2000 Server
DB2 Server 7.1 + Fixpack 2a
Intel-based RAID0 Disk
DB server
node
Content
creation &
management
node
Application
nodes
Application
nodes
OS/390
CICS or IMS
DB2
Customor ERP
applications
MQSeries 5.2
Commerce
application
logic
Connections to
data
Connections to
backends
Personalization
Commerce
Application
Server Node
Integration
node
NetworkDispatcher
Domainfirewall
Windows NT/2000
MQSeries 5.21
1
2
3
4
5
e-mail node
6
9
Payment
node
7
8
10
Outside
Banking
system
Mobile
protocl
gateway
Retail
customer
Mobile
Device
11

252
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
1.HTTP server node
For detailed information, refer to the following:
– WebSphere Commerce Suite V5.1 Handbook, SG24-6167, Part 2,
“Implementing the runtime environment”. This section of the redbook
includes detailed installation and configuration procedures for DB2 on
Windows NT/2000, and AIX in a stand-alone and remote database
configuration. In addition, detailed procedures are included for a remote
iPlanet Web Server configuration on Solaris.
– Installation Guide, IBM WebSphere Commerce Suite V5.1 Pro Edition for
Windows NT and Windows 2000 product guide
– Installation Guide, IBM WebSphere Commerce Suite V5.1 Pro Edition for
AIX product guide
– Installation Guide, IBM WebSphere Commerce Suite V5.1 Pro Edition for
Solaris product guide
2.Commerce application server node
For detailed information, refer to the following:
– WebSphere Commerce Suite V5.1 Handbook, SG24-6167, Part 2,
“Implementing the runtime environment”. This section of the redbook
includes detailed installation and configuration procedures for WebSphere
Commerce Suite V5.1 on Windows NT/2000, AIX, and Solaris multi-tier
configurations.
– Installation Guide, IBM WebSphere Commerce Suite V5.1 Pro Edition for
Windows NT and Windows 2000 product guide
– Installation Guide, IBM WebSphere Commerce Suite V5.1 Pro Edition for
AIX product guide
– Installation Guide, IBM WebSphere Commerce Suite V5.1 Pro Edition for
Solaris product guide
3.Database server node
For detailed information, refer to the following:
– WebSphere Commerce Suite V5.1 Handbook, SG24-6167, Part 2,
“Implementing the runtime environment”. This section of the redbook
includes detailed installation and configuration procedures for DB2 on
Windows NT/2000, and AIX in a stand-alone and remote database
configuration. In addition, detailed procedures are included for an Oracle
on Solaris remote database configuration.
– Installation Guide, IBM WebSphere Commerce Suite V5.1 Pro Edition for
Windows NT and Windows 2000 product guide

Chapter 10. B2C store working example
253
– Installation Guide, IBM WebSphere Commerce Suite V5.1 Pro Edition for
AIX product guide
– Installation Guide, IBM WebSphere Commerce Suite V5.1 Pro Edition for
Solaris product guide
4.Directory node
For detailed information, refer to the following:
– WebSphere Commerce Suite V5.1 Handbook, SG24-6167 redbook,
SecureWay Directory (LDAP) chapter.
– Chapter 11, “User management and security” on page 261
5.Integration node
For detailed information, refer to the following:
– WebSphere Commerce Suite V5.1 Handbook, SG24-6167 redbook,
WebSphere Commerce Suite messaging using MQSeries and e-mail
chapter.
– MQSeries product documentation found at:
http://www.ibm.com/software/ts/mqseries/library/manuals/index.html/
6.e-mail messaging node
For detailed information, refer to the following:
– WebSphere Commerce Suite V5.1 Handbook, SG24-6167 redbook,
WebSphere Commerce Suite messaging using MQSeries and e-mail
chapter.
– Chapter 14, “Messaging integration” on page 361
7.Payment node
For detailed information on installing and configuring WebSphere Payment
Manager V2.2, refer to the following:
– WebSphere Commerce Suite V5.1 Handbook, SG24-6167 redbook,
WebSphere Payment Manager
– e-commerce Payment Solutions Implementation and Integration using
WebSphere Payment Manager, SG24-6177
– Install Guide, IBM WebSphere Payment Manager for Multiplatforms V2.2
product guide
8.Personalization node
For detailed information on installing and configuring personalization
solutions, refer to the following:
– Chapter 15, “Personalization” on page 399

254
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
– WebSphere Personalization Solutions Guide, SG24-6214
9.Dispatcher node
For detailed information on installing and configuring the Network Dispatcher,
refer to the following redbooks:
– WebSphere Edge Server: Working with WTE & Net Dispatcher,
SG24-6172
– WebSphere Scalability: WLM and Clustering Using WebSphere
Application Server Advanced Edition, SG24-6153
– WebSphere V3.5 Handbook, Using WebSphere Application Server V3.5
Standard and Advanced Editions, SG24-6161
10.Firewall node
For detailed information, refer to the following redbooks:
– A Secure Way to Protect Your Network: IBM SecureWay Firewall for AIX
V4.1, SG24-5855
– WebSphere Scalability: WLM and Clustering Using WebSphere
Application Server Advanced Edition, SG24-6153
11.Mobile device
For detailed information on enabling the WebSphere Commerce Suite V5.1
runtime and store for mobile device support, refer to the following redbook:
– Mobile Commerce Solutions Guide using WebSphere Commerce Suite
V5.1, SG24-6171
10.3 Development environment
As described in 8.2, “Development environment” on page 156, there are several
variations of development environments that can be implemented depending on
the size of your project, available resources, and customization requirements.
In the working example, we chose to implement a full development environment,
which includes WebSphere Studio, VisualAge for Java, and WebSphere
Commerce Suite installed on the development system. We used a shared file
system for the Studio project files (JSPs, static HTML, etc), and a shared
VisualAge for Java repository.
For detailed information on installing and configuring the development
environments described in 8.2, “Development environment” on page 156, refer to
the following:

Chapter 10. B2C store working example
255
WebSphere Commerce Suite V5.1 Handbook, SG24-6167, development
environment chapter.
Installation Guide, IBM WebSphere Commerce Studio V5.1 Professional
Developers Edition for Windows NT and Windows 2000 product guide
WebSphere Commerce Suite V5.1 Customization and Transition Guide,
SG24-6174 redbook
Version 3.5 Self Study Guide: VisualAge for Java and WebSphere Studio,
SG24-6136 redbook
10.4 Test environment guidelines
When working on a software development project, it is very important that the
project plan include a test environment. Too often, Web development teams
deploy the application directly to the production environment without proper
testing, which can lead to disastrous results.
In 5.3.6, “Test phase” on page 74, we describe the various types of testing and
phases of testing within the e-business life cycle. Depending on the size of
project, duration of the project, whether it is developed in-house or by a vendor,
and other reasons, the number of testing phases may vary. Regardless of these
factors, the project plan should include a test plan and test environment.
A test environment is needed not only to verify the functionality and integration of
the store, but also allows for the testing of product fixes to the various software
products that make up a Electronic Commerce composite pattern. Imagine that
you need a fix for your Web server and you do not have a test environment to
verify the patch before deploying it on the production server. You may fix the
original problem and create several new problems that have a very negative
impact on your B2C e-commerce Web site, potentially costing your business lots
of lost revenue.
The following section highlights the key elements for building a test environment
for the Electronic Commerce composite pattern using WebSphere Commerce
Suite V5.1:
Test plan
During the early stages of the e-business life cycle when the project plan is
being created, the test organization or representatives should start to develop
a test plan. The test plan includes the roles and phases of testing, such as
unit testing, build verification test (BVT), function verification test (FVT),
system verification test (SVT), and customer acceptance test (CAT).

256
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Depending on the project complexity, the people responsible for the various
test roles need to create a test plan that documents the entrance and exit
criteria, how to execute the test, and tracking of the success and failures of
test cases from build to build. Often functional tests may involve exercising
the application code by using the test application code written by the function
test team. In other cases, such as a system test or user acceptance test, the
test case may be to execute a procedure to simulate the operation of
customers using the B2C e-commerce store.
Development unit test environment
This environment is used by the developer to unit test the application code
prior to integrating the code into the common team build environment. Once
the code has been unit tested, it is checked into the source control tool and
designated for a build that includes all of the development team members
source code.
WebSphere Commerce Suite V5.1 has the capability to run within the
VisualAge for Java WebSphere Test Environment (WTE). This environment
allows for source level debugging and execution of a working store. In addition
to the unit test environment on the local development system, development
teams often have a team server where they can integrate their code before
checking it into the source control tool for a controlled build.
For additional information on unit testing, refer to 8.2.8, “Unit testing
guidelines” on page 172.
For information on configuring WebSphere Commerce Suite V5.1 to run
within the WebSphere Test Environment of VisualAge for Java, refer to:
– WebSphere Commerce Suite V5.1 Handbook, SG24-6167 redbook
– Installation Guide, IBM WebSphere Commerce Studio V5.1 Professional
Developers Edition for Windows NT and Windows 2000 product guide
System test environment
The system test environment is used by the System Verification Test (SVT)
team. Depending on the size and complexity of the project, the Function
Verification Test (FVT) may share this environment or have their own test
systems. This environment is used to formally test the functionality and
integration of the application and systems once the build team has accepted
the build by running the Build Verification Test (BVT).
This environment should include, at a minimum, a single-tier WebSphere
Commerce Suite V5.1 runtime environment. If the production environment
has complexities for integration, additional tests and nodes may be needed for
simulation and testing purposes.

Chapter 10. B2C store working example
257
Staging test environment
The staging test environment is used to test the application for a customer
acceptance test, prior to deploying the store into the production runtime
environment. Depending on the requirements of the production environment,
some companies may decide to have all of the nodes to simulate the
production environment. In this case, companies may buy smaller systems
that allow for verifying the deployment, but not the massive scalability issues
that the production runtime environment may be designed for.
Test tools
Within the system test and staging test environment, it is very useful to run
tools that simulate transactions, simulate stress on the application and
servers, and verify scalability of the application.
The WebSphere Application Server does not include any tools for the
purpose of load generation or client-side performance monitoring. There are a
number of tools available for this purpose. Some are available for free and
some are at cost. Any of the tools mentioned below can be used alone or in
conjunction with the WebSphere Site Analyzer.
Some examples of test tools include the following:
– WebSphere Site Analyzer
IBM WebSphere Site Analyzer V4.0 provides analysis for enterprise Web
site visitor traffic, visitor behavior, site usage, site content and site
structure. WebSphere Site Analyzer helps you make factual e-business
decisions regarding Web site activity. Use WebSphere Site Analyzer to
detect visitor trends and preferences, manage Web site content and
structure, and improve the overall effectiveness of Web initiatives and
campaigns. More detailed information can be found at:
• http://www.ibm.com/software/webservers/siteanalyzer/
• Up and Running with WebSphere Site Analyzer, SG24-6169 redbook
– AKTools
Is a set of IBM internal test tools used to test application performance.
– WebStone
WebStone is an open-source benchmark tool that is freely available from
Mindcraft. WebStone was originally developed by Silicon Graphics to
measure software and hardware performance.
http://www.mindcraft.com/

258
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
– Apache Bench
The HTTP Server on UNIX platforms includes the Apache Bench (Apache
Bench is Perl script-based). This tool allows for HTTP client load
simulation. You can specify the URL, number of total requests, and the
number of concurrent requests with this tool. See Appendix D, “Additional
material” on page 583. Further information and the source code for
Apache Bench are available from the Apache Software Foundation at:
http://www.apache.org/
– Rational Suite Performance Studio
Performance Studio offers support for a variety of clients, both Web and
non-Web based. Among the clients supported are HTML, DHTML,
Document Object Model, Visual Basic, Visual C++, Java, ActiveX and
PowerBuilder. Performance Studio records user inputs for playback as
scripts that are used in performance testing.
More information on Rational Suite Performance Studio, including an
evaluation copy, is available from:
http://www.rational.com/
10.5 Sample code
The sample code produced while writing this redbook is available for download
and is referred to throughout the remaining working example chapters. Each of
the subsequent chapters includes sample Java code, configuration files and a
procedure to implement and deploy the samples.
To download and unzip the sample code, complete the following steps:
1.To download the additional materials zip file, enter the following in a browser:
ftp://www.redbooks.ibm.com/redbooks/sg246180/
2.Unzip SG246180.zip to the directory of your choice (for example, c:\temp).
Table 10-1 provides the subdirectories containing the sample code for the
example chapters and a brief description. The subdirectories listed will be visible
after unzipping the SG246180.zip file.
Table 10-1 B2C e-commerce sample code zip file contents
Directory Description
\sg246180\member User management and security samples
\sg246180\catalog Catalog management samples

Chapter 10. B2C store working example
259
10.6 Create the base store
There are several types and approaches to creating a store. In this example, we
will create a base B2C e-commerce store by using the WebFashion store as a
template. The base B2C store is used as a starting point to add the features
documented in the remaining working examples consistent with the B2C
e-commerce composite pattern.
The high-level steps to create a store are as follows:
1.Create the base store.
a.Download the WebFashion sample store from:
http://www.ibm.com/software/webservers/commerce/wcs_pro/downloads.html/
b.Create a store template.
c.Generate a store from a template.
d.Publish the new store.
e.Update the VisualAge for Java WebSphere Test Environment to run the
new store. This allows for the store to be run and debugged within
VisualAge for Java.
2.Load store assets into Commerce Studio.
a.Unzip the SAR to the PackageSAR directory.
b.Create a WebSphere Studio project.
\sg246180\orders Order customization samples
\sg246180\messaging Messaging integration samples
\sg246180\auctions Auction samples
\sg246180\pzn Personalization samples
Directory Description
Note: The detailed instructions for creating a store can be found in Chapter 11
of the WebSphere Commerce Suite V5.1 Handbook, SG24-6167 redbook.
Note: At this stage, you can publish the new store to your test runtime
environment. The sample store contains the product data for WebFashion.
As an alternative, you can modify the XML configuration files with your
store data or update the store data later as documented.

260
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
c.Import store assets into WebSphere Studio.
d.Configure WebSphere Studio after the import of assets.
3.Configure WebSphere Studio for publishing.
a.Create publishing stages.
b.Create a server to publish to.
c.Define assets to publish and the target publishing path for each publishing
stage. For example, you may have publishing targets for the WebSphere
Commerce Suite runtime environment, VisualAge for Java WebSphere
Test Environment, and the local file system directory PackageSAR
directory used to zip the SAR file.
4.Publish the store from WebSphere Studio.
a.Publish all assets defined for a stage and server or publish selected files.
b.Create the SAR file used by Store Services to publish the store.
5.Basic customization assets.
The WebFashion sample store includes the Web assets (JSPs, static pages,
etc.) and the store XML data files. The XML files include products, categories,
shipping, tax information, etc.
a.Basic customization of Web assets. This includes basic changes such as
the store logo, name, updating properties files, etc.
b.Basic customization of XML data files. There is a good chance that your
B2C store does not sell the same products as Web Fashion, thus you will
need to update the XML data files for your store data. We have included
chapters focused on managing your store catalog and using the Loader
package tool to update the store database (see Chapter 12, “Catalog
management” on page 303 and Appendix B, “Loader package” on
page 539).
10.7 Summary
If you intend to use the sample code, we recommend that you complete the
following steps before proceeding:
Set up a test runtime environment
Set up a development environment
Create a base store
Modify the base store with your store information
Package a SAR file with your changes
Publish your store using the updated SAR file

© Copyright IBM Corp. 2001
261
Chapter 11.
User management and
security
B2C e-commerce Web sites are customer-centric ,unlike conventional
businesses, which are product-centric. The success of a B2C e-commerce Web
site may be determined by customer retention rather than by the number of visits
or registered users.
The member subsystem within WebSphere Commerce Suite V5.1 has been
designed to represent the customer and human resources for a store. Some
common functions of the member subsystem include business logic for
registration, profile management, access control, authentication, session
management services, data for users, groups and organizational entities.
This chapter is organized into the following sections:
User management and security guidelines
Member subsystem architecture
Implementation examples overview
Use case 1: online user registration
Use case 2: user registration using LDAP
Use case 3: user registration using MQSeries
11

262
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
11.1 User management and security guidelines
The user management processes used for B2C stores are more or less standard
for Web sites. This include such capabilities as a registration profile, address
book, shopping cart etc. Your B2C store may provide unique or specialized
features; however, we recommend that you do not deviate too much from the
industry standards.
The main activities involved with user management are as follows:
Customer registration and profile management
Member security
Member groups
11.1.1 Customer registration and profile management
To provide the regular and special services, many B2C Web sites encourage
customers to register for additional benefits. In some cases, registration is a
mandatory process (for example, a banking application requires an account).
We have listed some guidelines for collecting the required data when designing a
registration process:
Mandatory parameters
The customer registration process has a direct effect on authentication. If you
would like to use basic authentication, it is necessary to collect a unique user
name (for example, customer login ID) and password. If you are using
certificate-based authentication, these parameters are optional, but other
information about the customer such as address, social security number, and
e-mail address may be required.
Demographic information
Information such as birthday, age, marital status, interests and hobbies,
income, etc. can be used for personalization, discounts, and promotions.
Communication information
Information such as e-mail, fax, phone number etc. are important for
communication.
Note: Many B2C Web sites use the e-mail address as the user ID. The
advantage of using the e-mail address for the user ID is uniqueness. The
disadvantage is if the customer’s e-mail ID changes, in many systems the
logon ID is not easily changed.

Chapter 11. User management and security
263
Customer address and payment information
This information is important for order fulfillment such as billing and shipping.
Business profile
The business profile information (employee/self employed/student,
organization details) is often not as important for B2C stores, but can play a
crucial role depending on your business process model.
Profile management
The registered users (members) should be given additional services such as
the ability to update their registration information (for example, password,
shipping address, billing information, etc.).
11.1.2 Member security
The complete security process involves the policies of authentication,
authorization, privacy, and single sign-on. This section provides design
guidelines for the key issues related to member security for B2C e-commerce
Web sites.
Authentication
Authentication is the process of identifying or verifying the user validity. The user
can be identified by various methods. We have included the following examples
of authentication methods:
Biometrics: finger print, retinal scan
Certificate authentication: badge, certificate, smart card
Basic authentication: user ID and password
Basic and certificate-based authentication modes are popular over the Web.
Most B2C Web sites use basic authentication because of its simplicity and
cost effectiveness. Certificate-based authentication is more secure, but has
the disadvantages of greater complexity and cost.
Note: Most auction sites requires payment information such as a credit card
number as a part of registration to insure validity. Many e-commerce systems
validate the user address for proof and fraud detection using an Address
Verification System (AVS).

264
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Authorization
Authorization is the process of granting access privileges to resources based on
the member access permissions.
The commerce system may have variety of resources for its business,
operations and administration. These resources requires fine-grained access
control based on the level of authorization. The important resources and their
access policies are summarized as follows:
Common: Access to these resources can be given to any user (for example, a
catalog).
Personal and confidential: These resources are customer specific and cannot
be shared. They require the customer’s own credentials (for example,
registration details, credit card, shopping cart, etc.).
Personal and shared: These resources are customer specific but access can
be granted to others by the customer (for example, a wish list).
Registered users only: Permission to these resources is granted only for
registered members (for example, technical data, white papers, and special
promotions).
Administrative: Permission to these resources is granted only for commerce
system administrators (for example, order approval and payment approval).
Privacy
Privacy refers to the policies for protecting customer confidentiality. Policy
examples include sharing of his personal information, means of exchanging
registration profiles with other business systems, legal actions, online
advertising, etc. It is very common for an e-commerce Web site to have a link or
statement about the Web site privacy policy.
Session control and single sign-on
Web sites are accessed using the HTTP protocol from a Web browser, which is a
stateless protocol. If the user interaction involves activity that requires
uniqueness such as credentials, or a shopping cart, there needs to be a
mechanism to identify and track the user status and information consistently over
this stateless channel. This mechanism is commonly known as session control
and can be accomplished by such methods as using cookies, URL rewriting, or
Note: The time of authentication and registration is also an important factor.
Some systems prompt for authentication as soon as the user visits the site (for
example, banking and e-mail services). Other sites, such as a retail store, will
prompt for authentication at the time of checkout.

Chapter 11. User management and security
265
hidden variables. Each of these methods has an effect on the application
programming model, and security. The session control strategy may be different
for Web browser clients and mobile computing devices such as mobile phones
and wireless PDAs. For example, most mobile phones do not have the capability
to store a cookie locally. For additional information on mobile commerce, refer to
the Mobile Commerce Solutions Guide using WebSphere Commerce Suite V5.1,
SG24-6171 redbook.
With Enterprise-out e-commerce Web sites that require integration with other
systems, the customer may be redirected to another system. If the resources on
the external systems require access control, the user may be asked to
authenticate (log on) multiple times, which is very cumbersome to the customer.
For example, a retail B2C Web site may provide services to access the product
catalog, chat, e-mail, and payment. To avoid multiple customer logons, we
recommend a single sign-on solution across all systems accessed by the
customer.
11.1.3 Member groups
To provide common services and better user management, member groups can
be used for authorization when called as access roles, and for business services
known as customer groups.
Access groups
These groups are mainly used to control access to the commerce system. Some
examples of access groups are as follows:
Guest shopper (customer that has not registered)
Registered customer
Commerce system administrator
Customer services representative
Customer groups
These groups are for business operations such as providing discounts,
promotions, and campaigns.
A member can belong to more than one member group. The member can leave
or rejoin the group again and can play different roles depending upon the group.
The association of the member with a member group can be static or dynamic.

266
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Static member groups
The association of members to these member groups is highly static. The
member will join in these groups at the time of registration or by updating their
profile. Some examples of static member groups are as follows:
– Age groups: child/teenager/young/adult/senior citizen
– Gender: male/female
Dynamic member groups
The association of members with their groups is highly dynamic in nature and
depends upon certain activities of the customer, such as the number of visits
or order history.
For example, the past three months’ order value of customers can be
grouped as Silver (below $1000), Gold (above $1000 and below $10000) and
Platinum (above $10000) to target for a campaign.
11.2 Member subsystem architecture
WebSphere Commerce Suite V5.1 provides a flexible and powerful framework for
the member subsystem to support most of the requirements specified in 11.1,
“User management and security guidelines” on page 262. You can reuse, modify
or extend the features provided by WebSphere Commerce Suite V5.1 according
to your specific requirements. The Commerce Suite member subsystem includes
components for member registration, member profile management, access
control, and authentication session control.
In this section we provide a description of the processing flow within the member
subsystem as follows:
Member registration and profile management
Member groups
Member security
Commerce Suite components of member subsystem
Note: The above features for registration and security depend on the physical
storage of member data called the user registry. Various types of user
registries can be used, depending upon the requirements and features that
you would like to provide. Some examples of user registries include operating
systems, database, LDAP, CRM applications, or other legacy systems.

Chapter 11. User management and security
267
11.2.1 Member registration and profile management
A member in the Commerce Suite member system could be a user,
organizational entity, or a member group.
Member types
This section describes the types of members.
User
A user in Commerce Suite can be registered or a guest (not registered). The
registered user will have a complete user profile such as registration details,
address book, and membership to specific member groups. The
non-registered users can be either generic or anonymous and do not have
profile data.
Member group
A member group is either a type of customer or access group. The type of
member group indicates the intended usages of the member group. A
customer type member group is for business use, while an access type
member group is used for access control purposes.
Organizational entity
The organizational entity can be either an organization or organizational unit.
An organization is a large, relatively static grouping within a larger corporation
or enterprise. An organizational unit is a relatively static grouping within a
larger organization (for example, the ITSO is an organizational unit within
IBM).
Member profiles
Members of type user and organizational entity have member profiles.
User profile
A basic user profile incorporates registration information, demographics,
address information, purchase history, and other miscellaneous attributes. A
business user profile contains the same information as a basic user profile, as
well as employment information, such as an employee number or a job title, or
a job description. The business profile may also contain a link to the business
organization to which the user belongs.
A registered user often has an address book, which contains a list of
addresses. The address book contains address information for the user,
friends, and relatives. The user can have many addresses, but one of them
must be the primary address. Also, the user can have default shipping and
billing addresses, which can be used for quick orders or one-click order
services.

268
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Profiles for organizational entities
This include information such as the organization name and business
category.
Member registration process and methods
Commerce Suite follows the store and mall approach, which means a Commerce
Suite e-commerce Web site can have a mall that contains many stores. User
registration is a site or mall-level process. By default, user registration is not
specific to a store but for the entire mall. The store can be customized for the
registration process, but the registered user can access the complete site.
User registry
One of the important factors to consider when designing a member registration
process is the type of member registry options supported by WebSphere
Commerce Suite V5.1.
WebSphere Commerce Suite store database
By default Commerce Suite uses the store database for user registry. This
method has the advantage of high reliability and simplicity. The
disadvantages of having user registration specific to Commerce Suite is that it
may not be sharable across other systems such as e-mail, chat etc.
LDAP
WebSphere Commerce Suite V5.1 can use LDAP as the user registry in a
synchronized mode. This means that users added to the LDAP database are
also updated automatically to the store database.
The advantages of using an LDAP directory is the sharing of user registration
information across all applications, which is necessary for a single sign-on
solution. The disadvantages are cost, maintenance, and failover of the LDAP
directory system.
Note: The direct usage of Commerce Suite user registration information
from the store database is not possible using the SQL or UserRegistration
EJB because it uses an encrypted password that cannot be used by other
systems.

Chapter 11. User management and security
269
Object and data models for members
Figure 11-1 and Figure 11-2 depict the entity objects and database schema for
the member subsystem. The object model UML diagram seen in Figure 11-1
represents the entity. The data model E-R diagram seen in Figure 11-2
represents the database schema relationships used by various business
components in registration, security, member groups, etc. in WebSphere
Commerce Suite V5.1.
Figure 11-1 Object model of the member subsystem

270
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 11-2 Data model of the member subsystem
User registration methods
To facilitate various requirements for e-commerce Web sites (for example,
Web-up or Enterprise-out), Commerce Suite provides several methods for user
registration as seen in Figure 11-3 and described below.
Figure 11-3 User registration and update methods
Customer
Commerce Suite
database
MQSeries
Applications
JNDI
LDAP
API
Directory
Applications
LDAP Directory
Management Tool
Legacy DB
Customer Service
Representative
Mass Loader
Mass Import Files
3a
3b
3c
LDIF
Commerce
Suite
MQ
1 2
3
4
LDAP

Chapter 11. User management and security
271
1.WebSphere Commerce Suite online registration
This involves the registration of members online for the live e-commerce Web
site. Users will be prompted for registration before catalog navigation or
during the order checkout process. This is the most common and direct
approach of the user registration method. This method does not support
mass registrations and is well suited for Web-up solutions.
2.MQSeries
Commerce Suite also supports member registration from back-end systems
such as ERP systems using MQSeries. To enable this method, the
Commerce Suite message transport adapter and MQSeries need to be
configured. Commerce Suite provides an inbound messaging service for
creating and updating customer registration. This method is very useful if you
have legacy systems, which you need to Web enable. This approach is best
suited for an Enterprise-out solution. By default, Commerce Suite does not
provide outbound services over MQSeries for the member subsystem.
3.Using LDAP
Commerce Suite also supports integration with industry-standard LDAP for
user registration. If LDAP is used as an user registry, then Commerce Suite
will synchronize with the LDAP directory, based on the mapping parameters
defined in the Commerce Suite ldapmap.xml file between Commerce Suite
and LDAP. When the registered user in LDAP logs into the Commerce Suite
system, the user entry is replicated on the fly to the Commerce Suite store
database. Commerce Suite will synchronize with the LDAP directory to
retrieve and update the user registration for the following scenarios:
– Registration through WebSphere Commerce Suite
The registration profile will be created in Commerce Suite and a new entry
will be created on the fly in the LDAP directory.
– Registration in LDAP
The LDAP users can be created in one of the following methods:
• Using LDAP Applications (3a in Figure 11-3 on page 270): The Java
applications of LDAP generally uses JNDI while others can use LDAP
API for registering users to LDAP.
• Using LDAP Directory Management Tool (3b): Most of the commercial
LDAP systems will come with an administrative interface, which helps
in LDAP administration such as adding, creating and deleting entries.
The IBM SecureWay Directory tool is called the Directory Management
Tool (DMT).
• Using LDIF (3c): (LDAP interchange file format): This helps in mass
registration of users and migration from legacy systems.

272
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
– A registered user logon to Commerce Suite and user profile is not found in
LDAP
The current logon user registration entry of Commerce Suite will be
replicated on the fly to LDAP.
– User logs on to Commerce Suite, and the user registry will be available
both in Commerce Suite and LDAP
The registration information in Commerce Suite will be compared with
LDAP and if any changes are made in LDAP, those parameters will be
updated in Commerce Suite.
– Registered user updates their registration profile in Commerce Suite
The profile will be updated both in Commerce Suite and LDAP. This
method is very useful if you have various applications that would like to
share common user data.
4.Using Commerce Suite Loader package (mass load)
The Commerce Suite Loader package is used for mass database updates.
The Mass Loader tool can be used for mass registration of users. This
method is especially useful in the migration from previous versions, database
management, and member registration exchange across Commerce Suite
systems.
The registered users will manage their user profile by updating the
registration information, adding, modifying or deleting address entries in the
address book. Also, a customer service representative can update the user
profiles by using the Commerce Suite Commerce Accelerator.
Important: The above scenarios will change depending on the
authentication mode for LDAP. If the authentication mode is simple, then
LDAP should be available for the Commerce Suite operation. If the
authentication mode is none, Commerce Suite allows user registration and
(based on the above-mentioned scenarios) will try to replicate with LDAP.
Once the user logs into the Commerce Suite system his profile in LDAP will
not be replicated back to Commerce Suite until he logs off the Commerce
Suite system. In other words, if you log on to the Commerce Suite system
and simultaneously make changes in the LDAP directory, those changes
will not take effect in Commerce Suite until the session completes.

Chapter 11. User management and security
273
11.2.2 Member groups
WebSphere Commerce Suite V5.1 supports two types of member groups. The
member groups used for access control are known as access groups, and for
customer services they are known as customer or user groups.
Customer groups
Customer groups in WebSphere Commerce Suite V5.1 plays an important
role for discounts and pricing.
WebSphere Commerce Suite V5.1 by default does not provide a GUI to
support customer groups. You can manually create the database entries or
use the EntityAdmin command to create customer groups and associate
users to these groups.
– Static association: Once the customer joins the group he remains a fairly
long time as a member of the group. This association is most common
during user registration or a registration update by customizing the
commands.
– Dynamic association: Unlike static association the user will change in the
user groups depending upon certain metrics, such as the past three
months’ purchase history, or number of visits over a period of time.
WebSphere Commerce Suite V5.1 by default does not provide any
support for these groups, but you can create your own command and add
it to the job scheduler to accomplish this task.
Note: WebSphere Commerce Suite does not provide the built-in function for
Address Verification Systems (AVS). You can easily customize Commerce
Suite to make use of an AVS by using UPS or CyberSource. For information
on integrating Commerce Suite with an AVS, refer to Chapter 11 in the
WebSphere Commerce Suite V5.1 Customization and Transition Guide,
SG24-6174 redbook.
Note: If you are using WebFashion as your store template, WebFashion
provides a facility to automate the static member groups association. To
use these groups, you need to run the discounts.db2.bat file found in the
<wcs_install_path>/bin directory, which calls the
RegisterNAddToMemberGroup command for the user registration.
WebFashion does not provide the facility to change the member groups for
a registered user.

274
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Access groups
Access groups are described in “Authorization” on page 264.
11.2.3 Member security
This section describes WebSphere Commerce Suite V5.1 member security for
authentication, authorization, session control, single sign-on, and session
transition to Commerce Suite.
Authentication
WebSphere Commerce Suite V5.1 supports two modes of authentication:
Basic authentication (using user ID and password)
Certificate-based authentication (using x.509 certificates)
You can use either basic authentication or certificate-based authentication, but
not both. For certificate-based authentication, Commerce Suite does not provide
any infrastructure for creating and managing the certificates. Products such as
IBM Registry or RSA/VeriSign can be used for managing the certificates.
To specify the mode of authentication, start the Commerce Suite Configuration
Manager and select InstanceList -> <your_wcs_instance> -> Instance
Properties -> Web Server. You also need to verify the Web Server httpd.conf to
make sure that the Web Server prompts users to require and accept certificates.
Commerce Suite also supports X.509 certificate with LDAP usage.
Basic and certificate authentication modes can be perfored using the following
authentication policies for user profile information.
Using WebSphere Commerce Suite: The user is authenticated against the
Commerce Suite store database.
Using LDAP: The user is authenticated against the LDAP server.
Using other: To use the third-party authentication you need to implement the
ThirdPartyAuthenticationCmd interface and should authenticate against the
store profile data in Commerce Suite store database.
Tip: The Blaze Advisor Engine, which ships with WebSphere Commerce Suite
V5.1, can be used for campaigns targeted at dynamic groups. Blaze provides
a flexible framework to dynamically identify the user group based on
predefined parameter rules and produces the desired result.

Chapter 11. User management and security
275
To specify the policy for the authentication, start the Commerce Suite
Configuration Manager and select InstanceList -> <your_wcs_instance> ->
Instance Properties -> Member subsystem.
Authorization
WebSphere Commerce Suite V5.1 uses member groups of the access group
type to implement access control. By default WebSphere Commerce Suite V5.1
provides the following access groups, also known as access roles:
Customer
Customer Service Representative
Marketing Manager
Merchandising Manager
Merchant
Order Clerk
Site Administrator
Store Administrator
Store Developer
Each of these groups is defined to play a specific role and given access to
resources. For a description of these roles, refer to 17.1, “I/T specialist roles and
tasks” on page 490 and 17.2, “Business user roles and tasks” on page 504.
The Commerce Suite Administrator can control the customer access to
resources such as commands, using the Administrator Console. The access to
customer resources can be further controlled by providing protected access,
which restricts access to registered users (for example,
UserRegistrationUpdate). The access control is implemented when the
command is registered or updated in the command registry.
Session control
Commerce Suite is based on J2EE specifications and follows the servlet
specifications for session management.
Session Manager: You can use either the Commerce Suite Session Manager
or the WebSphere Application Server Session Manager for the Commerce
Suite application server in the WebSphere Application Server. The session
Note: If a guest shopper attempts to access the protected customer
resources, Commerce Suite automatically tries to authenticate the user by
displaying LogonForm.

276
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
control configuration can be modified from Configuration Manager for the
Commerce Suite instance.
The advantage of using the WebSphere Application Server to manage the
session is that you can add extra information to the session. When managing
a session using Commerce Suite you cannot add extra session information.
However, it has the advantage of better performance. The Commerce Suite
session cookie in a clustered environment needs to maintain the session
affinity.
Session types: Commerce Suite supports two types of session management,
cookie-based and URL rewriting. For security reasons, cookie-based session
management uses two types of cookies: non-secure session cookies which
are used to manage the session data, and secure authentication cookies
used to manage authentication data. For more information, refer to 7.1.4,
“Application session management” on page 122.
Commerce Suite supports session management for mobile devices using the
PVC adapter. For more information, refer to the Mobile Commerce Solutions
Guide using WebSphere Commerce Suite V5.1, SG24-6171 redbook.
To define the session manager and session type, start the Configuration
Manager and select InstanceList -> <your_wcs_instance> -> Instance
Properties -> Session Management.
Single sign-on
Commerce Suite supports single sign-on with WebSphere Application Server
and Domino when LDAP is used as a user registry. You can enable the single
sign-on option in the Configuration Manager when configuring LDAP.
Note: By default Commerce Suite does not use session timeout. In other
words, once the user logs on to the Commerce Suite, the session is valid till
he either logs off or closes the browser. You should design the application
appropriately for session timeout scenarios (for example, based on the user
inactivity for timeout for security reasons).
If the session timeout is enabled, guest shoppers cannot continue shopping
where they left off previously, because of session invalidation. Commerce
Suite also supports simultaneous logon of the same user from more than one
browser.

Chapter 11. User management and security
277
Session transition in a Commerce Suite environment
Consider a typical shopping flow when you visit a home page or catalog page. It
is very common (not necessary) that users have to identify themselves to the
e-commerce Web site. But the moment an action that is specific to the user is
executed, such as adding an item to a shopping cart, the e-commerce store
should identify the user uniquely. When the user revisits the site and starts
shopping, he should have the ability to complete the partially filled order, once he
has been identified uniquely. Commerce Suite supports all of these features
using the session control strategy, as described in“Session control” on page 275.
The Commerce Suite member subsystem includes customers (actual shoppers),
who can be registered and non-registered. There are two types of non-registered
users: a generic user and an anonymous user. A generic user does not perform
any specific tasks or actions on an e-commerce Web site that requires unique
identification. Once the generic user performs an action that requires unique
identification, such as adding a product to a shopping cart, the generic user
becomes anonymous. It is also possible that the design of the site requires an
anonymous user to become a registered user before certain tasks can be
performed, such as placing an order. Migration from generic to anonymous to
registered user is automatic. The session transition is depicted in Figure 11-4.
Note: In order to use LTPA with LDAP, you must enable WebSphere
Application Server Security using the WebSphere Administrator’s Console.

278
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 11-4 Session transition in Commerce Suite when shopping
You can turn on a cookie acceptance warning for the browser and observe the
cookie. Commerce Suite sends different cookies depending upon your
interactions.Figure 11-5 through Figure 11-11 show the sequence of cookies
received from Commerce Suite when visiting the store, performing shopping, and
then registering during checkout.
Figure 11-5 shows the Commerce Suite session cookie when the user first
visits the Commerce Suite store catalog page. The current state of the user is
generic.
Figure 11-6 shows the Commerce Suite authentication cookie. When the
generic user adds an item to the shopping cart, the state will change from
generic to anonymous.
Figure 11-7 shows the session cookie for an anonymous user after
authentication.
WCS moves all
interest items,order
items and orders to
the current registered
profile.
WCS updates an
anonymous guest
profile as a registered
profile.
Action which requires
user's unique
identification.
e.g.:
InterestItemAdd
OrderItemAdd
Action which doesn't
require user's unique
identification.
e.g.
Category Display
Product Display
Clears current session
by sending Generic
guest session.
WCS clears anonymous
session by sending
registered user session
and authentication ticket.
WCS sends Guest
Session for Generic
User.
WCS resends
authentication and
session cookies.
WCS clears Generic
User session with
Anonymous User
session,also creat es a
guest shopper record
and sends
aut hentication t icket.
Generic User
Anonymous User
Registered User
Regis ter
or
LogOn
Logon
InterestItemAdd
Register
Store Catalog Display
LogOff

Chapter 11. User management and security
279
Figure 11-8 shows the Commerce Suite authenticated cookie after the user
registration. The state of user changed from anonymous to registered.
Figure 11-9 shows the Commerce Suite session cookie for a registered user.
Figure 11-10 shows the Commerce Suite session authentication cookie after
the user logs off. The state was changed from registered to generic.
Figure 11-11 shows the Commerce Suite session for the generic user after
sending an authentication cookie.
Figure 11-5 Commerce Suite generic user session cookie
Figure 11-6 Authentication cookie for an anonymous user adding items to shopping cart

280
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 11-7 Commerce Suite anonymous user session cookie
Figure 11-8 Commerce Suite authentication session after registration
Figure 11-9 Commerce Suite session for the registered user

Chapter 11. User management and security
281
Figure 11-10 Commerce Suite authentication session after logoff
Figure 11-11 Commerce Suite session after logoff
11.2.4 Commerce Suite components of member subsystem
To facilitate the Commerce Suite member subsystem components described in
11.2.4, “Commerce Suite components of member subsystem” on page 281,
Commerce Suite provides commands, JSPs, and data beans for member
customizations.

282
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Table 11-1 includes a summary of the common components used to customize
member subsystem-related operations. For a detailed list of the components,
including task commands, data beans, access beans, and EJBs, refer to the
Commerce Suite online documentation.
Table 11-1 Commerce Suite member subsystem components for customization
11.3 Implementation examples overview
This section provides an overview of the ITSO store requirements, solution
outline, and use cases of the user management and security examples.
11.3.1 ITSO sample store user requirements
The ITSO store will offer redbooks in softcopy, hardcopy, and CDs. The ITSO
store permits shopping for both guest shoppers and registered shoppers.
The ITSO store will offer online registration over the Web.
The ITSO store has an operational back office with an MQSeries
communication channel, which allows the customers in the back office to be
permitted to shop online over the Web.
ITSO store has other applications such as e-mail, and in the future the ITSO
store will provide more services such as chat, calendaring, and news groups,
which will use the common registration information.
Feature URLCommads JSPs Property Files
Registration
Management
UserRegistraionAdd
UserRegistraionUpdate
OrgEntityAdd
OrgEntityUpdate
register.jsp
edit_registration.jsp
UserRegistraion
.properties
AddressBook
Mangement
AddressAdd
AddressCheck
AddressDelete
AddressUpdate
addressbook.jsp
addressbookform.jsp
address.jsp
addressform.jsp
billingaddress.jsp
shipaddress.jsp
Address.propert
eis
MemberGroup
Management
EntityAdmin
Security
Management
Logon
Logoff
ResetPassword
logonform.jsp
logoff.jsp
forgetpassword.jsp
resetpassword.jsp

Chapter 11. User management and security
283
For simplicity, the ITSO store would like to use basic authentication as the
security mechanism. In order to register a user, we need to provide a unique
user ID, which is an ITSO store logon ID (valid e-mail address) and password.
For password conformity, the user should provide the verification of the
current password.
To help the user if they forget the password, the user should be provided a
challenge question and answer. As a minimum for communication, the user
should supply their first name and last name.
The ITSO store will provide personalization and special discounts based on
gender, age, and employment type.
The ITSO store will send a regular personalized news letter for the registered
users who are interested in receiving the newsletter for the technical topics
such as WebSphere Commerce Suite and WebSphere Application Server.
The ITSO store will permit the change of registration information such as
password, first name, and last name.
The ITSO store will provide an address book for the registered users, which
can be used for order checkout, and gift services such as a wish list or gift
registry.
If a registered user forgets his password, the ITSO store will regenerate the
password and will send an e-mail to the user after providing the challenge
question and answer.
11.3.2 Solution overview
This section describes the solution outline for the above-mentioned user
requirements. The following list represents the use cases to be developed:
Online registration over the Web
Online registration update
User registration using LDAP
User registration using MQSeries
Address add
Address delete
Address book view
Logon
Logoff
Forget password, challenge, reset, send

284
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
From the WebSphere Commerce Suite online documentation, we can identify the
important WebSphere Commerce Suite V5.1 supported functions for the current
requirements.
For example, online registration can be done using WebSphere Commerce Suite
V5.1 commands and JSPs. For the common user registry, we can use LDAP with
Commerce Suite. For the MQSeries requirements, we can use the WebSphere
Commerce Suite V5.1 messaging service.
We will explain the implementation for the following use cases:
Use case 1: online user registration
Use case 2: user registration using LDAP
Use case 3: user registration using MQSeries
Before implementing the above use cases, we must fulfill certain prerequisites.
The main prerequisites in this case are data modeling and member grouping.
Data modeling
Data modeling involves the collection of data for the member subsystem and
mapping it to the Commerce Suite schema as documented in Table 11-2.
Table 11-2 Data collection for member subsystem for users
Parameter Allowed values Characters Function
logonid A valid e-mail
address
Required and
cannot be
modified
Allows the user to
uniquely identify and log
in to the system
password A valid password Required and
modifiable
For authenticating the
user
verifypassword Same as password Required and
modifiable
For password conformity
challeneQuestion A valid Argument
e.g.:My Favorite
Color
Required and
modifiable
Helps in identifying the
user to log on in the
system when he lost the
password
challengeAnswer A valid answer
e.g: indigo
Required and
modifiable
Helps in identifying the
user to log on in the
system when he lost the
password
firstName Character text Optional and
modifiable
User’s first name

Chapter 11. User management and security
285
lastName Character text Required and
modifiable
User’s last name
age Numeric Range
0-9
10 - 19
20-29
30-39
40-49
50-59
60 and above
Optional and
modifiable
Helps in personalization
gender Male
Female
Optional and
modifiable
Helps in personalization
empType IBMRegular
IBMContract
IBMBusinessAsso
ciate
NonIBMEmployee
SelfEmployed
UnEmployed
Optional and
modifiable
Helps in offering
discounts and
promotions
interestTopics A combination of
* WebSphere
Commerce Suite
* WebSphere
Application Server
* MQSeries
* Lotus
* DB2
*VisualAge for
Java
Optional and
modifiable
Helps in sending
personalized Newsletter
newsLtrRcv boolean value
Yes/No
Optional and
modifiable
Willingness to receive
newsletter
Parameter Allowed values Characters Function

286
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Commerce Suite persists the user registration in the USERS, USERREG,
USERDEMO, and USERPROF tables. The parameters in Table 11-2 such as
logonid, password, lastname, and firstname will be mapped in their default way.
Table 11-3 describes the mapping of additional parameters. For the details of
parameter mapping, refer to the WebSphere Commerce Suite online
documentation.
Table 11-3 Mapping of parameters in the UserDemo table
11.4 Use case 1: online user registration
This use case involves registration of a customer online using a Web browser.
The user will open the registration form by clicking the register link or when
prompted for registration by the system while shopping. The registration details
are stored in the Commerce Suite store database when Submit is clicked.
Parameter
name
Column
name
Data
type
Mapping
strategy
interestTopics HOBBIES VARCHAR(254) An assembled string of
interests by using the ‘:’
delimiter. For example,
if the user selects
WebSphere Commerce
Suite, WebSphere
Application Server, and
MQSeries as his interests
then the value in this
column is WebSphere
Commerce
Suite:WebSphere
Application
Server:MQSeries
empType FIELD1 CHARACTER(1) 1 - IBMRegular Employee
2 - IBMContractEmployee
3 - IBMBusinessAssociate
4 - NonIBMEmployee
5 - SelfEmployed
6 - UnEmployed
newsLtrRcv FIELD2 CHARACTER(1) Y - Yes
N - No

Chapter 11. User management and security
287
11.4.1 Prerequisites
The following prerequisites must be completed before proceeding with the
sample implementation:
WebSphere Commerce Suite V5.1 installed
The base ITSO store is created from the WebFashion template and deployed.
The data model is defined and user groups must be created in Commerce
Suite for the ITSO store.
WebSphere Studio should be installed.
11.4.2 Component identification
From the WebSphere Commerce Suite documentation and the ITSO store, we
will use the component in Table 11-4 for user registration.
Table 11-4 Component used for use case 1
11.4.3 Component study and implementation
This section describes each component for the use case and the changes
required for implementation. Use case 1: online user registration, which requires
the following components:
UserRegistrationAdd
Register.jsp
UserRegistrataion_en_US.properties
UserRegistrationAdd
The UserRegistrationAdd

is defined in the member subsystem of the URL
commands and has the syntax as shown in Figure 11-12. For more detailed
information, refer to the WebSphere Commerce Suite online documentation.
Commands JSPs Property files
UserRegistrationAdd register.jsp infashion_en_US.txt
UserRegistraoin_en_Us.properties
Note: The completed versions of these files can be found in the additional
materials SG246180.zip file, <unzip_path>\sg246180\members directory after
being unzipped.

288
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 11-12 UserRegistrationAdd command syntax
This command has the following functional limitations for the ITSO store
implementation:
– The ITSO store requires that the user logon ID be an e-mail address. This
command does not verify the validity of the logon ID as an e-mail address.
– The ITSO store allows a user to select multiple topics of interest, but this
command will take only one parameter of interest (hobbies).
– The ITSO store will enforce users to add a valid challenge question and
answer for a password request, but the command cannot provide the
verification of these parameters.
Functional limitation severity: Medium.
Action to be taken: These functional limitations can be overcome by using
JavaScript for validation at the front end by modifying the JSP.
Register.jsp
The register.jsp provides the registration form for a Web browser client. This file
is packaged in the WebFashion.sar file and is deployed to the ITSO store in the
<wcs_install_path>\stores\ITSO\web\register.jsp directory.
Supported functionality: This JSP supports the default parameters for the
registration.
Functional limitations: The ITSO store requires additional parameters for
UserRegistration. This component does not require additional parameters by
default.
Functional limitation severity: High.

Chapter 11. User management and security
289
Action to be taken: To facilitate additional functionality, we need to modify
register.jsp.
Metrics: Requires the skills of a Web designer to modify the JSP. The
estimated time for this change is one hour, including unit testing.
List of changes:
– Provide three JavaScript Functions to the JavaScript section:
checkEMail(), checkChallenge() getCurrentInterestList( ).
– Added functionality to display fields for EmploymentStatus, Interests and
Newsletter acceptance.
UserRegistrataion_en_US.properties
The UserRegistration_en_US.properties file provides the required properties for
the UserRegistrationCommand. This file is deployed to the
<wcs_install_path>\stores\properties\ITSO directory.
Changes: The parameters for challenge Question and Answer requirements
were enabled as required (propertyName=‘yes’).
infashiontext_en_US.properties: This file provides the Parameter display text
for UserRegistration Form. This file is deployed to the
<wcs_install_path>\stores\properties\ITSO directory.
Changes: The text for additional parameters (challenge question/answer,
interests, newsletter) are added for the register.jsp section.
11.4.4 Deployment and testing
After making the required changes and publishing the updated assets to
Commerce Suite, testing needs to be performed. In this example, we performed
the following steps to verify the functionality:
1.Start a Web browser and enter the store URL.
Note: For details on JSPs and programming, please refer to the following
redbooks:
WebSphere Commerce Suite V5.1 Customization and Transition Guide,
SG24-6174
Servlet and JSP Programming with IBM WebSphere Studio and VisualAge
for Java, SG24-5755
Version 3.5 Self Study Guide: VisualAge for Java and WebSphere Studio,
SG24-6136
WebSphere Commerce Suite V5.1 Handbook, SG24-6167

290
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
2.Click the registration link. You should see something like Figure 11-13.
Figure 11-13 Use case 1: online user registration
3.Create a user by registering using the updated form.
4.Observe the database for the saved user profile.
5.Observe the failure criteria (for example, challenge question).

Chapter 11. User management and security
291
11.5 Use case 2: user registration using LDAP
This use case involves registration of a customer to an LDAP directory by an
LDAP application, an LDIF file, or by the administrator using the SecureWay
Directory V3.21, Directory Management Tool (DMT). The LDAP registered
customer is able to log in to the ITSO store without having to register using the
Web registration form.
11.5.1 Prerequisites
The following prerequisites must be completed before proceeding with the
sample implementation:
Same as 11.4.1, “Prerequisites” on page 287
IBM SecureWay Directory V3.21 must be installed and configured with
WebSphere Commerce Suite V5.1. For details, refer to the SecureWay
Directory (LDAP) chapter in WebSphere Commerce Suite V5.1 Handbook,
SG24-6167.
11.5.2 Solution overview
WebSphere Commerce Suite provides integration support for LDAP for IBM
SecureWay Directory V3.21, Lotus Domino, ADS, and Netscape directories. In
our example, we used IBM SecureWay Directory V3.21.
The parameters, attributes, and what to export/import between WebSphere
Commerce Suite and LDAP are defined in the Commerce Suite ldapmap.xml file.
The mapped entries and LDAP server parameters should be defined in
Commerce Suite Configuration Manager within the member subsystem of the
Commerce Suite instance.
Supported functionality
The default integration supports the mapping of parameters like user ID,
password, last name, first name, address, etc. Also, it provides replication
from LDAP to Commerce Suite and Commerce Suite to LDAP based on user
interaction in Commerce Suite as explained in “User registration methods” on
page 270.
Note: For a user registration update and a forget password request, you will
need to change edit_register.jsp, forgetpassword.jsp and myaccount.jsp. The
completed versions of these files can be found in the
<unzip_path>\sg246180\member directory.

292
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Functional limitations
The ITSO store registration profile includes additional parameters such as
interests, employment type, challenge question and answer. These additional
parameters should be available in the LDAP registry, but the default
implementation in WebSphere Commerce Suite V5.1 does not support this
facility. Also, the object class used in the default implementation “ePerson” of
IBM SecureWay Directory V3.21 does not support the additional attributes.
Functional severity: High.
Action to be taken
Need to extend the default mapping and add additional attributes for the
ePerson object class.
Metrics
Requires approximately three hours for a skilled Commerce Suite site
administrator and LDAP administrator.
11.5.3 High-level implementation
This section provides the high-level steps to implement use case 3.
1.Install and configure the LDAP Server.
2.Configure the Commerce Suite instance to enable LDAP support.
3.Define the mapping of Commerce Suite-LDAP parameters.
4.Set up and configure the LDAP Server. In our case, we are using the IBM
SecureWay Directory V3.21 as an LDAP directory. For detailed information on
installation and configuration for WebSphere Commerce Suite, refer to the
SecureWay Directory (LDAP) chapter in WebSphere Commerce Suite V5.1
Handbook, SG24-6167.
5.Define the LDAP schema.
6.Create a suffix using the SecureWay Directory Web Admin tool.
7.Add an entry for the created suffix.
8.Select the object class for the user, and identify the attributes.
– Since the ITSO store is actually an organizational unit of IBM US, we
created the top-level suffix as o=ibm, c=us using LDAP admin. After
restarting the LDAP server we added an organizational entry for the suffix
o=ibm,c=us and then created an organizationalUnit entry as ou=itso,
o=ibm, c=us using the DMT.
– In our case we selected ePerson as the object class for which the user
entries will be created in LDAP. ePerson is the IBM-defined schema that

Chapter 11. User management and security
293
has the super classes inetOrgPerson, organizationalPerson, person and
top.
– ePerson does not support the additional attributes for the ITSO store
registration, so we created the attributes defined in Table 11-5, and added
to the ePerson objectClass.
Table 11-5 Attributes for LDAP
9.After creating the attributes, we associated the attributes to the ePerson
object class. Since the ITSO Store requires a challenge question and answer,
we made them required attributes for the ePerson objectClass. To provide
consistency for registration, we also enforce the userPassword attribute as
required instead of optional as seen in Figure 11-14 on page 294.
Attribute name Syntax Purpose Comments
challengeQuestion Directory
String
Represents user’s
password
challenge question
challengeAnswer Directory
String
Represents user’s
password
challenge answer
userInterests Directory
String
Represents the
user’s interests
Actually multivalued
attribute is an ideal
candidate, but owing to
Commerce Suite mapping
limitation on multi-values we
selected this as a single
valued attribute
newsLtrReceive Directory
String
Represents user’s
willingness to
receive newsletter
Actually boolean value is a
good candidate for this,
since we are saving the
newsletter acceptance as Y
or N in the field1 and
because of Commerce
Suite limitation in translating
the data, we had chosen
this as a directory string

294
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 11-14 Attributes for the ePerson objectClass
10.Register users in LDAP by creating entries using an LDIF file, or DMT, or
using an LDAP application.
11.In our example, we created five user entries for the ePerson using LDAP
interchange file format (LDIF).
12.After the LDIF file has been imported, restart the server and rebind the DMT
to make the changes effective.
Attention: Make sure that you don not have any entries created for the
ePerson in your directory, since we are enforcing ePerson to require the
challenge question and answer. If you have existing entries in the directory
associated with the ePerson, the ePerson object class update fails
because of an inconsistency.
Note: A sample LDIF file itsousers.ldif file can be found in the additional
materials zip file provided with this redbook
(<unzip_path>\sg246180\member directory).
You can use the LDAP Admin to import the LDIF file and notice the logs.

Chapter 11. User management and security
295
After performing all of the above steps, our directory tree looks like
Figure 11-15.
Figure 11-15 LDAP directory tree
13.Configure the Commerce Suite Server.
To enable LDAP integration, we need to configure the Commerce Suite
server by starting the Commerce Suite Configuration Manager. Select
<wcs_instance> -> Instance Properties -> Member subsystem tab. Select
the authentication mode as LDAP and enter the information as required.
In our example, we entered the following:
– Authentication mode: LDAP
– LDAP Version: 3
– LDAP type: IBM SecureWay Directory 3.21
– Host: m23bk68t.itso.ral.ibm.com
– Port: 389
– Administrator distinguished name: cn=root
– Administrator password: admin
– Confirm password: admin
– LDAP authentication mode: none
– Time out = 0
– Mapping file name: c:\ibm\wcs\instances\wcs\xml\ldap\ldapmap.xml

296
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
– LDAP Search root: ou=itso,o=ibm,c=us
– Shopper base distinguished name: ou=itso,o=ibm,c=us
– Shopper Object Class: top person organizationalPerson
inetOrgPerson ePerson
– Organization objectClass: top organization
– Organizational unit objectClass: top organizationalUnit
– Person RDN: cn
14.Apply the changes made and close the Configuration Manager.
15.Define the mapping strategy.
We need to define what parameter of the Commerce Suite entity will be
mapped to what attribute of LDAP entity. The mapping file is provided in the
<wcs_install_path>\wcs\instances\<wcs_instance>\xml\ldapmap.xml
directory. The default mapping is not sufficient for the ITSO store
requirements.
16.Modify this file to support additional parameters for the ITSO store. We
updated the additional mapping described in Table 11-6.
Table 11-6 Mappings for the ldapmap.xml for the ITSO store
17.After applying the changes in Commerce Suite Configuration Manager and
saving the ldapmap.xml file, restart the Commerce Suite application server
instance. Back up the ldapmap.xml file before making the changes.
Note: Take note of the location of the ldapmap.xml file.
Commerce Suite
object-
attribute
LDAP
Entry-attribute
Type Operation Flow
UserRegistry -
challengeQuestion
ePerson -
challengeQuestion
ces replace Both directions
UserRegistry
-challengeAnswer
ePerson -
challengeAnswer
ces replace Both directions
Demographics
-hobbies
ePerson -
userInterests
ces replace Both directions
Demographics -
field1
ePerson -
employeeType
ces replace Both directions
Demographics -
field2
ePerson -
newsltrReceive
ces replace Both directions
Address - email1 ePerson - mail ces replace Both directions

Chapter 11. User management and security
297
11.5.4 Testing
After restarting the Commerce Suite server, start a Web browser and enter the
ITSO store URL. Log on as the user created via LDAP. Also, observe other
scenarios such as a new registration via Commerce Suite, update the
registration information in LDAP, and update the registration information in
Commerce Suite. The Commerce Suite store database for the user data should
be replicated from LDAP.
11.6 Use case 3: user registration using MQSeries
This use case involves registration of a customer using MQSeries. The users
added via MQSeries should be able to log into the ITSO store without registration
to the ITSO store online using the logon form.
11.6.1 Prerequisites
The following prerequisites must be completed before proceeding with the
sample implementation:
Same as 11.4.1, “Prerequisites” on page 287
MQSeries installed and configured
The MQSeries server must be installed. The WebSphere Commerce Suite
MQSeries adapter must be configured with the Commerce Suite instance. For
detailed information, refer to the chapter on messaging using MQSeries and
e-mail in WebSphere Commerce Suite V5.1 Handbook, SG24-6167.
11.6.2 Solution overview
Commerce Suite provides for integration with MQSeries using JMS. In our
example, we used IBM MQSeries V5.2 with JMS installed (mq88_xx.zip, where
xx is the platform).
The parameters, attributes, what to map, type and flow between the Commerce
Suite commands and inbound XML are defined in the sys_template.xml and
user_template.xml files.
Note: The sample ldapmap.xml file can be found in the additional
materials.zip (<unzip_path>\sg246180\member directory).

298
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
For user registration and updating, Commerce Suite provides support legacy
format (using the DTD files Create_NC_Customer_10.dtd and
Update_NC_Customer_10.dtd) and in XML format (using
Create_WCS_Customer_20.dtd and Update_WCS_Customer_20.dtd).
Create_WCS_Customer_20.dtd and Create_NC_Customer_10.dtd XML are
mapped to use UserRegistrationAdd command and
Update_WCS_Customer_20.dtd and Update_NC_Customer_10.dtd XML are
mapped to use UserRegistrationUpdate command and is defined in
sys_template.xml. In our case we are used the XML formatted messages.
Supported functionality
The default integration supports mapping of parameters such as user ID,
password, last name, first name, and address. It invokes the command
UserRegistration.
Functional limitations: same as in use case 1 using UserRegistrationAdd
command.
Action to be taken
Need to validate the emailId, add the interests as separate delimited ( ‘:’)
strings and map them to hobbies. The XML needs to be verified separately
before sending to Commerce Suite inbound queues.
Metrics
Requires the skills of a site administrator and MQ programmers and
administrator. Will take approximately three hours to complete (including
installation and configuration).
11.6.3 High-level implementation
This section provides the high-level steps to implement use case 3.
1.Set up and configure the MQSeries Server.
2.In our example, we used MQSeries V5.2 and JMS Fix Pack ma88_win.zip on
Windows NT. For details on the installation and configuration with Commerce
Suite, refer to the chapter on messaging using MQSeries and e-mail in
WebSphere Commerce Suite V5.1 Handbook, SG24-6167.
3.Create the MQSeries queues for Commerce Suite as follows:
– WCS inbound
– WCS inbound parallel
– WCS inbound serial
– WCS outbound

Chapter 11. User management and security
299
– WCS error
4.Configure the Commerce Suite Server for MQSeries integration.
To enable MQSeries integration, configure Commerce Suite server via the
Configuration Manager. Select <wcs_instance> -> Messaging -> Enable
the Transport Adapter. Define the JMS objects using the JMS admin tool.
5.Change the class paths and restart the Commerce Suite server instance.
11.6.4 Testing
To verify the MQSeries registration, complete the following steps:
1.After restarting the Commerce Suite application server, create the XML
message for user registration in compliance with
Create_WCS_Customer_20.dtd and send to the inbound queues.
2.Start a Web browser and enter the ITSO store URL.
3.Log in as the user created via MQSeries.
4.Verify the registration information by clicking Change my personal
information on the My Account page.
5.In our case we created the XML messages as shown in Example 11-1 and
placed them in the inbound serial queue.
Example 11-1 shows the XML message and Figure 11-16 on page 301 the
registration information after logging in to Commerce Suite.
Example 11-1 xml message used for user registration using MQSeries
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE Create_WCS_Customer SYSTEM "Create_WCS_Customer_20.dtd">
<Create_WCS_Customer version="2.0">
<ControlArea>
<Verb value="Create" />
<Noun value="WCS_Customer"/>
</ControlArea>
<DataArea>
<Customer>
<Registration>
<LogonInfo>
<LogonID>animesh@in.ibm.com</LogonID>
<Password>animesh</Password>
<VerifyPassword>animesh</VerifyPassword>
</LogonInfo>
<StatusInfo>
<CustomerStatus/><PasswordExpired/>
</StatusInfo>
<Challenge>
<Question>My Interested Middleware</Question>

300
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
<Answer>MQSeries</Answer>
</Challenge>
</Registration>
<AddressInfo>
<AddressNickName>Ani</AddressNickName>
<AddressType/>
<PersonName>
<LastName>Ghosh</LastName>
<FirstName>Animesh</FirstName>
</PersonName><Address>
<AddressLine>IBM Global Services</AddressLine>
<AddressLine>AirPortRoad</AddressLine>
<City>Bangalore</City>
<State>KA</State>
<ZipCode>560 017</ZipCode>
<Country>India</Country>
</Address>
</AddressInfo>
<Profile>
<Personal>
<DistinguishedName>animesh</DistinguishedName>
</Personal>
<Demographics>
<Age>25</Age>
<Gender>M</Gender>
<Hobbies>MQ:DB2:WCS:WAS</Hobbies>
<DemographicField>1</DemographicField>
<DemographicField>Y</DemographicField>
</Demographics>
</Profile>
</Customer>
</DataArea>
</Create_WCS_Customer>

Chapter 11. User management and security
301
Figure 11-16 Registration profile for a user created via MQSeries

302
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
303
Chapter 12.
Catalog management
This chapter provides the fundamentals of the catalog hierarchy, and describes
how the catalog is represented in the WebSphere Commerce Suite store
database. We include guidelines and procedures for loading catalog data,
removing catalog data, installation instructions for a staging server, and
propagation guidelines.
The primary tool for loading the WebSphere Commerce Suite V5.1 store
database is called the Loader package. The chapter makes reference to
Appendix B, “Loader package” on page 539, where we explain how to install the
Loader package on the remote system and give an example how to use the
utilities of the Loader package.
The chapter is organized into the following sections:
Catalog design
Strategies for loading the store catalog
Data management
12

304
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
12.1 Catalog design
The WebSphere Commerce Suite catalog has its specific features, hierarchy,
and organization. A full understanding of the WebSphere Commerce Suite
catalog can lead to successful WebSphere Commerce Suite implementation. In
the following section, we describe the catalog hierarchy from both a logical and
functional view. Please refer to IBM WebSphere Commerce Suite V5.1 online
documentation for more additional information if needed.
12.1.1 Catalog hierarchy
The WebSphere Commerce Suite catalog can be presented as a tree structure
or a combination of trees structures, as seen in Figure 12-1. The hierarchy can
have the following levels:
Catalog level
Catalog group level
Product level
Item level
Figure 12-1 Catalog hierarchy
Books
Software
Catalog
level
WebSphere
Family
DB2 books
WCS books
MQ Family
Catalog
group
level
WCS
handbook
Item
level
Hard
cover
Soft
cover
CD
WCS B2C
pattern
Product
level
WCS V5.1
WCMV2
Start
Edition
Pro
Edition

Chapter 12. Catalog management
305
Catalog level
The catalog partitions products into meaningful views as seen in Figure 12-1 on
page 304. In this example two trees represent two different catalogs. The catalog
has to have an assigned the owner. The owner for the catalog is created as an
organization in the ORGENTITY table.
In order for the catalog entries to by displayed for a store, the catalog, catalog
groups and catalog entries must be assigned to the catalog for a store in the
following database tables:
STORECAT
STORECENT
STORECGRP
DISPCGPREL
DISPENTREL
A catalog entity represents a catalog in the database in the CATALOG and
CATALOGDSC table. Figure 12-2 on page 306 depicts the high-level
relationships between the entity beans of the catalog. The catalog, CatalogGroup
and CatalogEntry beans all have owners and are related to a store.

306
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 12-2 Catalog object model
Catalog group level
The catalog group levels provides the ability to bring related products together.
They may correspond to departments in an actual store. With properly structured
catalog groups, customers can easily browse through an e-commerce store and
quickly find the desired product. Catalog groups provide an effective structure for
a product line, and provide pathways for customers to navigate through the store,
starting at the home page and navigating to a product page.
Note: The data bean implemented for the catalog entry is the
CatalogDataBean, which extends CatalogAccessBean and
CatalogDescriptionAccessBean.
Catalog
CatalogDescription
Member
1*
CatalogGroup
1
CatalogGroupDesc
*
CatalogEntry
CatalogObject
Bundle
Package
Product
Item
CatalogEntryDescription
StoreEntity
1
*
1
*
*
1
*
*
*
*
+subCatalogEntry
*
*
+subCatalogEntry

Chapter 12. Catalog management
307
To create catalog groups, first the products must be arranged in a tree hierarchy.
The tree begins at a general catalog group called the root. At the next level are
branches or subcategories, which increasingly get specific until they cannot be
further divided into categories. Each of the lowest level catalog groups, which
contains only products, are called leaves. A catalog group is the parent to the
categories immediately below it, and a child of the category above it. The catalog
group information is stored in the CATGROUP and CATGRPDESC tables.
After the catalog groups are created for the catalog, the top-level groups must be
assigned to the catalog. The CATTOGPR table store this information.
The CATGRPREL table keeps information about relationships between catalog
groups. For example, the top-level catalog groups have subcategories and so
on.
Catalog entries level
The merchandise in your catalog takes the form of catalog entries. Products,
items, packages, and bundles are all examples of catalog entry types.
Product
A product is a group of items.
Item
An item is a specific instance of a product, defined by attributes. For example,
the WebSphere Commerce Suite V5.1 Handbook, SG24-6167 is a product,
because this product cannot be uniquely identified until the cover or CD
version is provided as attributes.
Bundle
A bundle is a collection of catalog entries. For example, a bundle for a
computer may comprise a central processing unit, a monitor, a hard drive,
and a CD-ROM drive. Bundles may be a grouping of items, or a combination
of products, items and packages. If a bundle contains only items and is added
to an order, it is broken into separately orderable items. Bundles allow
customers to buy multiple items at one time. The price of a bundle object is
the aggregate of the prices of all the bundle components.
Note: The CategoryDataBean can be used to access an entity bean created
for these tables.

308
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Package
Packages are an indivisible collection of catalog entries. For example, a
computer package may contain a specific central processing unit, monitor,
and hard drive that may not be available separately. A package has its own
price and is a separately orderable SKU that can be added to an order. A
package cannot be broken up or modified.
The catalog entries can be created by adding the information to the CATENTRY
and CATENTDESC tables.
The CATGPENPREL table keeps information about relationships between the
products and catalogs groups. For example, the WebSphere Commerce Suite
V5.1 Handbook, SG24-6167, and B2C e-commerce Composite Pattern, Using
IBM WebSphere Commerce Suite V5.1, SG24-6180 redbooks belong to the
WebSphere Commerce Suite category group.
Item level
Each product in your catalog has a specific set of attributes. For example, the
WebSphere Commerce Suite V5.1 Handbook, SG24-6167 can be obtained as a
hard copy, soft copy or on CD. Items are defined by the attribute values, for
example a hard copy or soft copy.
Attributes and attribute values can be created in your catalog by adding
information to the ATTRIBUTE and ATTRVALUE tables.
12.2 Strategies for loading the store catalog
This section describes the strategies for loading the WebSphere Commerce
Suite catalog. The whole process can be divided into the following phases, as
shown in Figure 12-3:
Data preprocessing
Data load
Data propagation
Note: Data beans used to access the catalog entries are
CatalogEntryDataBean, BundleDataBean, and PackageDataBean.
Note: The ItemDataBean can be used for retrieving or updating attribute
information.

Chapter 12. Catalog management
309
Figure 12-3 Loading of Commerce Suite catalog
The most important phase data-wise is the preprocessing. During this phase the
data is transformed from various formats, merged from different data sources
and so forth.
The first two steps intensively use the IBM WebSphere Catalog Manager, which
consists of utilities for preparing and loading WebSphere Commerce Suite data.
Alternatively, you may use your own tools or processes to pre-process data to be
used by the Loader package supplied with WebSphere Commerce Suite.
The Loader package may be used to load large amounts of data and to update
data in your Commerce Suite database. The Loader utility in this package uses
valid and well-formed XML as input to load data into the database. Elements of
the XML document map to table names in the database, and element attributes
map to columns.
The loading process consists of the following high-level steps necessary to load
data into the Commerce Suite store database:
1.Generating a document type definition (DTD) using the DTD Generator utility
2.Resolving IDs in the input files with the ID Resolver utility
3.Loading the data using the Loader utility
Figure 12-4 on page 310 depicts the sequence in which the Loader package
utilities are executed. The DTD Generator in used to produce the DTD files used
during pre-processing phase. The ID generator and Loader are use during the
load phase. More detailed information on how to use the utilities of the Loader
package can be found in Appendix B, “Loader package” on page 539.
Propagation can be performed by the Commerce Suite staging propagation
utilities or a native DB2 propagation utility such as Dprop.
Preprocessing
Load
Staging
database
Production
database
Propagate
XML

310
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

Figure 12-4 Loader package data flow
Create new
DTD
Create XML
file
Resolve XML
file
Load XML file
DTD Generator
ID Resolver
Loader
New DTD
XML
Resolved
XML
Default DTD
DTD

Chapter 12. Catalog management
311
12.2.1 Data preprocessing
The preprocessing is a process or a set or processes executed with the goal of
creating well-formatted XML documents. These XML documents are used as
input files for WebSphere Commerce Suite Loader package. Depending on the
business case, the data preprocessing can be approached differently with the
same objective: well-formatted XML documents based on the generated DTD
file.
An XML document can be created manually, extracted from an already existing
database, or can be created as a result of merging data from more than one data
source. The XML document must be built upon predefined DTD files, against
which it must be validated. When a document is checked for validity by the ID
Resolver, it is verified as to whether the document’s content matches the logical
structure as it is defined in the DTD. For example, for a document to be valid, all
tags and attributes appearing in the document must have corresponding
declarations in the DTD, and all elements appearing within other elements must
adhere to the content model defined in the DTD.
A DTD can be generated by the DTD Generator run against the Commerce Suite
store database as seen in Figure 12-5 on page 312. When the database schema
is modified, the new DTD must be generated. If not, the default DTD can be
used. Appendix B, “Loader package” on page 539 explains how to install and run
the DTD Generator.
Commerce Suite catalog data can originate from different data sources, as seen
in Figure 12-5 on page 312. For example, catalog data can be stored in an SAP
system, an existing application database, or an Excel spreadsheet. Also, data
can be stored in different formats in different quantities and qualities.
For these reasons, it is important to understand the answers to the following
questions as they relate to the preprocessing phase for WebSphere Commerce
Suite applications:
1.Is all needed data available?
2.In how many data sources is catalog data stored?
3.In how many formats is the data stored?
4.What is the best way to merge this data?
5.Is there a need for the third0party transformation engine?
6.How often is data loaded? Once a week or every day?
7.Is every load being performed for all data or only for a delta?
8.What is the quality of the data?
9.What is the quantity of the data?

312
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
10.Is there a need to load data from separate XML documents?
11.Is there a need to have additional machines for preprocessing only?
Commerce Suite applications are data driven. It becomes irrelevant how fancy
the front-end of the application is, if data cannot be delivered on time and in the
right quality. We recommend that you spend a significant amount of time to
ensure that all needed data is available for loading.
Figure 12-5 Data preprocessing
The preprocessing phase not only targets catalog data, but all data that must be
loaded to Commerce Suite database. Data can be grouped into the following
categories:
Catalog (category, product, prices, etc.)
Member or user (registration information, addresses, demographic data)
Site data (store information, shipping information, tax information)
XML generator/
tranformation
engine
External data
souce
DTD
ASCII or
XML
Spread
sheet
XML
DTD Generator
WCS
database

Chapter 12. Catalog management
313
Data can be represented in one or more XML documents. The catalog data can
be loaded separately from member data, but parts of the catalog can be loaded
separately. The catalog can be represented by more XML documents. For
example, the catalog update for customers in a different time zone can be
scheduled during low peak hours in this time zone.
12.2.2 Load
The load phase loads data into the WebSphere Commerce Suite database. In
this phase we assume that data that is produced during the preprocessing is
valid and well-formatted XML documents.
To load the catalog, the following steps must be completed:
1.Run ID Resolver
2.Perform a backup of the database (optional, but recomended)
3.Run Loader
Appendix B, “Loader package” on page 539 describes how to install and run ID
Resolver and the Loader utility. Chapter 9, “Systems management and security
guidelines” on page 203 provides guidelines on database backup.
Figure 12-6 depicts the process of loading data into the staging database.
Note: The same considerations apply to the member and site data as for
catalog data.

314
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 12-6 Data load
There are basically two options for implementing loading to the store database:
1.Local loader
The Loader package utilities are installed on the same machine as the
Commerce Suite and the database server. Figure 12-7 describes this
solution. The following issues must be considered:
– Installation of IBM JDK on the staging server.
– Installation of the load utilities on the staging server.
Note: We recommend loading data first to the staging database and then
using the propagate utility to propagate data to the production database. This
way you can avoid potential problems with a corrupted database in the event
of a loader failure.
ID Resolver
Staging
database
XML
resolved
Loader
XML
DTD

Chapter 12. Catalog management
315
Figure 12-7 1-tier approach - components.
2.Remote loader
In this approach, the Loader package utilities are installed on a separate
machine from the Commerce Suite system. If the runtime environment
consists of a 2-tier remote database server environment, the remote load may
be performed on the database server or over the network from a remote
database client containing the Loader package, as depicted in Figure 12-8 on
page 316.
The following issues must be considered:
– Installation of the Loader package utilities on the remote system
– Installation of a database client
– Installation of IBM JDK
– Network configuration
– The loader restriction when loading data to the remote database (see
Appendix B, “Loader package” on page 539 for more information)
Staging server
ID Resolver
Staging
database
XML
Loader
DTD

316
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 12-8 2-tier approach - components
12.2.3 Propagation
After data is loaded into the staging database, tested, and approved, the
propagation utilities will be used to propagate data to the production database.
In this section, we describe two approaches for staging servers:
1.Commerce Suite staging server with a staging instance
This approach requires data synchronization from the production database to
the staging database before any changes can be done in the staging
database. WebSphere Commerce Suite provides a framework of components
supporting this solution.
2.Commerce Suite staging server without a staging instance
This approach does not require data synchronization from the production to
the staging database. Rather the data consistency is managed on the staging
server, which must be identical to the production database during the
production lifetime. This solution uses a native DB2 propagation utility called
Dprop. This solution is outside of the scope of this redbook and should only
be considered for advanced users.
Commerce Suite staging server with a staging instance
Primarily, the Commerce Suite staging server is a tool that allows the site
administrator to copy the production database to a staging database for code
testing purposes, without impacting customers using the production store site.
Secondarily, the Commerce Suite staging server can be used for verification of
data before data propagation to the Commerce Suite production database.
Staging server
Application server
ID Resolver
Staging
database
XML
Loader
DTD

Chapter 12. Catalog management
317
The database tables managed by a staging server include all operational data,
but do not include any customer, order, or SET-related data. The site
administrator can work with fictitious users and orders.
The site administrator makes changes on the staging server, then after ensuring
that these changes are working properly, the site administrator can propagate the
data to the production server.
How the staging server works
The production database can be copied to the staging database by using the
stage copy utility. This utility will copy all operational tables of the production
server to the staging server database. A typical B2C database can be divided
into two groups:
Tables that contain operational data
The operational tables contain data such as store, catalog, tax, discount, and
so on. They are under the site administrator's control, and only this user can
modify them.
Tables containing customer data
The customer tables contain the customer's information, such as address,
orders, etc.
The staging server includes the operational tables only, ensuring that this data
will not be updated by other users during the staging session.
A log is created in the STAGLOG table during the configuration. Whenever a
change is made to a record in a staging table, a trigger records this change into
the STAGLOG table. For each modified record, a trigger records the type of
modification (delete, insert, or update), the name of the table in which the record
resides, and the record's primary key or unique index. After you complete
changes and tests on the stage database, propagate the data to the production
server using the stage propagate utility. The information in the STAGLOG table
identifies the records in the stage database that must be deleted, inserted, or
updated in the production database.
Do not make any changes on the production database that can disturb the
consistency of data after propagating the data from the staging server. A staging
session begins when you use the stage copy utility to copy the production
database to the staging database. It ends when you use the stage copy utility
again to begin a new session. At this point, you can update the stage database
only and use the stage propagate utility to propagate changes to the production
database.
Figure 12-9 on page 318 depicts the Commerce Suite staging environment and
flow of data using the stage propagation utilities.

318
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 12-9 Commerce Suite staging environment
If you update the production database during a stage session, your propagation
will fail due to key conflicts or reference integrity violations, and your update
could be lost. But if you must update the production database during the staging
session, you should create a new staging session using the stage copy utility to
synchronize both databases again.
You need to be aware that any image files, HTML files, or JSP files must be
manually copied from the production environment to the staging server, and if
they are new files, they must be manually copied from the staging server to the
production environment.
Staging server components
The staging server consists of the following components:
Commerce Suite instance
The staging server uses the staging log table STAGLOG, and database
triggers to log changes to store tables. Whenever you change a record in the
staging tables, the changes are recorded in the STAGLOG. This table will be
used later when you propagate the data from the staging server to the
production server.
Database schema scripts
Scripts are used to create the staging tables and the triggers for the staging
database. The stage database contains the same schema as the production
database, plus a set of tables used for staging purposes and a set of triggers
used to log the changes made in the stage database.
Commerce
Staging
instance
Commerce
Production
instance
stagingcopy
stagingprop
Staging environment Production environment
Staging
database
Production
database

Chapter 12. Catalog management
319
Stage copy utility
Allows the site administrator to copy all data from the production database to
the staging database.
Stage propagate utility
Allows the site administrator to propagate changes on the staging database
to the production database using the information in the STAGLOG staging
table. The stage propagate utility uses the STAGLOG table to identify which
records must be inserted, updated, or deleted, and then updates these in the
production database.
Configuring a staging server
To create a staging server, do the following:
1.When you create a Commerce Suite instance in the Configuration Manager,
ensure that you select the Use Staging Server check box on the Database
tab, and configure your instance as a staging server.
2.In the Configuration Manager, you need to ensure that the cache is not
enabled by doing the following:
a.In the Configuration Manager, expand the <instance_name> folder.
b.Select Cache and be sure that the Cache Enable check box is
unchecked. Click Apply.
c.Close the Configuration Manager.
Configuring the database
To get your staging server to work properly, do the following:
1.Ensure that the <wcs_install_path>\bin and <db2_install_path>\sqllib\bin are
in the PATH environment variable.
2.Configure both the production database and the staging database with the
following DB2 commands:
db2 update db cfg for db_name using STMTHEAP 60000
db2 update db cfg for db_name using LOCKLIST 512
db2 update db cfg for db_name using LOGPRIMARY 80
db2 update db cfg for db_name using LOGBUFSZ 512
db2 update db cfg for db_name using DBHEAP 2048
db2 update db cfg for db_name using APPLHEAPSZ 2048
db2 update db cfg for db_name using PCKCACHESZ 640
db2 update db cfg for db_name using STAT_HEAP_SZ 2048
db2 update db cfg for db_name using APP_CTL_HEAP_SZ 4096

320
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
3.Increase the buffer pool size to improve performance.
Decide on your buffer pool size based on your database size and available
memory. Run the following command to change the default buffer pool size,
where
n
is the size of the buffer pool you have chosen:
db2 connect to db_name
db2 alter bufferpool IBMDEFAULTBP size n
db2 terminate
4.Authorize the user that will execute the stage copy utility and stage propagate
utilities must have database administrator authority.
Stage copy utility
The stage copy utility copies the data from the production database to a staging
database.
These are some options that you should be aware of before using the
stagingcopy command:
cleanup_stage_db option
You can choose to copy data from site-related tables, merchant-related
tables, or individual tables. You can specify if you want to clean your staging
tables before copying using the cleanup_stage_db option. Specifying yes for
this option means the stage copy utility will clean all the staging tables before
copying. This may impact other tables because it uses delete cascade. If you
specify this option as no, the stage copy will not delete anything before
copying. This may cause copy failure, due to conflicts such as duplicate
primary keys or unique indexes. The best option is specifying only for this
option, so that the stage copy utility will clean only the staging database.
Important: You will need to restart both the production and staging server
machines so that the preceding changes will take effect. We recommend that
you do these configurations before having a store in production.
Note: Before executing the stage copy utility, we recommend backing up
your production database.

Chapter 12. Catalog management
321
scope option
The stage copy utility and the stage propagate utility divides the database
data into two scope levels: site-related and merchant-related. The site scope
includes the data common to all merchants, such as language, country and
currency used by the system. The merchant scope is for data limited to
individual merchants, such as store information, catalog information, product
information, and so on. If you set the scope to all, the stage copy utility will
copy the site data, followed by all the merchant data.
script_file option
If this option is set, the stage copy utility generates an SQL script file that
uses export and import to copy the production data to the staging database.
You can specify a table to clean or copy by using the dtable parameter. But
be aware that this table could be related to other tables, so if you ask to clean
the specified table, all the child tables may be cleaned by a delete cascade.
You should copy the parent table before copying this table. Otherwise, your
copy or clean will fail.
Stage propagate utility
After the stage copy utility, you should stop and restart your staging server before
beginning any modifications.
Now you can perform your tests on the staging server machine. You can test new
functions, perform integration and stress tests, and so on. Once this is done, you
are ready to propagate the data to the production database.
The stage propagate utility moves the data from the staging database to the
production database. This utility uses the STAGLOG table to identify which
records have changed in the staging database and what kind of change (insert,
delete or update) was made, then it updates these records in the production
database. Remember that the utility does not copy or propagate any files (HTML,
Note: You cannot copy the merchant data without copying the site data
first. If you do so, your copy may fail due to a mismatch between the
foreign and primary keys.
Note: For additional information, refer to the following:
Store Developer: Creating a Store Using the Store Services product guide
IBM WebSphere Commerce Suite V5.1 online documentation

322
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
JSP, image files, for example), so you should copy these files manually. If you
change the database schema, for example if you create a new column, table or
view in the staging database, you need to do this change manually in the
production database before propagating data.
As with the stage copy utility, you can specify the scope during the stage
propagate utility by using the scope option.
Specify “site” to propagate all the site-related tables. Specify “merchant” to
propagate only the merchant data to the production database. Specify all if you
want to propagate all data, site and merchant tables.
Using the dtable option, will can propagate a specific table from the stage
database to the production database. Ensure that you propagate the parent table
before you propagate the specific table.
If you propagate files for any reason, the propagation rolls back the old
production data, so your production database will be the same as before.
You can also propagate customized tables, as described in “Using staging server
with customized tables” in the IBM WebSphere Commerce Suite V5.1 online
documentation.
Examples using staging server commands
In the following examples, we use a staging session and show how to use the
stagingcopy command, make some changes in the staging database, and then
show how to propagate the changes to the production database by using the
stagingprop command.
Copying data to the staging server
To copy the site-related data from the production database to the staging server,
do the following:
1.Configure the database as described in “Configuring a staging server” on
page 319.
2.Open a command window and change to the directory where you want log
files to be written.
3.Type the following command:
stagingcopy -scope _site_ -sourcedb <production_database_name> -destdb
<staging_database_name> -sourcedb_user <production DBA user>
-sourcedb_passwd <production DBA password> -destdb_user <staging DBA user>
-destdb_passwd <staging DBA password>
4.Examine the stagingcopy_yyyy.mm.dd_hh.mm.ss.zzz.log to verify if the
command was successful.

Chapter 12. Catalog management
323
After using the stage copy utility, you should stop and restart your staging server
before beginning any modifications to the database.
Loading database changes
For testing purposes, we have loaded data as described in Appendix B, “Loader
package” on page 539.
Propagating data to the production server
To propagate the site-related data from the staging database to the production
servers:
1.Start a command window and change to the directory where you want log
files to be written.
2.Type the following command:
stagingprop -scope _site_ -sourcedb <staging_database_name> -destdb
<production_database_name> -sourcedb_user <staging_DBA_user>
-sourcedb_passwd <staging_DBA_password> -destdb_user <production_DBA_user>
-destdb_passwd <production_DBA_password>
Examine the stagingprop_yyyy.mm.dd_hh.mm.ss.zzz.log to verify if the
command was successful.
12.3 Data management
Data management within this section refers to managing the adding and
removing of products and items from the store database. We have included
examples to add and remove products.
12.3.1 Add products, items, and offer price
Appendix B, “Loader package” on page 539 gives an example of the catalog data
load. In this section we will go through the import XML file (catalog.xml) and
describe all elements needed to add a single product to the database.
Note: You can find more examples in the Store Developer: Creating a Store
Using the Store Services product guide.
Note: The stage propagate utility cannot propagate records loaded by the
Loader (load mode) or the DB2 load utilities, since both bypass the staging
triggers. We recommend the use of sqlimport mode when using the loader.

324
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
1.Resolve the reference number of the store entity that is needed when a
product will be associated with the store entity:
<storeent
storeent_id="@storeent_id_1"
identifier="&STORE_NAME;"
type="S"
member_id="&MEMBER_ID;"
/>
The STORE_NAME and MEMBER_ID are macros stored in
DBLoadMacros.dtd.
2.Resolve the catalog ID that is going to be updated by a new product:
<!-- Catalog -->
<catalog
catalog_id="@catalog_id_1"
member_id="&MEMBER_ID;"
identifier="InFashions"
description="In Fashions Catalog"
/>
3.Resolve the catalog group ID to which products will be assigned to:
<catgroup
catgroup_id="@catgroup_id_4"
member_id="&MEMBER_ID;"
identifier="Pants and shorts"
markfordelete="0"
field1="-"
field2="-"
/>
4.Create an entry for product:
<catentry
catentry_id="@product_id_1102"
member_id="&MEMBER_ID;"
catenttype_id="ProductBean"
partnumber="sku-@product_id_1102"
mfpartnumber="sku-@product_id_1102"
Note: A catalog.xml file is included in the additional material SG24618.zip file.
After being unzipped, place it in the <unzip_path>\sg246180\catalog directory.
Note: If you need to assign the product to the new category, change the
identifier to “My new category”. Then assign “My new catogory“ to the top
or to parent category. This relationship is kept in CATGRPREL table.

Chapter 12. Catalog management
325
mfname="InFashion"
markfordelete="0"
buyable="1"
/>
5.Create an entry for item:
<catentry
catentry_id="@catentry_id_1105"
member_id="&MEMBER_ID;"
catenttype_id="ItemBean"
partnumber="sku-1105"
mfpartnumber="sku-1105"
mfname="InFashion"
markfordelete="0"
buyable="1"
/>
6.Associate the item with the product:
<catentrel
catentry_id_parent="@product_id_1102"
catreltype_id="PRODUCT_ITEM"
catentry_id_child="@catentry_id_1105"
sequence="1"
quantity="1"
/>
7.Create a product’s description. This description is used by the
CategoryDisplay and ProductDisplay commands.
<catentdesc
catentry_id="@product_id_1102"
language_id="&en_US;"
name="khakis"
shortdescription="Khakis"
longdescription="These stylish khakis are loose fit for extra comfort.
They are machine washable."
thumbnail="images/mens_pants_cords_sm.gif"
fullimage="images/mens_pants_cords.gif"
available="1"
published="1"
/>
8.Create a item’s description. For example this description is used by the
OrderItemDisplay command.
<catentdesc
Note: Only items can be ordered, but every item is associated with a
product.

326
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
catentry_id="@catentry_id_1105"
language_id="&en_US;"
name="khakis"
shortdescription="Khakis"
longdescription="These stylish khakis are loose fit for extra comfort.
They are machine washable."
thumbnail="images/mens_pants_cords_sm.gif"
fullimage="images/mens_pants_cords.gif"
auxdescription1="&lt;b&gt;Size: &lt;/b&gt;29W x 32L &lt;b&gt;Color:
&lt;/b&gt;Brown "
available="1"
published="1"
/>
9.Create one or more new attributes:
<attribute
attribute_id="@attribute_id_1103"
language_id="&en_US;"
attrtype_id="STRING"
name="Size"
sequence="0"
description="Size"
catentry_id="@product_id_1102"
description2="Waist and leg sizes"
field1=" "
/>
10.Create an attribute’s value entry:
<attrvalue
attrvalue_id="@attrvalue_id_1111"
language_id="&en_US;"
attribute_id="@attribute_id_1103"
name="29W x 32L"
attrtype_id="STRING"
stringvalue="29W x 32L"
sequence="0"
catentry_id="@catentry_id_1105"
/>
11.Create offer, offer price and list price for the item:
<offer
offer_id="@offer_id_1105"
startdate="2000-06-19 16:26:17.784691"
catentry_id="@catentry_id_1105"
precedence="0"
published="1"
identifier="1105"
flags="1"
tradeposcn_id="@tradeposcn_id_101"

Chapter 12. Catalog management
327
/>
<offerprice
offer_id="@offer_id_1105"
currency="USD"
price="25.00"
compareprice="25.00"
/>
<listprice
catentry_id="@catentry_id_1105"
currency="USD"
listprice="25.00"
/>
12.Accociate the product and item to the store:
<storecent
storeent_id="@storeent_id_1"
catentry_id="@product_id_1102"
/>
13.Resolve fulfillment ID, which is needed for inventory entry:
<ffmcenter
ffmcenter_id="@ffmcenter_id_1"
member_id="&MEMBER_ID;"
name="InFashion Home"
/>
14.Create inventory entry.
<inventory
catentry_id="@catentry_id_1105"
quantity="100"
ffmcenter_id="@ffmcenter_id_1"
store_id="&STORE_ID;"
quantitymeasure="C62"
inventoryflags="0"
/>
12.3.2 Remove products
If you plan to remove products or items from your catalog, you have the following
options:
Note: List prices are static descriptive prices that are associated with a
catalog entry. List prices cannot be used for order processing. You must
create an offer in order to add merchandise to a shopping cart or to
process orders.

328
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
1.Unpublish item by setting CATENDECS.PUBLISH field to 0. This will disable
adding the item to shopping basket.
<catentdesc
catentry_id="@catentry_id_1105"
language_id="&en_US;"
name="khakis"
shortdescription="Khakis"
longdescription="These stylish khakis are loose fit for extra comfort.
They are machine washable."
thumbnail="images/mens_pants_cords_sm.gif"
fullimage="images/mens_pants_cords.gif"
auxdescription1="&lt;b&gt;Size: &lt;/b&gt;29W x 32L &lt;b&gt;Color:
&lt;/b&gt;Brown "
available="1"
published="0"
2.Mark the product for deletion by setting CATENTRY.MARKFORDELETE field
to 1. After this update the product will not be displayed by the
CategoryDisplay command.
<catentry
catentry_id="@product_id_1102"
member_id="&MEMBER_ID;"
catenttype_id="ProductBean"
partnumber="sku-@product_id_1102"
mfpartnumber="sku-@product_id_1102"
mfname="InFashion"
markfordelete="1"
buyable="1"
/>

© Copyright IBM Corp. 2001
329
Chapter 13.
Order customizations
In the course of the shopping process, after shoppers or customers find the
products they are interested in buying, they order those products. Ordering
consists of the collection of billing and shipping information, allocation of
inventory, calculation of prices, calculation of taxes, calculation of shipping and
handling charges, determination of payment method, authorization of payment,
generation of orders, and acknowledgment of orders.
Customizations of a B2C store are often needed for orders. In this chapter we
describe the order subsystem, and provide several common customizations for
orders.
The chapter is organized into the following sections:
Order subsystem overview
Customization example
Use case 1: reorder
Use case 2: set scheduled orders
Use case 3: browse/delete scheduled orders
13

330
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
13.1 Order subsystem overview
The order subsystem is a component of the WebSphere Commerce Server that
provides shopping carts, order processing, and management function support.
Related services, such as pricing, taxation, payment and fulfillment, are also part
of the order subsystem. Order processing capabilities include quick order or buy,
scheduled orders, multiple pending orders, and reorders.
Order and order item
A customer order is a list of selected products. Each product on that list is an
order item. From the store perspective, an order is a list of order items that are
part of the store's data.
Each order item represents something that a customer has selected for
purchase. In addition, each order item has a reference to an offer, a contract, a
shipping mode, and a fulfillment center. Discounts and shipping charges are
stored with each order item, although tax amounts are stored with the order.
OrderItems in the order object are grouped to form SubOrders. OrderItems in a
SubOrder object have the same shipping address, so that shipping charges for
each suborder are calculated separately. A currency identifier is associated with
the order.
Order subsystem object model
Figure 13-1 displays the relationships between entity beans related to an order.

Chapter 13. Order customizations
331
Figure 13-1 Order object model - order view

332
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Additional order object models are as follows:
Calculation code view
– Attachment
– Discounts
– Shipping
– Taxation
Language-specific objects view
Member owned entities view
Offer view
Order view
Order adjustment view
Order taxation view
Site level view
Store entities for currency view
Store entities for language view
Store entities for quantity unit view
Store user view
These object models are documented in the IBM WebSphere Commerce Suite
V5.1 online documentation.
Shipping mode
Shipping mode information can be defined either at the store level or the store
group level. Typically, the customer can choose the shipping mode, which
includes the shipping carrier and the shipping method for delivering the order.
Before a shipping mode can be used in a store, shipping arrangements must be
created for that store and the fulfillment centers that can ship using that shipping
mode.
Discounts and discount codes
A discount code is associated with a product to calculate a discount based on
some predefined usage rules.

Chapter 13. Order customizations
333
Two dimensions are involved in attaching a discount code to a product or a group
of products. First, the discount can be attached to one or more catalog entries,
and catalog groups. Attaching a calculation code to a catalog group has the
same effect as attaching it to all the catalog entries directly in the catalog group.
Second, the order items are grouped for calculation in one of three ways: per
contract, per product, or per offer.
Tax code
A tax calculation code indicates the tax calculation for order items. A store
typically collects two types of taxes: sales or use tax, and shipping tax. The tax
codes are unique within each tax type for a store. Only one tax calculation code
of each tax type is applied to a particular order item.
Tax calculation codes may be classified into tax code classifications for
convenience. A tax code scheme consists of a group of tax code classifications.
A store typically uses a single tax code scheme.
Offer
Offers present different prices for the same product to different customers. An
offer is also known as a trading position. An offer represents the price of a
catalog entry and any criteria that the customer must satisfy in order to pay that
price. The Offer object has a quantity range attribute, used for specifying the
minimum or maximum quantity, or both, that may be sold in an order under the
given offer, a date range, and the member groups of the trading position
container for the offer. For an offer to apply, the customer must make the
purchase during the time when the Offer object is valid.
URL commands
The order subsystem includes all logic and data relevant to placing, processing,
and managing orders. Table 13-1 lists the commands for the order subsystem.
Table 13-1 Order subsystem commands
Command name Description
OrderCancel Cancel the specified order by changing its order
status to X.
OrderCopy Create, merge, or modify pending orders.
OrderDisplay Display the contents of the specified order.
OrderList Display a list of the customer's orders.
OrderPrepare Prepare an order by calculating the composition of
the order, the shipping charges, and the applicable
taxes.

334
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
13.1.1 Order state diagram
When a user finds the products he is interested in, and adds the product to the
shopping cart, an order is created.
We will explain the order process through the state diagram of the object Order
as seen in Figure 13-2. The state diagram includes the features of the state. The
state transition event is the URL command called by the user or external events
such as MQSeries or Payment Manager.
OrderProcess Process a submitted order.
OrderProfileUpdate Create or update a customer's default billing and
shipping addresses, shipping mode and
payment information.
OrderSchedule Submit a recurring order, which will be processed by
the Job Scheduler.
OrderUnlock Unlock an order that was previously locked by the
OrderPrepare command.
ScheduledOrderCancel Cancel execution of a recurring order submitted by
the OrderSchedule command.
SetCurrencyPreference Set the currency preference for the user running this
command.
SetPendingOrder Set a pending order as the current pending order.
OrderItemAdd Add items or products to the list of items that are to
be shipped.
OrderItemDelete Delete an ordered item from a pending order.
OrderItemDisplay List all order items that are in pending status.
OrderItemUpdate Update products and items in the existing order list.
GetPaymentInfo Obtain the credit card number, credit card brand and
credit card expiration date.

Chapter 13. Order customizations
335
Figure 13-2 Order state diagram
Pending (P) - created order
The pending state is the default state an order is created in. When in pending
state users can modify quantities, addresses, and even cancel the order.
The command responsible for the creation of a new order in pending state is
OrderItemAdd. The command does the following for each product or item and
quantity that is provided:
The product or item is ignored if the input product reference number is
non-numeric.
The quantity is checked and an error is generated if the quantity is not valid.
Compiles the list of orders for processing. The current pending orders are
obtained, if needed. If a new order is requested or no current pending orders
exist, or there are no existing pending orders for a particular store, a new
order will be created.
From the list of pending orders retrieved for a specific user there is one that is
the default order for the shopper. If not specified other orderId products will be
added to the default pending. Information about current pending order is
contained in the CPENDORDER table, which stores the relationship of an
order, member and store.

336
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
To manage a default order for a customer, you need to use the
SetPendingOrder URL command, which marks or unmarks orders according
to needs.
OrderItemAdd does the following for each order in the list:
– If the order is in a pending state, the command unlocks it and updates the
timestamp.
– Calls the CheckInventoryCmd task command to ensure a sufficient
amount of inventory exists for the specified product or item.
Inventory information is stored in the INVENTORY table. In this table it is
possible to control WebSphere Commerce Suite inventory check behavior
by setting the proper value in the INVENTORYFLAGS column.
The default value is 0, with full inventory check and update. If a product
has the value 1 in this column its inventory level will not be updated. If it
has 2, its inventory level will not even be checked.
– Creates an order item entry containing the specified quantity of the
product or item.
– The store shipping mode, comment, field1 and field2 information is
inserted when the order item entry is created.
OrderItemAdd command does the following for each order item that has been
created or updated:
– Calls the GetBaseUnitPriceCmd task command to get the special price of
the product or item.
– Calls the ExtendOrderItemProcessCmd task command to perform
additional processing to meet any unique requirements. For example,it
checks the validity of the address book reference number and updates it, if
necessary. If the shopper creates a shipping association and then updates
the address book entry, an error will occur.
If the addressId parameter is not supplied for a register user, the default will
be the addressId in the ADDRESS table (where the STATUS column has a
value of P and the value in the NICKNAME column is the user's login ID
obtained from the LOGONID column in the USERREG table). If no row exists
in the ADDRESS table, the addressId will be NULL for the order item in the
ORDERITEMS table.
Note: If you set more than one current pending order for a customer with the
command SetPendngOrder, when the OrderItemAdd command is called, it will
add the item to all the current pending orders listed in the CPENDORDER
table for the specified customer.

Chapter 13. Order customizations
337
Calls ResolveFulfillmentCenter and GetBaseUnitPriceCmd task commands.
After all products and items are processed, calls the URL that is specified.
The call to the OrderItemUpdate command causes a transition that ends in the
same state. Actually a pending state can be composed of two substates as seen
in Figure 13-3.
Locked: order is ready to be processed by the OrderProcess command.
Transition to a state other than P is only possible if order is in this substate.
Unlocked: order has to be prepared. This could happen because of time (the
time in QUOTEFORGOOD column in STORE table has expired) or because
the OrderUnlock command has been submitted.
Figure 13-3 Pending state and substates
QuickOrderProfile (Q)
An order can be created in status Q. This is not a real order. It has no taxes and
items, but is used as an order profile for quick orders. An order in status Q cannot
be submitted. The transition in this state in caused by UpdateProfileView
command, which creates or updates the order profile depending on whether a
previous profile exists.
Cancelled (X)
The OrderCancel command cancels the specified order by changing its order
status to X. This command does not remove the order from the database. An
order can be cancelled any time but only if it is in the pending state (P).
Low inventory (L)
In this state there is at least an item in the order that has a low inventory level;
however, payment is started and if successful, the order can pass to status
confirmed (C).

338
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Order submitted (M)
The order has been submitted by the user, but payment is not initiated. In this
case WebSphere Commerce Suite passes control of the order to an external
tool, such as Payment Manager, to process payment. From this state there is a
transition to Payment Initiated (I) state.
Payment Initiated (I)
In this state, a payment is being processed and WebSphere Commerce Suite is
waiting to pass the order status to confirmed (C).
The transition to status C depends on the response of the tool used for payment
processing.
Confirmed (C)
An order in status confirmed (C) has completed all the process inside
WebSphere Commerce Suite, payment has been completed, and inventory has
been updated.
The event that causes transition from pending to another state (except to be
cancelled) is the submission of the OrderProcess command which:
Ensures that the shopper invoking the command owns the order.
Ensures that the order is pending and locked. This means that before being
processed, the OrderPrepare command, which prepares an order by
calculating the composition of the order, the shipping charges, and the
applicable taxes, needs to be called.
Once the order is ready to be processed then OrderProcess does the following:
Updates inventory: this task can be performed by UpdateInventoryCmd or by
the DoPaymentCmd task command if it implements the DoInventory
interface.
Calls the appropriate DoPaymentCmd task command to perform additional
error checking and to process the payment. All other parameters specified
with the OrderProcess command are passed to the DoPaymentCmd task
command for processing, if appropriate.
Additional processing can be performed by the ExtOrderProcessCmd task
command.
Note: In the default implementation, Payment Manager will update the status
of the order if the payment is successful. If payment fails, the order status will
not be updated and remains in the status I (payment initiated).

Chapter 13. Order customizations
339
The resulting status depends on the DoPaymentCmd return. If this command
returns a null or empty order state, the order status is set to C. The other values
are:
– M: the shopper has initiated payment. UpdateInventory succeeded.
– I: the shopper has submitted the Order, but has not yet initiated payment
– L: the shopper has initiated payment. UpdateInventory failed. This could
happen when WebSphere Commerce Suite checks inventory level for a
specified product and there is not enough to be delivered.
Shipped (S)
Once the order has been confirmed shipment begins. WebSphere Commerce
Suite provides a status (S) for orders completely shipped. Additional values can
be added (for example, to indicate partial shipment).
13.1.2 Common order customizations
WebSphere Commerce Suite order subsystem can be customized to meet
customer requirements.
We have included some typical order customizations and when possible, we will
reference external resources that can help WebSphere Commerce Suite
architects and developers. We will also explain a typical order customization,
repeated orders, and scheduled orders to show all of the development and
deployment steps.
Shipping customization
Shipping customization is performed to add shipping provider and prices to a
store.
Tax customizations
Taxware and Cyber Source are external solutions used for tax calculations and
customizations of a store. For example:
en_US product, tax, total, ship cost, grand total
de_DE product, total, ship cost, tax (all), grand total
Default implementation of tax in Commerce Suite
WebSphere Commerce Suite collects two type of taxes: sales or use tax, and
shipping tax. The tax codes are unique within each tax type for a store. Only one
tax calculation code of each tax type is applied to a particular order item.

340
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Tax calculation codes may be classified into tax code classifications for
convenience. A tax code scheme consists of a group of tax code classifications.
A store typically uses a single tax code scheme.
TaxCategory objects correspond to the different kinds of taxes a store may be
required to collect, such as federal, state or provincial, and municipal. Taxes for
each TaxCategory object are calculated in ascending sequence by their
sequence attributes.
The tax CalculationCodes are unique within each TaxType in a StoreEntity. No
more than one tax CalculationCode of each TaxType can apply to any particular
order item. Typically, sales or use tax is levied on the net price, and shipping tax
is levied on shipping charges. However, it is possible to calculate sales or use tax
on the net price plus the shipping charges, by using the appropriate
CalculationScaleLookupMethod. If you do this, you should either establish a
default shipping tax calculation code that calculates zero shipping tax, or disable
the shipping tax TaxType entirely by removing the corresponding row from the
STENCALUSG database table.
A tax code may be attached to online catalog entries or to a catalog group. When
attached to a catalog group, it has the same effect as a tax code attached to all
the catalog entries directly in that catalog group. However, if an entry has more
than one tax calculation code of a particular TaxType object attached, only the
code with the lowest sequence attribute is used.
A particular tax calculation code can have several CalculationRules, one for each
combination of TaxCategory object, TaxJurisdictionGroup object, and
FulfillmentCenter object identified in the TAXJCRULE database table. When a
shipping address matches more than one TaxJurisdictionGroup, the
CalculationRule object with the highest associated TAXJCRULE.PRECEDENCE
column value is used.
Tax Integration Interface Kit
In today’s global marketplace, managing e-commerce sites not only means
keeping pace with international trends, but adapting to the unique cultural,
business and financial needs of customers throughout the world.
If the customer has the option to view the tax at the beginning of the shopping
experience prior to adding the product to the shopping cart, the tax is calculated
based on the customer’s registration information or the merchant’s location, and
the tax is displayed on the product information page. This option depends on the
specific merchant’s store configuration.

Chapter 13. Order customizations
341
The Tax Integration Interface Kit is available for all IBM Software Partners who
want to enable WebSphere Commerce Suite for integration with a third-party tax
application to build a robust and secure, tax-compliant e-commerce site. The Tax
Integration Interface Kit installs the Tax Integration Interface, the component that
communicates with the Tax Integration Feature specific to an external tax
application.
With an integrated Commerce Suite and third-party tax application solution, you
may be able to do any of the following:
Calculate federal, state, county, and city sales and consumption taxes on
products purchased and shipped anywhere within the United States and
Canada
Calculate VAT, GST, sales and consumption taxes for multiple countries,
including cross-border trade
Adapt to multiple taxation laws, fluctuating currency logistics and payment
regulations
Automate and monitor tax exemption processing, with online access to proof
of compliance
Create and manage audit trails compliant with state and federal regulatory
requirements
Create an end-to-end shopping flow, from point of purchase to fulfillment,
payment and settlement
Third-party tax application
Commerce Suite includes a Tax Integration Interface for third-party tax
applications to process tax information for a customer’s purchases.
1.The customer uses a browser to access the merchant’s online store, browse
the store catalog, view products on the product display pages, and add items
to the shopping cart.
2.When the customer views the shopping cart page after adding one or more
items to the shopping cart, a request is sent to the Web server that invokes
the OrderPrepare controller command.
3.The OrderPrepare command calls the ApplyOrderTaxesCmd task command.
Its default implementation class, ApplyOrderTaxesCmdImpl, is overridden by
the ApplyOrderTaxesTIKCmdImpl implementation class (which is part of the
Tax Integration Interface), and does the following:
a.Creates a TaxOrderCmd task command, which will instantiate the
configured implementation, based on entries in the Commerce Suite
CMDREG table. There is no default implementation.

342
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
b.For every order item in the shopping cart, creates a TaxOrderItemCmd
task command, which will instantiate the configured implementation,
based on entries in the Commerce Suite CMDREG table. There is no
default implementation. The TaxOrderCmd addOrderItem method adds
each TaxOrderItemCmd command to the TaxOrderCmd command. During
this process, the audit flag for each order item by default is set to off.
c.Invokes the TaxOrderCmd calculateTaxes method to calculate the tax.
d.Updates the ORDERITEMS table in Commerce Suite with the tax, using
Commerce Suite’s OrderItemAccessBean. The tax may be displayed on
the shopping cart page to the customer.
4.If the customer submits the items in the shopping cart for purchase, another
request is sent to the Web server, but this time, to invoke the OrderProcess
task command.
5.The OrderProcess task command calls the ExtOrderProcessCmd task
command. Its default implementation class, ExtOrderProcessCmdImpl, is
overridden by the TaxOrderAuditTIKCmdImpl implementation class (part of
the Tax Integration Interface). The TaxOrderAuditTIKCmdImpl implementation
class performs the same functions as ApplyOrderTaxesTIKCmdImpl (see
Step 3) except that for every order item, the audit flag is set to on.
6.After the tax is calculated and the OrderItemAccessBean updates the
ORDERITEMS table, the tax may be displayed on the checkout page to the
customer.
For more detailed information on the Tax Integration Interface Kit, please refer to:
http://www-4.ibm.com/software/webservers/commerce/wcs_pro/downloads.html
A third-party tax calculation tool can allow the merchant to use a pre-built
calculation logic and avoid customization.
An example of such a tool is Taxware, which provides calculation and reporting
of Value Added Tax (VAT), Goods and Services Tax (GST), sales tax and
consumption tax, keeping rules up to date as legislation changes.
Another product is WORLDTAX System product, which is useful for countries
outside the US (mainly European).
For more information on Taxware, please refer to:
http://www.taxware.com
Order cancel/return
Cancel - cancels items added to the shopping cart (OrderCancel prior to
OrderProcess)

Chapter 13. Order customizations
343
Return - After the order has been processed (OrderProcess) it is considered a
return (for example, sent to back-end fulfillment, already shipped to customer)
Quick order
Refer to the Web Fashion sample store documentation.
Bonus points
Refer to the IBM WebSphere Commerce Suite V5.1 Programmer’s Guide.
Multiple shopping carts
WebSphere Commerce Suite V5.1 allows customers to have multiple shopping
carts (multiple pending orders). Information about users and orders is kept in the
CPENDORDER table (see Table 13-2).
Table 13-2 CPENDORDER table
For each customer there is an entry in the CPENDORDER table that defines the
default pending order for the shopper (that is, the default shopping cart).
A list of all pending orders for a current user can be retrieved by the
OrderListDataBean; this is useful if you want to give your customer separate
shopping carts (i.e. for books and for CDs). You can in that case mark different
shopping carts for different purposes by using a custom field (for example field1).
Association between pending orders and products can be performed by
associating catgroups with orders.
The creation of a new order depends upon whether there is already a pending
order for that kind of product.
Column name Column type Column description
ORDERS_ID BIGINT NOT NULL The order
STOREENT_ID INTEGER NOT NULL The store
MEMBER_ID BIGINT NOT NULL The shopper
FIELD1 INTEGER NULL Merchant cust
FIELD2 VARCHAR(254) NULL Merchant cust

344
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
13.2 Reorder example
The reorder of products from past orders is a common function offered to
registered shoppers. This section describes the reorder example requirements,
solution outline, and the use cases for each solution design.
13.2.1 Summary of ITSO store requirements
The ITSO store requirements for registered shoppers are as follows:
View the list of all past orders
View details of all past orders
Set an order as the default template for future reorders
Place an order based on the template
Browse the current scheduled orders and delete
Schedule repeated orders
13.2.2 Solution outline
From the account main page, a user can choose to view his past orders, and are
shown a list of the submitted orders with the current status. It is possible, from
the TrackOrderStatus page, to select an order and to see the order details. From
the order details page, it is possible to set the order as the default template order
for reorders.
From the main account page, a user can see their order template and can submit
an order by copying that template. It is also possible to set a scheduler to submit
the same reorder for the desired frequency and see the scheduled orders
existing for the time specified. Figure 13-4 shows the navigation flow of the
solution.

Chapter 13. Order customizations
345
Figure 13-4 Reorder navigation flow
From the requirements and problem statement, we have identified three
important use cases:
Reorder
Order schedule
Scheduled order deletion
For a detailed description of use cases, please see Appendix A, “Use cases” on
page 531.
The base ITSO store was created from the Web Fashion sample store, so we
can identify the functions that are supported by the base store implementation.
Data model
Figure 13-5 shows how the order subsystem and job scheduler data is organized
in the database (tables regarding tax and prices have been deleted to make the
schema more readable).
Main
account
Order status
View
orders
These pages can be
accessed fromany page
in the site
Reorder/
Schedule
Schedules
View
detail
View
schedules
Schedule
orders
View
schedules

346
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 13-5 Order subsystem and job scheduler data model
We will work mainly on the following tables:
ORDER: each row in this table represents an order in a store
SCHORDERS: this table contains the entries for scheduled orders
SCHCONFIG: this table contains all the scheduled job entries (not only
orders)
Table 13-3 shows the ORDERS table and the columns used in this
customization. The ORDERS table references the MEMBER table by
MEMBER_ID column. Zero or more orders can belong to only one user
(member).
Table 13-3 ORDERS table
Column name Column type Column description
ORDERS_ID BIGINT NOT NULL Generated unique key.
MEMBER_ID BIGINT NOT NULL The shopper this order is for.

Chapter 13. Order customizations
347
Table 13-4 shows the SCHCONFIG table and the columns used in this
customization. The MEMBER_ID column references the MEMBER table.
SCCJOBREFNUM is the primary key and is referenced by SCHORDERS table.
SCCACTIVE indicates the status of the job, the default status is A (active), while
another status is D (deactive). SCCINTERVAL indicates the number of seconds
between successive executions of this order.
Table 13-4 SCHCONFIG table
STATUS CHARACTER (1)
NULL
Order status:
P-pending-the shopper can modify this
Order.
X - canceled - the order has been canceled.
I - submitted - the shopper has submitted
the order, but has not yet initiated payment.
M - payment initiated - the shopper has
initiated payment. UpdateInventory
succeeded.
L - low inventory - the shopper has initiated
payment. UpdateInventory failed.
C - complete - payment has been
authorized.
S - shipped - the order has been shipped.
Q - quick order profile - the order cannot be
submitted. It contains default information for
a shopper such as shipping address and
payment information that can be copied
when creating a new pending order.
Other values are possible. Uppercase
letters are reserved by IBM.
Column name Column type Column description
MEMBER_ID BIGINT NOT NULL Owner of the scheduled
job
SCCACTIVE CHARACTER (1)
NOT NULL, DEFAULT 'A'
Owner of the scheduled
job
SCCINTERVAL INTEGER
NULL
Job reschedule interval in
seconds
SCCJOBREFNUM BIGINT
NOT NULL
Job reference number
Column name Column type Column description

348
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Table 13-5 shows SCHORDERS table that links ORDERS table and
SCHCONFIG table.
Table 13-5 SCHORDERS table
Job scheduler
The job scheduler is a component of WebSphere Commerce Server primarily
used to schedule and launch jobs based on a timing scheme. Each scheduled
job runs as a separate thread, and multiple jobs can be scheduled to run
simultaneously. A job is a Commerce Suite command scheduled to run at a
specified time or interval. Timing is specified by the AddJob command's start and
interval parameters for job execution. Job tracking information, including the job
start time, end time, and results, are maintained in the database.
Multiple commerce servers or clones can connect to the same database. When a
job is added to the SCHCONFIG scheduler table, the job can be scheduled to
run on any of the WebSphere Commerce Servers or clones. The job scheduler is
scalable across one or more threads, running on one or more machines. The
SCHSTATUS job status table contains at least one record for every job in the
SCHCONFIG table. The job scheduler polls for new jobs based on the
parameters specified in the configuration file.
You can add the auto clean job to the scheduler, which cleans up jobs from the
job scheduler status table based on time stamp or job reference number. With
heavy scheduler use, the scheduler status table grows considerably large and
auto clean trims the size of the table. Auto clean will not log the job instance entry
in the job scheduler status table when the job completes successfully.
Application partitioning groups heavily running jobs together to avoid overloading
the scheduler server. Jobs are grouped by specifying the application type in the
SCHCONFIG table and the number of threads assigned to execute the job. A
fixed number of threads are assigned to each application group.
If a job is registered as a broadcast job, the job will run only once on all clones or
WebSphere Commerce Servers that are connected to the same database.
Status is logged in the SCHBRDCST database table.
For more information about using the job scheduler, refer to the IBM WebSphere
Commerce Suite V5.1 online documentation.
Column name Column type Column description
JOB_RN BIGINT NOT NULL Scheduled job reference
number
ORDERS_ID BIGINT NOT NULL Scheduled order ID

Chapter 13. Order customizations
349
13.3 Use case 1: reorder
In this use case, the customer browses the orders he has submitted in the past,
and decides to place a new order based on a previous order.
Prerequisites
WebSphere Commerce Suite installation must have been completed and the
ITSO store created using Web Fashion as the store template
(WebFashion.sar)
WebSphere Studio must be installed and configured to run in a WebSphere
Test Environment
VisualAge for Java must be installed and configured to run Web Fashion in
WebSphere Test Environment
Implementation overview
The ITSO store has been created based on Web Fashion, and has already
implemented the order status view, which allows the browsing of a user’s past
orders, including the ability to see the details of the orders.
Component Identification
From Web Fashion documentation and IBM WebSphere Commerce Suite V5.1
online documentation, we have identified the components for this use case and
listed them in Table 13-6.
Table 13-6 Reorder use case components
Component study
OrderDetail.jsp and detail.jsp
Functional limitations: The standard JSP displays order details, but does not
allow for placing an order based on a previous one.
Action to be taken: To allow a user to place the order based on a previous
order, we have to modify the JSP. The OrderDetail.jsp displays the details of a
selected order. To enable order schedule (next use case) we decided to move
the contents of this JSP to a new JSP called detail.jsp and to include it with
Commands JSPs Property files
OrderDetail OrderDetail.jsp infashiontext_en_US.properties
OrderCopy detail.jsp infashiontext_en_US.properties

350
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
the <jsp:include> directive. This also allows multiple pages to be shown
without modifying the view registry (contained in the VIEWREG table). The
selection of which page to include is based on page parameter that is passed
in calling the command OrderDetail (See Table 13-7).
Table 13-7 Parameter page values and JSPs included in OrderDetail.jsp
Metrics: requires the skill of a Web developer and average estimated time is
one hour.
Changes:
– Move OrderDetail.jsp content to detail.jsp
– Write code to include multiple JSPs in OrderDetail.jsp
– Add command OrderCopy call in detail.jsp
The OrderDetail.jsp and detail.jsp pages are included in the additional materials
zip file.
Example 13-1 TrackOrderStatus.jsp modified code
while (ordersABList.hasMoreElements())
{
next_order = (OrderAccessBean) ordersABList.nextElement();
String orderStatusCode = next_order.getStatus();
//Skip pending, cancelled, Low Inventory and Quick order profile orders.
if (orderStatusCode.equals("P") || orderStatusCode.equals("X") ||
orderStatusCode.equals("L") || orderStatusCode.equals("Q") ||
orderStatusCode.equals("I"))
// Added the line above with the status I
continue;
String nextOrderId = next_order.getOrderId();
//get the date ordered
orderDate = next_order.getPlaceOrderTimeInEJBType();
orderDateString = formatter.format(orderDate);
Parameter page JSP included
detail detail.jsp
schedule orderschedule.jsp
Note: TrackOrderStatus.jsp is the page that lists all past orders, but
unmodified it does not work if there are orders in a status I (payment initiated).
It is required that the code to this JSP must be modified (see Example 13-1) to
add in the if clause the option “I”.

Chapter 13. Order customizations
351
String orderStatus =
infashiontext.getString(orderSFixed.concat(orderStatusCode));
infashiontext_en_US.properties: this file contains the multicultural support of
the store.
Changes: provide translations for all the text that will be added to the JSP.
OrderDetail, OrderCopy: These commands do not require code customization
for our base functionality goals.
– OrderDetail: the parameter page will be added to the command call to
allow the OrderDetail.jsp page to include the right JSP.
– OrderCopy: the most important parameters are (see Figure 13-6 on
page 352):
• fromOrderId_i: specifies zero or more source orders from which order
items will be copied when enumeration group i is processed. We will
set only one order, the one shown in the detail page.
• toOrderId: specifies the order to be created or modified. We will not
use this parameter as its default value is ‘**’ which forces the creation
of a new order for the current user.
• status: specifies the status of the destination order. Only I (submitted)
and P (pending) are valid values. Since the default value is P, we will
not set it.
• URL: The redirection URL that is called when the command successfully
completes. This command will redirect the OrderDisplay command to
allow the user to complete payment with his/her default billing and
shipping addresses.
• copyOrderItemId_i: specifies which order items should be copied from
the source orders specified by fromOrderId_i and added to the
destination order specified by toOrderId. The default value is ‘*‘(all
orderitems).
Note: If you want to allow the user only to fill the shopping cart with the
content of a previous order you can redirect to OrderItemDisplay.

352
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 13-6 OrderCopy command syntax

Chapter 13. Order customizations
353
13.4 Use case 2: set scheduled orders
The use case calls for reorders to be scheduled by the user. The order may be
set as a recursive order by selecting the order to use as a template with the start
time for the order, and frequency.
Prerequisites
WebSphere Commerce Suite installation must be completed and the ITSO
store must be created using Web Fashion as the store template
(WebFashion.sar)
WebSphere Studio must be installed and configured to run in WebSphere
Test Environment
VisualAge for Java must be installed and configured to run Web Fashion in
WebSphere Test Environment
Implementation overview
The Web Fashion sample store, which the ITSO store is built from, does not
provide any pre-built page or functionality to schedule an order. However,
WebSphere Commerce Suite provides a command called OrderSchedule that
allows for interacting with the Commerce Suite Job Scheduler.
Component Identification
The components involved in this use case are shown in Table 13-8.
Table 13-8 Order Schedule use case components
Component study
OrderDetail.jsp and detail.jsp: OrderDetail.jsp is the same modified for
reorder use case
Functional limitations: in Web Fashion there is no JSP that manages
scheduling of orders.
Action to be taken: we need to modify detail.jsp in order to allow user to set
the preferred scheduling parameters (startdate, frequency...)
Metrics: Requires the skill of a Web developer and average estimated time is
one hour.
Commands JSPs Property files
OrderSchedule OrderDetail.jsp infashiontext_en_US.prop
erties
na detail.jsp infashiontext_en_US.prop
erties

354
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
changes: Add OrderSchedule URL command call.
The OrderDetail.jsp and detail.jsp are provided in the additional materials for
this redbook.
Figure 13-7 shows how the order detail view should look.
Figure 13-7 Order details view
infashiontext_en_US.properties: This file contains the multicultural support of
the store
Changes: Provide translations for all the text that will be added to the JSP.
OrderSchedule: this command does not require code customization for our
base functionality goals.
The most important parameters are shown in Figure 13-8.
Note: The detail.jsp page will redirect to schedule.jsp to display the user’s
current schedules. We include information on this JSP in 13.5, “Use Case 3:
browse/delete scheduled orders” on page 355.

Chapter 13. Order customizations
355
Figure 13-8 OrderSchedule command syntax
– URL: The URL to be called when the command completes successfully.
This command will redirect to schedule.jsp, which contains the list of the
current scheduled orders (browse/delete scheduled orders use case).
– orderId: The reference number of the order that needs to be processed as
a recurring order.
– start: The time at which the first execution of this order should occur, in the
format YYYY:MM:DD:hh:mm:ss. Only hh:mm:ss is mandatory. We will not
ask the user to set seconds, but the value will be hardcoded.
– interval: The number of seconds between successive executions of this
order. If omitted, this order will be processed only once.
13.5 Use Case 3: browse/delete scheduled orders
Once setting a recurring order, the user can browse his or her scheduled orders
and can remove one or more scheduled orders.
Prerequisites
WebSphere Commerce Suite installation must be completed and the ITSO
store created using Web Fashion as store template (WebFashion.sar)
WebSphere Studio must be installed and configured to run in WebSphere
Test Environment

356
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
VisualAge for Java must be installed and configured to run Web Fashion in
WebSphere Test Environment
Implementation overview
As in the set scheduled orders use case, Web Fashion does not provide any
pre-built page or functionality to browse scheduled orders. Moreover, there are
no fitting methods to get data from the database. WebSphere Commerce Suite
provides a command, ScheduledOrderCancel, to delete scheduled tasks in the
job scheduler, but we need to create a custom session bean to retrieve
scheduled orders data.
Component identification
The components involved in this use case are shown in Table 13-9.
Table 13-9 Browse/cancel orders schedules use case components
Component study
OrderDetail.jsp and schedules.jsp: OrderDetail.jsp will be used to include the
schedules.jsp
Functional limitations: In Web Fashion there is no JSP to manage the
scheduling of orders.
Action to be taken: We need to create schedules.jsp in order to allow the user
to browse scheduled orders and to delete orders.
Metrics: Requires the skill of a Web developer and average estimated time is
one hour.
Activities:
– Create a new JSP
– Add ScheduleOrderCancel command call
– OrderSchedule access bean call
The completed schedules.jsp can be found in the additional materials zip file
for this redbook.
Figure 13-9 on page 357 shows how the scheduled orders view should look.
Commands JSPs EJBs Properties files
ScheduledOrderC
ancel
OrderDetail.jsp OrderSchedule infashiontext_en_U
S.properties
schedules.jsp

Chapter 13. Order customizations
357
Figure 13-9 Scheduled orders view
infashiontext_en_US.properties: This file contains the multicultural support of
the store.
Changes: provide translations for all the text that will be added to the JSP.
ScheduledOrderCancel: this command does not require code customization
for our base functionality goals.
The most important parameters are as follows (see Figure 13-10 on
page 358):
– URL: The URL to be called when the command completes successfully. In
our case the command will redirect to the same JSP to display the
changes in the list of scheduled orders.
– orderId: The reference number of the scheduled order to be canceled.

358
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 13-10 ScheduleOrderCancel command syntax
OrderSchedule:
Functional limitations: WebSphere Commerce Suite does not provide any
class to get scheduled orders data.
Action to be taken: We need to create a new EJB (session bean) to retrieve
data for the current user. The session bean will extend the BaseJDBCHelper
session bean and will have only one method:
findCurrentScheduledOrdersByMemberId() (see Example 13-2).
Example 13-2 findCurrentScheduledOrdersByMemberId() sample code
makeConnection();
java.sql.PreparedStatement searchSQL =
getPreparedStatement(findScheduledOrdersByMemberSQL);
searchSQL.setLong(1, param_memberId.longValue());
// perform the query
java.sql.ResultSet rs = executeQuery(searchSQL, false);
// process the results of the query
//Declaring a new object ItsoOrder
com.itso.commerce.order.utils.ItsoOrder orderRetrieved = null;
if (rs != null) {
while (rs.next()) {
// read the product ID from the resultset on this row
orderRetrieved = new com.itso.commerce.order.utils.ItsoOrder();
String active = rs.getString("ACTIVE");
orderRetrieved.setActiveFlag(active);
Long member = new Long(rs.getLong("MEMBER"));
orderRetrieved.setMemberId(member);
Integer interval = new Integer(rs.getInt("INTERVAL"));

Chapter 13. Order customizations
359
orderRetrieved.setInterval(interval);
Long order = new Long(rs.getLong("ORDER"));
orderRetrieved.setOrderId(order);
orderList.addElement(orderRetrieved);
}
} else
System.out.println("resultset empty");
//no schedules found!
} finally {
// return the connection to the Commerce Suite data source
closeConnection();
}
return orderList;
}
The method executes the query and stores data in an object ITSOOrder,
which is then added in a vector. The ITSOOrder extends the Hashtable class
and keeps the information needed for our purposes.
Metrics: Requires the skill of a Java-EJB developer and average estimated
time is two hours or more.
Activities:
– Create a new session bean
– Create a new access bean for the session bean
13.6 Deployment of reorder customization
To deploy the reorder customization code:
1.Unzip files in a temp folder.
2.Copy the JSPs from the temp folder to the Web assets directory of the ITSO
store. If you have published the ITSO store (built from Web Fashion) to the
default location, the directory will be:
<wcs_install_path>\stores\web\<store-name>.
Of the five JSPs, three (OrderDetail.jsp, account.jsp, TrackOrderStatus.jsp)
already exist and you should rename the existing ones as .original. The
other two (schedules.jsp and detail.jsp) do not exist in the default installation.

360
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
3.From the temp folder, copy the files ITSOEJBIMPL.jar, ITSOEJBDeployed.jar,
and ITSOCommands.jar to <wcs_install_path>\lib. The first file contains the
implementation classes of the Session bean, the second file contains the
deployed classes and the third contains the utility classes and any custom
commands.
4.Start the WebSphere Application Server Administrative Console.
5.Stop the WebSphere Commerce Server - <instance-name> application
server from the Administrative Console.
6.Using the WebSphere Administrative Console, add
<wcs_install_path>\lib\ITSOEJBIMPL.jar to the dependent classpath of the
node (at the beginning).
For example: C:\Websphere\WCS\lib\ITSOEJBIMPL.jar
7.Add to the command line arguments of the application server WebSphere
Commerce Server - <instance-name> the following entries:
.\lib\ITSOEJBIMPL.jar;.\lib\ITSOEJBDeployed.jar;.\lib\ITSOCommands.jar
8.Add to XMLConfig.bat batch file (located in the <was_install_path>\bin folder)
the following line:
set WAS_CP=%WAS_CP%;<WCS_INSTALL_PATH>\lib\ITSOEJBIMPL.jar
For example: C:\Websphere\WCS\lib\ITSOEJBIMPL.jar
9.Modify was.ITSO.EJB.xml changing the node name, application server name
and location of the jar-file and copy it to the <was_install_path>\bin folder.
10.Open command prompt, change directory to <was_install_path>\bin folder
and run the command: XMLConfig -import was.ITSO.EJB.xml
-adminnodename <NODE_NAME>
11.Restart the WebSphere Commerce Server - <instance-name> application
server from the WebSphere Administrative Console.
For more information about deployment of custom code, please see WebSphere
Commerce Suite V5.1 Customization and Transition Guide, SG24-6174.
Note: If you do not want to substitute your JSPs, you can add the custom
code between the tags <!-- ITSO Order Custom START --> and <!-- ITSO
Order Custom END -->

© Copyright IBM Corp. 2001
361
Chapter 14.
Messaging integration
To facilitate communication with external applications, WebSphere Commerce
Suite V5.1 provides a powerful and flexible framework using the Common
Connector Framework (CCF). This communication includes the sending and
receiving of messages to and from back-end systems, and sending notification to
customers and administrators that events have occurred within WebSphere
Commerce Suite. Commerce Suite also defines well-known messages used in
the commerce systems such as OrderSend and InventoryUpdate. You can reuse
and extend these message or create messages of your own type using the
framework.
This chapter is organized into the following sections:
Messaging subsystem architecture
MQSeries back-end integration example
Newsletter example
14

362
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
14.1 Messaging subsystem architecture
The Commerce Suite messaging subsystem is comprised of two components
subsystems:
Inbound: The inbound messaging system uses an MQSeries adapter to
manage inbound messages from back-end systems.
Outbound: The outbound messaging system allows you to send notification to
users as well as outbound messages to back-end systems.
The Common Connector Framework (CCF) is the IBM-developed standard for
connectivity to external systems. CCF shields the user from the complexities of
underlying transports such as e-mail and MQSeries to provide a uniform
interface irrespective of the transport type and has the facility to accommodate
transport specific parameters.
14.1.1 Commerce Suite inbound messaging system
Figure 14-1 depicts the inbound messaging system components.
Figure 14-1 Inbound messaging system components
Serial
Inbound
Queue
Parallel
Inbound
Queue
CCF
MQ
Adapter
Web
Controller
Command
Framework
EJB
Commerce Suite
Database
XML Parser
MQListener
Template
Definition
Files
dtd

Chapter 14. Messaging integration
363
TransportListener or MQListener
The MQListener is a protocol listener that listens to the messages from
MQSeries JMS objects and dispatches them to the program adapter.
Program or MQSeries adapter
This adapter transforms the message format of the inbound request into a set of
properties that Commerce Suite commands can understand using the XML
parser and template definition files and invokes the Web controller.
The MQSeries adapter supports two types of message processing, depending
upon the specified MQSeries JMS queue.
Serial processing: In serial processing mode the adapter processes the
messages serially or one after another on the order of arrival. In this method,
each message must wait until processing of the previous message is
complete.
Parallel processing: In parallel processing mode the adapter simultaneously
processes the number of messages. Instead of each message having to wait
for the previous one to be completed, many of them can be processed
simultaneously.
MQSeries JMS objects
MQSeries JMS objects are actually MQSeries JMS objects such as connection
factories and queues. The JMS objects are mapped to MQSeries queues using
the JMSAdmin tool of the MQSeries V5.21. For the inbound processing of
messages you need to set up and configure MQSeries in either bindings mode or
client mode. The bindings mode can exploit JNI and be more reliable, but
generally requires more resources.
For the inbound message support, you need to create two queues: one for serial
processing and the other for parallel. Next, the appropriate JMS objects defined
needs to be mapped for the inbound transport, using the Configuration Manager.
Note: The actual selection of mode for your message depends upon the
business logic. Generally parallel processing provides faster throughput, but is
not suitable for the messages where serial ordering is required.
For example, if a customer registers as a new customer at your store, and
then makes a correction to his address information, and then places an order,
these transactions need to be preserved when processing them. You could
not perform the address modification or the purchase order unless the account
had already been created. Likewise, you would not want to fill the purchase
order without having the correct shipping information.

364
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Template definition files
The template files defines the mapping of inbound XML messages to Commerce
Suite commands. For example, if it is based on an inbound XML message type, it
determines which Commerce Suite command has to be called and maps the
XML message elements to Commerce Suite command parameters.
For each inbound message type, the template definition file defines two
elements:
Template document: Defines the DTD file used by the message, the
command that is called when the message is received, which tag mapping is
to be used, and the XML element from which tag mapping is started.
Template tag: Defines the mapping of XML elements in the DTD file to
parameter names of commands in WebSphere Commerce Suite. The
template tag element identifies the parameter names and tells the parser
where to find the values on an incoming message.
Commerce Suite provides two template definition files. The sys_template.xml file
is the template definition used to map existing Commerce Suite inbound XML
messages (shown in Example 14-1). The user_template.xml is provided to add
additional inbound XML messages. Both files are in XML format, based on the
ec_template.dtd template definition DTD file.
Example 14-1 shows the mapping of Update_NC_ProductInventory defined in
the sys_template.xml file.
Note: In fact, for the complete integration of MQSeries you need to create five
queues for inbound, error, and outbound as follows:
MQSeries inbound serial queue mapped to JMSSerialInBoundQueue,
used for serial inbound message processing.
MQSeries inbound parallel queue mapped to JMSParallelInboundQueue,
used for parallel processing of inbound messages.
MQSeries inbound queue mapped to JMSInbound Queue, used for
synchronous receiving of messages when outbound processing mode
specified as request-reply.
MQSeries outbound queue mapped to JMSOutboundQueue, used for
sending outbound messages.
MQSeries error queue mapped to JMSErrorQueue, used for placing the
messages not able to be processed in Commerce Suite.

Chapter 14. Messaging integration
365
Example 14-1 Example sys_template.xml
<TemplateDocument>
<DocumentType version='1.0'>Update_NC_ProductInventory</DocumentType>
<StartElement>DataArea</StartElement>
<TemplateTagName>ProductInventory10Map</TemplateTagName>
<CommandMapping>
<Command CommandName='ProductInventoryUpdate' />
</CommandMapping>
</TemplateDocument>
<TemplateTag name='ProductInventory10Map'>
<Tag XPath='ProductInventoryInfo' XPathType='VECTOR' Field='VECTOR' />
<Tag XPath='ProductInventoryInfo/ProductNumberByMerchant'
Field='catEntryId' />
<Tag XPath='ProductInventoryInfo/MerchantID' Field='storeId' />
<Tag XPath='ProductInventoryInfo/MerchantID@type' XPathType='EMPTY' />
<Tag XPath='ProductInventoryInfo/Quantity' Field='inventoryQuantity' />
<Tag XPath='ProductInventoryInfo/UserData/UserDataField'
XPathType='USERDATA' />
</TemplateTag>
Inbound messages
The Commerce Suite predefined inbound messages provide the following
functions:
Create a customer registration
Update a customer registration
Update the status of an order
Update the inventory for a product
Update the price of a product

366
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Each of the functions listed above can be activated by a message in either XML
format or legacy format (messages in Net.Commerce 3.2). XML is the
recommended format and should be encoded using UTF-8. Table 14-1
summarizes the predefined inbound messages, the appropriate command to be
triggered, and the relevant XML file.
Table 14-1 Inbound messages
Function Description
Controlled
Command
XML
Message
Legacy NC
message
New User
Registration
Creates a new
user registration
record in
Commerce Suite
UserRegistraion
Add
Create_WCS_Custom
er
Create_NC_C
ustomer
Updat User
Registraion
Updates the
existing User
registration record
in Commerce
Suite
UserRegistraoin
Update
Update_WCS_Custo
mer
Update_NC_C
ustomer
Update Order
Status
Updates the
general status of
an existing Order
in Commerce
Suite
OrderStatus Update_WCS_OrderS
tatus with the element
‘OrderStatus’
Update_NC_O
rderStatus
Update Order
Confirmation
Updates the
confirmation
Status of an
existing Order in
Commerce Suite
OrderConfirmSta
tus
Update_WCS_OrderS
tatus with the element
OrderConfirm
Update Order
Shipping Status
Updates the
shipping status of
an existing order in
Commerce Suite
OrderShippingSt
atus
Update_WCS_OrderS
tatus with the element
OrderShipping
Update Order
Invoice Status
Updates the
invoice status of
an existing order in
Commerce Suite
OrderInvoiceStat
us
Update_WCS_OrderS
tatus with the element
OrderInvoice
Update Product
Offer Price
Updates the offer
price information
of an existing
product in
Commerce Suite
ProductOfferPric
eUpdate
Update_WCS_Produc
tPrice with the element
OfferPriceInfo
Update_NC_P
roductPrice

Chapter 14. Messaging integration
367
By default, all of the template definitions, template definition DTDs, and DTD files
for inbound XML messages are stored in the <wcs_install_path>/xml/messaging
directory.
How the inbound messaging system works
When a message arrives, the MQListener reads the message and dispatches to
the MQSeries adapter. The adapter will process the message depending on the
message type and processing mode (serial or parallel). The actual processing
involves the following steps:
1.The MQSeries adapter invokes the XML parsers and passes the XML
message.
2.The XML parser parses the message based on the message type using
systemplate.xml and usertemplate.xml, which identifies the command to be
called and maps the XML message elements to the command parameters. If
the message type is not found, the default NewInboundMessagecmd will be
specified and returns to the MQSeries adapter.
3.The MQSeries adapter then invokes the Web controller passing the
command name and command properties.
4.The Web controller starts the transaction and executes the command. The
command actually performs the business logic by invoking various task
commands and updates the database.
5.If successful, the Web controller commits and returns. If unsuccessful, it rolls
back the current transaction. In such a case, the MQSeries adapter will place
the message in an error queue.
Update Product
List Price
Updates the list
price information
of an existing
product in
Commerce Suite
ProductListPrice
Update
Update_WCS_Produc
tPrice with the element
ListPriceInfo
Update Product
Inventory
Updates the
inventory
information of an
existing product in
Commerce Suite
ProductInventory
Update
Update_NC_ProductIn
ventory
Update_NC_P
roductInventor
y
Function Description
Controlled
Command
XML
Message
Legacy NC
message
Note: Table 14-2 on page 369 defines the parameters to configure the
Commerce Suite instance, such as template files, DTDs, and Commerce Suite
JMS objects by using the Configuration Manager.

368
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
14.1.2 Commerce Suite outbound messaging system
Inbound messaging only supports the MQSeries transport, whereas the
outbound messaging is very comprehensive and supports transports for e-mail,
file transfer, and MQSeries using the plug-in model of the CCF. The outbound
messaging system also provides administration tools used to configure the
messages and transports.
Commerce Suite outbound messaging is comprised of administration tools,
runtime services, and interfaces for application access as seen in Figure 14-2.
Figure 14-2 Commerce Suite outbound messaging system components
Administration and management services
The following features are used for the configuration and management of the
transports, and message types:
Plug-in management: involves the tasks for adding/deleting and
enabling/disabling the transports.
Message type management: involves the task for creating, adding and
deleting the message types. Commerce Suite also provides 12 outbound
messages used for order, notifications, etc.
Note: For details about how to extend inbound messages, controller
commands, and create new messages and controller commands, please refer
to the IBM WebSphere Commerce Suite V5.1 online documentation.
Tools
Sub
Systems
User
Interface
Administration
Plug-in
Administration
Message Type
Management
Profile
Management
Composition
Service
Message Type
Settings in DB
Profile Settings
in DB
Runtime
Interface
Administration
Interface
CommonConnectorFramework
(CCF)
MQSeries
e-Mail
File
Runtime
Profile Services
Send Services
Composition
Services
User
Interface
Send
services

Chapter 14. Messaging integration
369
Profile management: involves the tasks for assigning transports to the defined
message types and configuring the messages.
Runtime services
The runtime features are used for actual messaging composition as invoked by
the Commerce Suite subsystem for the business operations (for example, order,
member, etc.) and delivery of the messages to various transports. The runtime
provides the flexible services for composing the messages using JSPs and
sending through various transports based on the message profile type. In a
nutshell, the main runtime features include the following features:
Composition services: customizing the message composition using JSP
templates.
Multiple message transmission support: allows you to send the same
message through more than one transport.
Multiple notification of messages over the same transport: useful for sending
broadcast messages over e-mail.
Multiple processing modes: supports three processing modes:
– Transacted: used for the messages that should be sent upon the
successful completion of the current transaction (for example, sales order
creation).
– Immediate: used for the messages that should be sent when the event
takes place in Commerce Suite. The message is sent whether the
transaction commits or not (for example, error notification to merchant)
– Request-reply: used for the message that requires a response message
from the back-end system (for example, synchronized message
applications such as online order confirmation, online payment
processing, stocks, and foreign exchange system).
Message types: Commerce Suite predefines 12 messages for order,
password, error notifications, etc. You can also add your own outbound
messages.
Table 14-2 Commerce Suite predefined message types
Message Type Name in administration console Usage
ErrorMessage Description of an error condition
occurring in WebSphere Commerce
Suite
Configure this message type to
enable administrators to receive
e-mail messages when an error
occurs in WebSphere Commerce
Suite.

370
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
OrderCreateFixFormat Outbound message for WebSphere
Commerce Suite order create
Indicates that an order has been
created in Commerce Suite. The
message can be used to send an
outbound Commerce Suite order
create message to a back-end
system.
OrderCreateXMLFormat Outbound message for WebSphere
Commerce Suite XML create
Indicates that an order has been
created in Commerce Suite. The
message can be used to send an
outbound Commerce Suite order
create message to a back-end
system.
OrderStatusNotify Notification message of the order
status
Indicates that the status of an
order has changed.
OrderAuthorized Message for a authorized order Indicates that an order has been
authorized.
OrderReceived Message for a received order Indicates that an order has been
received.
OrderRejected Message for a rejected order Indicates that an order has been
rejected.
OrderCancel Notification message for a canceled
order
Indicates that an order has been
canceled.
PasswordNotify Notification message for password
reset
Configure this message type to
enable e-mail messages to be
sent to customers indicating that
their password has been reset.
BroadcastMessage A broadcast message Configure this message type to
send broadcast message to
customers.
MerchantOrderNotify Message for notifying the merchant of
an order
Related to the NotifyMerchant
parameter of the OrderProcess
command.
AdminOrderComment Order-related message sent by
customer service representative
Configure this message type to
enable Customer Service
Representatives to send
customers e-mail messages from
the Commerce Suite Accelerator.
Message Type Name in administration console Usage

Chapter 14. Messaging integration
371
How outbound messaging work
Using the Commerce Suite Administration Console, the administrator can enable
transports and configure profiles for different message types. The store
administrator can further customize the settings specific to the store.
When the subsystem invokes the outbound messaging using commands and
interfaces, the following events will occur.
1.The appropriate profile is retrieved for the message type. If no store profile
exists for that message, the site profile is used. The profile directs the type of
transport and settings used to send the message.
2.If the message uses the composition service, a template is used to generate
the message.
3.The message is sent through the runtime interface to the transport, which
delivers the notification.
14.2 MQSeries back-end integration example
This section describes an MQSeries back-end integration scenario with
WebSphere Commerce Suite V5.1.
Requirements
The first task is to identify the back-end integration messaging requirements for
the ITSO store. When the user places an order in the ITSO store, the ITSO store
will create a sales order and pass it to the back office. The back office will
process the order and send the updated inventory back to the ITSO store. The
ITSO store will update the inventory and show the reflected inventory in the
product display pages.
Note: OrderCreateFixFormat and OrderCreateXMLFormat can only be used
with MQSeries. Some messages require that you create your own JSP
templates. For more detailed information, refer to the IBM WebSphere
Commerce Suite V5.1 online documentation.

372
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Solution overview
Since the ITSO store was developed using WebSphere Commerce Suite V5.1
and the back office has an existing MQSeries channel, we can immediately
identify the usage of MQSeries messaging with Commerce Suite to send the sale
order to the back office. We can use the Commerce Suite outbound message for
order creation and for the inventory update in Commerce Suite database. In
addition, we can use the product inventory update inbound message. The
sequence of steps in the message flow are depicted in Figure 14-3.
Figure 14-3 Message flow between Commerce Suite and back office over MQSeries
This section provides an explanation of how MQSeries XML messages interact
with WebSphere Commerce Suite for the ITSO store.
1.The shopper creates an order within the ITSO store.
2.An XML message is sent from the Commerce Suite, based on the order
details, to the MQSeries adapter using outbound messaging system. The
4
Backend
database
1
7
2 356
8
9
Commerce
Suite
Command
Framework
Commerce
Suite
database
Back-end
ERP
ERROR
INBOUND.SER
OUTBOUND
MQ adapter
MQListener
Outboundservices
Outboundservices
Inboundservices
Inboundservices

Chapter 14. Messaging integration
373
MQSeries adapter is configured to send the MQSeries message in XML
format to the MQSeries Server queue manager called QM.WCS, and
OUTBOUND queue.
3.The back-end system will get the XML message from the OUTBOUND
queue.
4.The back-end system will deduct the inventory level for the ordered product,
based on the received XML message generated from the WebSphere
Commerce Server.
5.The back-end system creates an XML message that reflects inventory
changes to be put on the INBOUND.SER queue. The back-end system must
follow the XML message DTD format of Commerce Suite for the inventory
update.
6.The MQSeries adapter will get the XML message from INBOUND.SER queue
and invoke the Commerce Suite command ProductInventoryUpdate.
7.The Commerce Suite command ProductInventoryUpdate updates the
inventory level for the particular product within the INVENTORY table of the
Commerce Suite database server.
8.If any error occurs in processing the inbound message or updating the
inventory, the MQSeries adapter will place the received message in the
ERROR queue.
9.The shopper can view the inventory level of items in the ITSO store display
pages.
14.2.1 High-level implementation steps
The high-level implementation steps are as follows:
Install and configure MQSeries and Commerce Suite
Configure the outbound messaging for the sale order
Configure the inbound messaging for updating inventory
Note: The Update_NC_ProductInventory has some problems with the Web
Fashion store. We are providing an alternative DTD and template definition file
with this example.

374
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Install and configure MQSeries and Commerce Suite
This section describes the necessary tasks to accomplish the back-end
integration using MQSeries with WebSphere Commerce Suite V5.1.
1.MQSeries V5.21 installation.
– Install Active Directory Server (ADS), Microsoft Management Console
(MMC) and HTML help, included on the MQSeries CD (MQSeries
prerequisites).
– Install MQSeries in either client/server or server-to-server mode (bindings
mode). To install the MQSeries client/server mode you need to install the
client on a Commerce Suite machine and an MQSeries Server on the
other system.
– Verify the MQSeries installation using the PostCard application.
2.Create the MQSeries queues used by Commerce Suite.
Create the queue manager and necessary queues for Commerce Suite and
MQSeries connectivity. The default integration uses five queues. In our case
we have created the queues as follows:
– Queue manager: QM-WCS
– Inbound serial queue: INBOUND.SER
– Inbound parallel queue: INBOUND.PAR
– Inbound queue: INBOUND
– Outbound queue: OUTBOUND
– Error Queue: ERROR
3.MQSeries JMS installation.
Note: For the details on installing and configuring MQSeries, MQSeries JMS,
and Commerce Suite messaging refer to the chapter on messaging using
MQSeries and e-mail in the WebSphere Commerce Suite V5.1 Handbook,
SG24-6167 redbook.
Note: The queue creation and definition very much depend upon your
complete MQSeries system configuration. If your back-office application is
on a different machine, then you need to create the outbound queue as the
remote definition queue for the back office. In addition you will have to
define the transmission channel, and will need to start the channel listener.
For details, please refer to MQSeries product documentation found at:
http://www.ibm.com/software/ts/mqseries/library/manualsa/index.html

Chapter 14. Messaging integration
375
The MQSeries JMS enablement requires that you install a separate support
pac MA88 available from the IBM site at:
http://www.ibm.com/software/ts/mqseries/txppacs/txpm4.html
4.MQSeries JMS configuration.
a.Update the system Java class path to include JAR files in the MQSeries
JMS installation.
b.Add environment variable MQ_JMS_INSTALL_PATH for the installed
MQJava executable directory.
c.Update the system path to include the WebSphere Application Server JRE
for the usage of the JVM.
d.Run the test script IVTRun to verify the JMS installation.
e.Update the JMSAdmin.config file to use WebSphere Persistent Naming
Server (PNS) for JMS objects.
f.Map the MQSeries objects (queues) to Commerce Suite JMS objects
using JMSAdmin tool. In our case, we have mapped as follows:
• INBOUND.SER: JMSSerialInboundQueue
• INBOUND.PAR: JMSParallelInboundQueue
• INBOUND: JMSInboundQueue
• OUTBOUND: JMSOutboundQueue
• ERROR: JMSErrorQueue
5.Commerce Suite - MQSeries configuration.
a.Enable the Transport Adapter using Configuration Manager.
b.Prepend the MQSeries JMS JAR files to the Commerce Suite classpath in
the command-line arguments of the Commerce Suite application server
using the WebSphere Administration Console.
Configure the outbound messaging for the sale order
To send the order to the back end using MQSeries, Commerce Suite supports
two outbound messages: one in legacy Net.Commerce (NC) format
(OrderCreateFixFormat) and the other in XML format (OrderCreateXMLFormat).
You can use either of them but not both.
Note: The definitions for the queues JMSInbound and JMSError can be
modified using the Commerce Suite Configuration Manager for the CCF
parameters of your current Commerce Suite instance.

376
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
The OrderCreateXMLFormat message uses Report_NC_PurchaseOrder XML to
format the message, SendXMLOrderCmdImp as the implementation of
OrderMessgingCmd interface, and OrderCreateXML.jsp as the template to
compose the message.
The OrderCreateFixFormat message uses Net.Commerce legacy message
format and SendWCSOrderCmdImp as the implementation of
OrderMessgingCmd.
To use the desired message, you need to perform the following tasks:
Enable the status of MQSeries transport as active using Commerce Suite
Administration Console.
Select the message type to send order and define the transport settings.
Register the command implementation for the OrderMessagingCmd
Interface.
Update and create views for the usage of the appropriate message.
If you are not using Payment Manager, update the DoPaymentMPFCmdImpl
of DOPaymentCmd interface to DoPaymentCmdImpl, and modify the
OrderDisplayPending.jsp to use the credit card types.
In our example, we used the OrderCreateXMLFormat message type and
performed the following tasks:
1.Select and configure the message type Outbound message for WebSphere
Commerce Suite XML create, and assign the transport setting to MQSeries
by using the Commerce Suite Administration Console.
2.Register the SendXMLOrder command for use with the store (storeid=10001)
using the following SQL script:
insert into CMDREG(STOREENT_ID, INTERFACENAME, CLASSNAME, DESCRIPTION,
TARGET) values (10001, 'com.ibm.commerce.order.commands.OrderMessagingCmd',
'com.ibm.commerce.messaging.commands.SendXMLOrderCmdImpl', 'Order Create
XML', 'Local')
3.Update the VIEWREG table by replacing OrderOKView with
OrderOKResultView using the following SQL script:
update VIEWREG set VIEWNAME='OrderOKResultView' where STOREENT_ID=10001 and
VIEWNAME='OrderOKView'
4.Create a new view OrderOKView for the ITSO store as a
HTTPRedirectedView using the following SQL script:
Note: We recommend the use of OderCreateXMLFormat, which is very
flexible unless you have legacy NC format usage requirements.

Chapter 14. Messaging integration
377
insert into VIEWREG (STOREENT_ID, DEVICEFMT_ID, VIEWNAME,INTERFACENAME,
CLASSNAME, PROPERTIES, HTTPS, INTERNAL)values (10001, -1, 'OrderOKView',
'com.ibm.commerce.command.RedirectViewCommand','com.ibm.commerce.command.Ht
tpRedirectViewCommandImpl','redirecturl=OrderOKResultView', 0, 0)
5.Update the VIEWREG to use the OrderCreateXML.jsp at the Mall level (the
JSP is available in the <wcs_install_path>/stores/web directory) using the
following SQL script:
update viewreg set properties='docname=OrderCreateXML.jsp&storeDir=no'
where viewname like '%OrderCreateXML%' and storeent_id=0
6.Optional - Disable Payment Manager.
If you do not want to use Payment Manager, complete the following steps
(optional):
a.Update the CMDREG not to use Payment Manager by disabling the
command implementation DoPaymentMPFCmdImpl with default payment
implementation by using the following SQL script:
update cmdreg set classname =
'com.ibm.commerce.payment.commands.DoPaymentCmdImpl' where interfacename
= 'com.ibm.commerce.payment.commands.DoPaymentCmd'
b.Modify the OrderDisplayPending.jsp to use offline payments using credit
cards by inserting the following CREDIT_CARD_TYPE between the select
tags of CardBrand as follows:
<option value ="visa">VISA</option>
<option value ="mast">MASTER</option>
<option value ="amex">AMEX</option>
Configure the inbound messaging for updating inventory
The usage of Product_NC_Inventory has some problems in updating the
inventory for Web Fashion stores. We have provided an alternative DTD and
template definition file to update the product inventory for the stores that are
developed using the Web Fashion store template.
To use these files, complete the following steps:
1.Copy the DTD file Update_WCS_ProductInventory_20.dtd to the
<wcs_install_path>/xml/messaging directory.
Note: The additional materials zip file for this redbook includes the following
files to provide inventory update support for stores developed using the Web
Fashion template store:
Update_WCS_ProductInventory_20.dtd
user_template.xml

378
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
2.Open the <wcs_install_path>/xml/messaging/user_template.xml and add the
contents of user_template.xml supplied with this book. Alternatively, replace
the file if you have not customized the messaging system, with the
user_template.xml file supplied with the additional material.
3.Update the Commerce Suite inbound messaging system to identify the
Update_WCS_ProductInventory_20.dtd.
Open the Commerce Suite Configuration Manager and select
<wcs_instance> -> Instance Properties -> Messaging. In the General tab
for messaging, append the text Update_WCS_ProductInventory_20.dtd in the
inbound message DTD file text box, and apply the changes to Commerce
Suite Configuration Manager (delimited by commas).
4.Update the display pages to show the updated inventory (shoppingcart.jsp).
The product inventory for the SKUs will be saved in the INVENTORY table.
You can access the inventory information using InventoryAccessBean. In our
example, we display the product inventory on the shopping cart page. The
code added to the shoppingcart.jsp can be seen in Example 14-2.
Example 14-2 Sample inventory update - shoppingcart.jsp
// InventoryAccessBean available in the package
// com.ibm.commerce.fulfillment.objects
<% try{
InventoryAccessBean ib = new InventoryAccessBean();
ib = ib.findByCatalogEntryAndFulfillmentCenterAndStore(new Long(
orderItem.getCatalogEntry().getCatalogEntryReferenceNumber()) , new
Integer(storeId), new Integer(storeId) ) ;
out.print(ib.getQuantity());
} catch(Exception e) { out.print("NA"); }
%>
5.After completing all of the above-mentioned tasks, you need to restart the
Commerce Suite server instance.
Testing
To test the inventory update being displayed, create an order in the ITSO store.
Commerce Suite will create a sale order and dispatch it to the OUTBOUND
queue. You can get the sale order message from the queue. Next the message is
parsed and it creates the product inventory update message, which can be
placed in either serial or parallel inbound queue. We prefer in this case to use the
serial inbound queue. The sequence of windows for the order can be seen in
Figure 14-4, Figure 14-5, Figure 14-6, and Figure 14-7.

Chapter 14. Messaging integration
379
Figure 14-4 Item in the shopping cart displaying the inventory

380
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 14-5 Order checkout

Chapter 14. Messaging integration
381
Figure 14-6 Order confirmation

382
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 14-7 Adding the same item to another order showing the updated inventory
The portion of the sale order XML in the OUTBOUND queue can be seen in
Example 14-3, and the product inventory update XML can be seen in
Example 14-4.
Example 14-3 Part of Commerce Suite created sale order XML in OUTBOUND queue
<!DOCTYPE Report_NC_PurchaseOrder SYSTEM "Report_NC_PO_10.dtd">
<Report_NC_PurchaseOrder version="1.0">
<ControlArea>
<Verb value="Report"> </Verb>
<Noun value="NC_PurchaseOrder"> </Noun>
</ControlArea>
<DataArea>
<ReportPO>
<ReportPOHeader>
<OrderNumberByNC>11002</OrderNumberByNC>
<DateTimeReference>
<PlacedDate>20010911</PlacedDate>
<PlacedTime>153223</PlacedTime>
</DateTimeReference>

Chapter 14. Messaging integration
383
<TotalPriceInfo currency="USD">
<TotalNetPrice>25.00000</TotalNetPrice>
<TaxInfo>
<MonetaryAmount currency="USD">1.25000</MonetaryAmount>
</TaxInfo>
<TotalShippingPrice>6.00000</TotalShippingPrice>
<TotalTaxOnShippingPrice>0.00000</TotalTaxOnShippingPrice>
</TotalPriceInfo>
<ShipStatus>C</ShipStatus>
<BillToInfo>
Example 14-4 Product Inventory Update XML to be placed in the serial Inbound Queue
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Update_WCS_ProductInventory SYSTEM
"Update_WCS_ProductInventory_20.dtd">
<Update_WCS_ProductInventory version="2.0">
<ControlArea>
<Verb value="Update"></Verb>
<Noun value="WCS_ProductInventory"></Noun>
</ControlArea>
<DataArea>
<ProductInventoryInfo>
<ProductSKU>sku-105</ProductSKU>
<MerchantID>10001</MerchantID>
<Quantity>99</Quantity><FulfillmentCenterID>10001</FulfillmentCenterID>
</ProductInventoryInfo>
</DataArea>
</Update_WCS_ProductInventory>
14.3 Newsletter example
This section provides an example of how to create and send a personalized
news letter for registered users of a defined interest.
Requirements
The ITSO store will send a personalized newsletter based on the interests for the
registered users who subscribed for to newsletter. The ITSO store administrator
will compose the newsletter and schedules the news letter application to send
regular newsletters.

384
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Solution overview
The actual information for the subscription to the newsletter and user interests
are saved in the field2 and hobbies columns of the USERDEMO table.
The solution is implemented using Commerce Suite outbound messaging
system architecture. We have organized the solution as follows:
Analysis: This task involves analyzing the requirements of the newsletter and
mapping the requirements over functional components of the system.
Design: This is the actual identification of functional components that are
newly developed and utilize existing Commerce Suite components.
Development: This is the actual task of developing or modifying and
packaging the components of the newsletter using VisualAge for Java and
WebSphere Commerce Studio.
Deployment: This is the task of deploying the components developed in the
Commerce Suite server runtime.
Testing: This task involves testing the newsletter application for various
success and failure criteria.
Analysis
From the above requirements, we can identify the following components that are
required for the ITSO Store newsletter usage:
1.An application which performs the overall task - say NewsLetterApplication.
2.A component that finds the interested users to receive the newsletter - say
NewsletterHelper.
3.A component that obtains the individual user information provided by the
NewsLetterHelper component - say UserinformationComponent.
4.A component that composes the newsletter - say NewsLetterComposer.
5.A component that sends the newsletter over e-mail - say NewsLetterSender.
6.A component that schedules the newsletter -say NewsLetterScheduler.
Design
Having identified the required components for the newsletter usage, the next
task is to find the available components in WebSphere Commerce Suite V5.1
that provide the specified functionality.
From the IBM WebSphere Commerce Suite V5.1 online documentation we can
ascertain the following:
NewsLetterApplication: The Broadcast messaging command is similar to this,
but the Broadcast command can’t send the personalized newsletter. Hence
we need to develop a separate controller command to facilitate this. Let’s call

Chapter 14. Messaging integration
385
this NewsLetterCmd and an equivalent implementation class
NewsLetterCmdImpl.
NewsLetterHelper: Interested users for e-mail will be marked with the value of
‘Y’ in the UserDemo table. We can have various solutions to get this data,
some of which are listed below.
– Direct JDBC calls in NewsLetterCmd: Involves the low-level coding using
JDBC; not very flexible.
– Using entity bean Rowset AccessBean: Using a finder method of an entity
bean involves heavy database access and round-trip calls and is not
efficient. The DemographicsBean doesn’t provide the finder method for
the field2 condition.
– Using a Stateless Session Bean: This is a better way and this can hide the
complexity of data accessing and can use either JDBC or entity beans.
Commerce Suite also provides a JDBCHelper class that shields the user
from actual database calls and provides a uniform interface. We can use
this for the development of our Helper Bean.
UserInformationComponent: This component is responsible for getting user
information such as e-mail address, first name, last name, interests, etc.
From the IBM WebSphere Commerce Suite V5.1 online documentation, we
can identify that there are different beans to accomplish the tasks, such as:
– UserRegistryBean - to get the registration information
– DemographicsBean - to get the user demographic information
– AddressBean - to get the user address information
And hence we can use the appropriate access beans to get the user information.
Also for the ease of usage in JSP we can develop the data bean
NewsLetterUserInfo, which helps the JSP developer avoid the complexity of
using access beans.
NewsLetterComposer: A JSP can be used for this purpose. Furthermore the
JSP can be encompassed using a MessagingViewCommand that has the
flexibility to change the JSPs without changing the command coding.
NewsLetterSender: From the Commerce Suite messaging documentation,
we find that SendMsgCmd can be used for this purpose.
NewsLetterScheduler: From the IBM WebSphere Commerce Suite V5.1
online documentation, we can find that Commerce Suite scheduler can be
used for this purpose.

386
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Table 14-3 summarizes the above identified components.
Table 14-3 News letter components
Component
Required
Component
identified
Availability Comments
NewsLetterApplicatio
n
NewsLetterCmd
NewsLetterCmdImpl
New This is a Controller
Command whose
interface is
NewsLetterCmd and
implemented as
NewsLetterCmdImpl.
NewsLetterHelper NewsLetterHelper New This is a Stateless
Session bean that
extends the
BaseJDBCHelper
class provided by
Commerce Suite.
UserInformation Access Beans of
1.UserRegistry
2.Demographics
3.Address.
Available These access beans
are used to get the
required information
for the newsletter
such as e-mail
address, interests etc.
UserInformation used
in the template
NewsLetterUserInfo New This is a databean that
encompasses the
user information by
accessing
Demographics and
Address beans.
NewsLetterCompose
r
NewsLetterView and
NewsLetter.jsp
New NewsLetterView is a
Messaging View
Command and
NewLetter.jsp is the
actual JSP template
used to compose the
newsletter.
NewsLetterSender SendMsgCmd Available The SendMsgCmd
command of WCS
Messaging system.
NewsLetterSchedule
r
Scheduler Available WCS System
Scheduler.

Chapter 14. Messaging integration
387
Figure 14-8 Newsletter components and flow
The following component interaction is depicted in Figure 14-8.
1.The administrator schedules the newsletter job by entering a URL in a Web
browser.
DemoGraphics
Address
Beans
NewsLetterCmd
SendMsgCmd
SMTP
Server
HTTP Servlet Engine &
Adapter Mechanism
Scheduler
Adapter
1
12
2
3
4
5
6
7
8
9
10
11
1
Web
Controller
2
4
3
5
8
9
12
NewsLetter
View
10
NewsLetter.jsp
NewsLetter
User Info
11
7
User Registry
Access Bean
NewsLetter
Helper
Access Bean
User Registry
Bean
NewsLetter
Helper Bean
6
13
Commerce
Suite
database

388
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
2.The URL request will reach the Web controller over the servlet engine,
Request Servlet and HTTP Adapter framework of the Commerce Suite
server.
3.The Web controller adds the newsletter job to the schedule to be triggered
and repeated for the defined time and interval.
4.The scheduler invokes the specified task to the Web controller by passing the
NewsLetterCmd name and input properties at the scheduled time and
intervals.
5.The Web controller instantiates and invokes the NewsLetterCmd.
6.The NewsLetterCmd will invoke the NewsLetterHelperAccessBean which in
turn accesses the NewsLetterHelper session bean to get the list of interested
users to receive the newsletter.
For each interested user to receive the newsletter, the NewsLetterCmd
performs the following tasks:
a.Invokes the UserRegistryAccessBean to get the e-mail address (same as
logon ID).
b.Invokes the SendMsgCmd by passing the messaging parameters.
c.SendMsgCmd invokes the NewsLetterView to compose the news letter.
d.NewsLetterView uses the NewsLetter.Jsp template to compose the mail.
e.NewsLetter.jsp uses the NewsLetterUserInfo data bean to get the user
details such as name and interests in receiving such topics as Commerce
Suite and WebSphere Application Server.
f.NewsLetterView returns the composed message to SendMsgCmd.
g.SendMsgCmd sends the mail over SMTP to the mail server.
Development
This section highlights the actual development of newsletter components:
1.Developing the NewsLetterHelper session bean
The NewsLetterHelper class has two interfaces and an implementation class
as follows:
– NewsLetterHelper extends EJBObject and has method
findInterestedUsers() method which returns the Vector of interested users
to receive the newsletter.
– NewsLetterHelperHome extends the EJBHome interface
– NewsLetterHelperBean is a stateless session bean that extends
com.ibm.commerce.base.helpers.BaseJDBCHelper and implements the
session bean. The BaseJDBCHelper class provides the methods for

Chapter 14. Messaging integration
389
getting a database connection without specifying the datasource, user ID
and password and hides the implementation issues for DB2 and ORACLE.
This bean implements the findInterestedUsers() of NewsLetterHelper
remote interface as seen in Example 14-5. This method uses
makeConnection() to get a Commerce Suite database connection and
creates the prepared statement using the SQL statement and then
executes the query. Then it creates a vector for the list of interested users
containing their user IDs.
In the ITSO store the mail subscription, we saved the data in field2 of the
USERDEMO Table as “Y”. Hence the SQL statement is also prepared
appropriately to fetch the data as seen in Example 14-5.
Example 14-5 Example findInterestedUsers
// the argument value is a conditional expression for the SQL statement a value
// “Y” is used to get the interested users for newsletter in ITSO store
// public static final java.lang.String findInterestedUsersSQL =
// " SELECT USERS_ID FROM USERDEMO WHERE FIELD2 = ?";
public java.util.Vector findInterestedUsers(String value) throws
javax.naming.NamingException, java.rmi.RemoteException, java.sql.SQLException,
java.lang.Exception {
java.util.Vector intUsers = new java.util.Vector();
try {
// makeconnection() provided by BaseJDBCHelper which creates the connection to
// WCS datasource
makeConnection();
PreparedStatement stmt = getPreparedStatement(findInterestedUsersSQL);
stmt.setString(1, value);
ResultSet rs = executeQuery(stmt, false);
if(rs != null)
while (rs.next())
{
String curUser = rs.getLong("USERS_ID")+"".trim();
// add it to the intUsers Vector
intUsers.addElement(curUser);
}
finally {
closeConnection();
}
if (intUsers.isEmpty())
{
// no elements added to the vector
intUsers = null;

390
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
}
return intUsers;
}
– You can use the VisualAge for Java smart guide to develop the EJB. The
deployment descriptors for the bean are specified in Table 14-4.
Table 14-4 Bean deployment descriptors
– After completing the coding, create the access bean and generate the
deployed code. Export the relevant JARs. For the details of EJB
development, refer to the IBM WebSphere Commerce Suite V5.1
Programmer’s Guide.
– We packaged the EJB as com.itso.commerce.newsletter.objects and
created two JARs: newsletterhelper.jar and newsletterhelperimpl.jar.
2.Development of newsletter application controller command.
The actual implementation of this component involves developing the
following:
a.NewsLetterCmd: This interface extends the ControllerCommand and
defines the NewsLetterCmdImpl as the default command implementation.
b.NewsLetterCmdImpl: This command is the main application in sending
the regular newsletter. This command can be invoked as follows:
http://yourhostname/webapp/wcs/stores/servlet/NewsLetter?storeId=storeid
&langId=languageId&subject=newslettersubject&sender=admin@itsoStore&view
=newsletterView&msgtype=newsLetterMessageId
The command performs the following tasks for each invocation:
1.Collects the basic information for the newsletter such as subject, sender,
message type from the requested properties; if not specified, it uses the
default values.
2.Invokes the NewsLetterHelper to identify the list of users interested in
receiving the newsletter.
Deployment descriptors Value
Transaction Attribute TX_REQUIRED
Isolation Level
TRANSACTION_READ_COMMITTED
Run As Mode SYSTEM_IDENTITY
State Management Attribute#STATELESS
TimeOut 0

Chapter 14. Messaging integration
391
3.For each user identified, it does the following tasks:
– It gets the basic user data such as e-mail address (same as logon ID).
– Creates the input property containing the user ID, logon ID and e-mail,
sets the mail headers such as subject, sender, and recipient, and invokes
the SendMsgCmd command to actually send the mail.
This method uses the following methods to accomplish these tasks:
• setRequestProperties(TypedProperty reqProp) is used to collect the
newsletter information for subject, sender, message view and type for
the newsletter. If the parameters are supplied as part of command
execution then it sets them using the appropriate setters.
• isGeneric() returns false, since this command may be accessed by
Administrators only.
• isRetriable() returns true, since this command can be tried within the
scope of current transaction.
• performExecute() method is the core of the command. It invokes
getInterestedUsers() to get the list of interested users and for each
interested user it invokes the sendMail() to compose and send the mail.
The snippet of code listed in Example 14-6 displays this task.
Example 14-6 Example performExecute
public void performExecute() throws ECException {
Enumeration intUsersList = null;
SendMsgCmd sendMailCmd = null;
// invoke the super class method
super.performExecute();
// get the interested userd to send newsletter
try{
intUsersList = getInterestedUsers().elements();
sendMailCmd = (SendMsgCmd)CommandFactory.createCommand(SendMsgCmd.NAME,
getCommandContext().getStoreId());

// iterate on the users list to send the mail
while( intUsersList != null && intUsersList.hasMoreElements())
{
String userid = (String)intUsersList.nextElement();
// sending mail to each user
sendMail(sendMailCmd, userid);
}
} catch(ECException ec)
{

392
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
System.out.println("Error in NewsLetter Sending " + ec);
throw (ECException) ec;
}
catch(Exception e )
{
System.out.println("Error in NewsLetter Sending " + e);
}
}
• getInterestedUsers() returns a vector of interested users by creating
and invoking the findInterestedUsers() method on
NewsLetterAccessBean (see Example 14-7)
Example 14-7 Example getInterestedUsers
public Vector getInterestedUsers() throws
com.ibm.commerce.exception.ECException {
try{
NewsLetterHelperAccessBean nb = new NewsLetterHelperAccessBean();
return nb.findInterestedUsers("Y");
} catch (Exception ec) // the exeptions may be EJB and SQL
{
System.out.println(ec);
throw new ECSystemException
(ECMessage._ERR_GENERIC,this.getClass().getName(),"performExecute()", new
Object[] {ec.toString()}, ec);
}
}
• sendMail( ) actually gets the individual user details such as e-mail
address (same as logon ID) using the UserRegistryAccessBean, sets
the newsletter properties, and then invokes the compose method of
SendMsgCmd command to format the e-mail. Finally it invokes the
execute method of SendMsgCmd to transmit the mail over SMTP to
the relevant user (see Example 14-8).
Example 14-8 Example sendMail
public void sendMail(SendMsgCmd mailSender, String uid) throws ECException {
// used to get the users logon id and email
UserRegistryAccessBean ub = null;
System.out.println("In sendMail");
try{

TypedProperty mailProp = new TypedProperty();
mailProp.put("intUserId", uid);
ub = new UserRegistryAccessBean();
ub.setInitKey_UserId(uid);

Chapter 14. Messaging integration
393
mailProp.put("email",ub.getLogonId());
// for ITSOStore logonid is same as email
mailProp.put("logonId",ub.getLogonId());

mailSender.setMsgType(getNewsletterMsgType());
mailSender.setStoreID(getCommandContext().getStoreId());
// compose the mail using the MailTempalte
mailSender.compose(getNewsLetterView(), getCommandContext(),
mailProp);
mailSender.setConfigData("subject",getSubject());
mailSender.setConfigData("recipient",ub.getLogonId().trim());
mailSender.setConfigData("sender",getSender());
// to support transactional mode use mailSender.sendTransacted()
mailSender.sendImmediate();
mailSender.setCommandContext(getCommandContext());
mailSender.execute();

} catch(Exception ec)
{
System.out.println("Exception in mail sending : " + ec);
throw new ECSystemException
(ECMessage._ERR_GENERIC,this.getClass().getName(),"sendMail()", new Object[]
{ec.toString()}, ec);
}
}
There are no special wizards available in VisualAge for Java to develop
the controller command. You can use a regular class wizard to develop
this and export it as a JAR file.
4.NewsLetterUserInfo
This is a data bean that extends the SmartDataBeanImpl. This bean uses the
DemographicsAccess bean and AddressAccessBean to get user data as
required by the JSP template developer. This command also provides the
user interests as required.
5.NewsLetter.jsp
Note: The NewsLetterView and NewsLetterType that you need to be created
using SQL script and the administration console are explained in 14.1,
“Messaging subsystem architecture” on page 362. For the details of creating a
new outbound message, please refer to the online documentation available
with Commerce Suite.

394
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
This is the actual JSP template that composes the newsletter according to
interests specified by the user. It instantiates the NewsLetterUserInfo data
bean and includes the appropriate topics based on the user’s interests (see
Example 14-9).
Example 14-9 Example NewsLetter.jsp
<%
TypedProperty tp = new TypedProperty();
tp.put("intUserId", JSPHelp.getParameter("intUserId") );
tp.put("email", JSPHelp.getParameter("email") );
tp.put("logonId", JSPHelp.getParameter("logonId") );

NewsLetterUserInfo userInfo = new NewsLetterUserInfo();
userInfo.setRequestProperties(tp);
userInfo.populate();
%>
Dear <%=userInfo.getLastName()%>
<%
// if the user is interested in WebSphere topic include WAS.inc file
if(userInfo.isInterestedIn("WAS") )
{
// check the physical existance of the file before including in JSP
incfile = "/" + storeDir + "/newsletter/wcs.inc";
File f = new File(docRoot , incfile);
if(f.exists() && f.canRead() )
{
%>
<jsp:include page="<%=incfile%>"/>
<%
}
}

Chapter 14. Messaging integration
395
After developing the components, you need to package appropriately using the
Commerce Suite packaging specifications seen in Table 14-5.
Table 14-5 Example news letter packaging
14.3.1 Deployment of components for the newsletter application
This section describes how to deploy the newsletter application to a Commerce
Suite runtime.
1.Ensure that the mail server is running.
2.Ensure Commerce Suite is configured for the e-mail transport.
3.Open the DB2 command-line processor or command window.
a.Connect to the Commerce Suite database and perform steps 1 to 5 listed.
b.Create the NewsLetterView.
insert into viewreg (VIEWNAME, STOREENT_ID, DEVICEFMT_ID, INTERFACENAME,
CLASSNAME, PROPERTIES, INTERNAL) values ('NewsLetterView', 10001, -3,
'com.ibm.commerce.messaging.viewcommands.MessagingViewCommand',
'com.ibm.commerce.messaging.viewcommands.MessagingViewCommandImpl',
'docname=NewsLetter.jsp',1);
c.Create the NewsLetter Message type:
Note: The newsletter application is normally scheduled. In the JSP you can’t
use data bean instantiation using the data bean manager. Since the request is
triggered by the scheduler, which is not a servlet request, you need to use
JSPHelper to get properties and then set the request properties of data bean
and then populate it. This method has the advantage of using HTTP
invocation using URL or using Scheduler.
JAR File components package
newsletterhelper.jar Deployed JAR exported from EJB tab in
VisualAge for Java for
NewsLetterHelper session bean
com.itso.commerce.newslett
er.objects
newsletterhelperimpl.jar Exported and repackaged JAR file of
NewsLetterHelper impl classes and
access bean from projects in VisualAge
for Java
com.itso.commerce.newslett
er.objects
newsletter.jar
Exported classes for NewsLetterCmd
and NewsLetterCmdInterface
com.itso.commerce.newslett
er.commands
Exported class of NewsLetterUserInfo
data bean
com.itso.commerce.newslett
er.beans

396
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
insert into msgtypes (msgtype_id,msgtdir,name,viewname,description)
values (250, 1,'NewsLetterSend','NewsLetterView','Send the NewsLetter')
d.Define the profile type using the console and assign the e-mail transport to
NewsLetter Message. Add the message types by clicking New in the the
Commerce Suite Administration Console.
4.Register the command NewsLetterSend for the newsletter.
insert into CMDREG (STOREENT_ID, INTERFACENAME, DESCRIPTION, CLASSNAME,
PROPERTIES, TARGET) values(10001,
'com.itso.commerce.newsletter.commands.NewsLetterCmd','NewsLetterApplicatio
n','com.itso.commerce.newsletter.commands.NewsLetterCmdImpl','subject=NewsL
etter','Local')
5.Register the URL for the newsletter.
insert into URLREG
(URL,STOREENT_ID,INTERFACENAME,HTTPS,DESCRIPTION,AUTHENTICATED) values
('NewsLetter',0,'com.itso.commerce.newsletter.commands.NewsLetterCmd',1,'IT
SO Store NewsLetter.',1)
6.Copy the JAR files newsletter.jar, newwletterhelper.jar, and
newsletterhelperimpl.jar to the directory <wcs_install_path>/lib.
7.Deploy NewsletterHelper EJB using the WebSphere Administration Console
or XML config.
8.Add newsletterhelperimpl.jar to the server node dependent classpath.
9.Update the Commerce Suite classpath for newsletterhelper.jar,
newsletterhelperimpl.jar, and newsletter.jar in the order described to the
classpath of Commerce Suite application server command-line arguments.
10.Copy the NewsLetter.jsp and newsletter directory to <wcs_store_path>/web/.
11.Restart WebSphere Commerce Server - <wcs_instance> application server
for the changes to take effect.
Testing
After deploying the newsletter components as explained above, restart the
Commerce Suite application server.
1.To test the newsletter delivery issue the following URL:
http://<yourserver>/webapp/wcs/stores/servlet/NewsLetter?storeId=<storeid>&
langId=<languageid>
2.Using Commerce Suite job scheduler to schedule the newsletter to the job
scheduler.

Chapter 14. Messaging integration
397
http://<yourserver>/webapp/wcs/stores/servlet/AddJob?pathInfo=NewsLetter&qu
eryString=storeId%3Dstoreid%26langId=languageid&interval=timeinterval&name=
wcsadmin&start=yyyy:mm:dd:hh:mm:ss&attempts=number&delay=number&URL=returnu
rl
3.To remove the scheduled job
http://<yourserver>/webapp/wcs/stores/servlet/RemoveJob?&jobId=jobid&URL=ur
l
4.To clean the scheduled job:
http://<yourserver>/webapp/wcs/stores/servlet/CleanJob?endTime=yyyy:mm:dd:h
h:mm:ss&jobId=jobid&URL=returnurl

398
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
399
Chapter 15.
Personalization
Personalization means different things to different people. In its most basic form,
personalization is a means of generating unique content customized for a
particular client.
Implementing a personalization strategy is a great way to develop customer
loyalty and complement the marketing campaigns of your Web site. WebSphere
Commerce Suite provides the infrastructure and development tools for
personalizing your Web site.
In this chapter, we explore personalization techniques for WebSphere Commerce
Suite. We will discuss in some detail, rules-based personalization using the
Blaze Advisor Rule Server, shipped with WebSphere Commerce Suite.
The chapter is organized into the following sections:
Personalization overview
Personalization in WebSphere Commerce Suite
Awareness advertising
Suggestive selling
Campaign reports
15

400
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
15.1 Personalization overview
Personalization is about targeting Web content and applications to specific
users. This might mean the simple process of offering a discount to particular
customers or a complex engine that generates recommendations for the
customer based on the pages that they have been viewing.
This is done by gathering and storing information about site visitors, analyzing
the information, and based on the analysis, delivering the right information to
each visitor at the right time.
Elements of a personalization solution include the following:
User profile
– Users of the Web site
– Attributes about the user
– User group and profile membership
Content
– Products to promote, cross-sell or up-sell
– Advertisements
Matching technology
– User profile, rules, collaborative filtering, and collaborative filtering/market
basket analysis or a combination
– Matching the user to the right content
Feedback on personalization effectiveness
– Reports that allow the business users to monitor the success of the
personalization initiatives.
Before we discuss the personalization mechanisms in WebSphere Commerce
Suite, it is probably a good idea to clarify the two basic personalization
technologies used in the market. These include:
Rules-based personalization
Collaborative personalization
15.1.1 Rules-based personalization
Rules-based personalization is by far the simpler flavor of personalization
technologies. Here, content is presented to the user based on pre-defined rules
that map certain attributes of the user to specific content available for
presentation.

Chapter 15. Personalization
401
Rules-based personalization has the following steps:
1.Rules are defined, either in code or administratively, that map certain user
attributes to content available on the server.
For example: “Display an advertisement promoting a discount of 10% on
khaki pants if the shopper has already purchased a cotton shirt”. Such a rule
has two parts:
a.Content to display or hide.
In this case it is the advertisement for khaki pants.
b.Conditions.
In this case, the condition is “If the user purchased a cotton shirt”.
2.When the user does visit the page, the matching engine:
a.Identifies the attributes in question.
In this case that the user has a cotton shirt in the shopping cart.
b.Finds the correct rule.
c.Identifies the content to be presented to the user.
In this case, the content is the correct product, that is khaki pants.
A common variation on this theme is to ask the client to supply the
personalization preferences. For example, the user could specify fashion
preferences as an optional part of the registration form. From the perspective of
the server, such subscription-based models are also very similar to the foregoing
example.
Blaze Advisor Rule Server
Support for rules-based personalization in WebSphere Commerce Suite is
provided by the Blaze Advisor Rule Server. This consists of advertisements and
suggestive selling techniques. This server is incorporated into the WebSphere
Commerce Server.
The rule server is called by the Commerce Suite server, which passes
information based upon the current shopping environment. The rule server
processes this information against a collection of rules created by the merchant
or the marketer, and compiles appropriate output for the particular
circumstances.
The Blaze Advisor Rule Server is completely integrated into the Commerce Suite
product. One of the important results of this is that rules can now be defined by
the business users using only the Commerce Suite Acclerator tool, without any
need for additional coding each time the business requirements behind
personalization change.

402
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
15.1.2 Collaborative personalization
Collaborative personalization is a powerful new technology. This is an adaptive
mechanism where the content that the user sees depends not only on
self-declared preferences and user attribute-based rules, but also on the choices
of other users within a similar group.
Collaborative personalization is built on the following principles:
Consumer preferences are not random.
People who express the same taste in products can recommend products to
others.
The Recommendation Engine uses collaborative filtering/market basket analysis
technology to learn from observed behavior, and based on that behavior, select
the right content to present an appropriate product to recommend.
1.As the shopper visits the site and browses around various pages, various
engines running powerful analysis algorithms silently track the user’s actions.
Examples of these engines include:
– The purchase engine, which tracks the items actually purchased by the
user.
– The clickstream engine. which builds customer profiles based on the
pages that the user views (the click-hrough pattern).
– The item affinity engine, which builds cross sell data based on items that
users are likely to have in their shopping cart at the same time.
– The market basket engine can track items that the user considered
purchasing. These might be items that were added to the shopping cart
but not actually bought.
Multiple such engines can run at the same time.
2.As user traffic flows through the site, the engines build profiles and
correlations based on actions of all users.
For example, the item affinity engine might find that people who bought a
cotton shirt are also likely to buy a pair of summer sandals.
3.When new shoppers visit the site, the engine would then make
recommendations based on these profiles.
Macromedia LikeMinds
The collaborative personalization engine for WebSphere Commerce Suite is
currently provided using Macromedia LikeMinds. Macromedia LikeMinds is an
optional application included with the WebSphere Commerce Suite V5.1, Pro
Edition.

Chapter 15. Personalization
403
Macromedia LikeMinds collects profile information based on a number of
algorithms to develop customer communities. These communities are the
foundation for the subsequent product recommendations. Customers that fit the
profile of a particular community are presented with recommendations based on
the likes of others in the community.
We found that LikeMinds is currently not as seamlessly integrated into
WebSphere Commerce Suite as the Blaze Advisor Rule Server (planned
integration for next release). Integration with LikeMinds requires you to make
changes to the Commerce Suite database schema to accommodate the
collaborative engine.
Integration of LikeMinds with Commerce Suite will not be addressed in this
redbook.
15.2 Personalization in WebSphere Commerce Suite
In this section, we take a closer look at the personalization implementation
available in WebSphere Commerce Suite. WebSphere Commerce facilitates
personalization by enabling the marketing staff to interact with the site directly.
Personalization in WebSphere Commerce Suite is encapsulated in campaigns.
The Commerce Suite Acclerator tool gives the marketing staff many powerful
tools to create and manage campaigns and monitor their effectiveness.
15.2.1 Campaigns
Campaigns serve to organize your marketing efforts. A campaign is the
high-level marketing element that organizes the initiatives that govern the
low-level conditions.
As we noted before, campaigns are typically created by either a marketing
manager or a merchandising manager using the WebSphere Commerce Suite
Acclerator. Campaigns are marketing efforts and they usually have a set of
objectives.
Campaigns are the only marketing element that can be published to the
production server as a unit. Publishing a campaign creates an Advisor Rule
Server Project file Campaign_name.adv. If you are using a multi-tier
environment, you may need to publish project files and the associated rules to
the production server as a separate step.
Campaigns campaigns contain two types of initiatives:
Awareness advertising initiative

404
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
These initiatives are used to display banner advertisements that inform the
user about upcoming events, discounts, special offers, or just increase brand
visibility and awareness. We discuss awareness advertising in detail in 15.3,
“Awareness advertising” on page 412.
Suggestive selling initiative
Suggestive selling initiatives are used to provide product recommendation.
These recommendations are up-sell or cross-sell attempts based on dynamic
criteria such as user attributes, items in shopping cart or past purchases. We
discuss a suggestive selling example in detail in 15.4, “Suggestive selling” on
page 430.
All initiatives contain conditions that govern their visibility and content. Both types
of initiatives have a comprehensive range of conditions.
In our example, the Summer Sale campaign shown in Figure 15-1 on page 405
has four initiatives.
Throughout the campaign, we have an awareness ad campaign banner that
advertises the brand in general.
Also, throughout the campaign, we have a suggestive selling initiative that
pitches specific men’s fashion products to male shoppers and women’s
fashions to female shoppers.
In the last two weeks of the campaign, we pitch a 10% discount to all users on
summer merchandise.
Our suggestive selling initiative now suggests only those products that are in
excess inventory.

Chapter 15. Personalization
405
Figure 15-1 Campaigns
Roles involved
A campaign encompasses many different roles at various points in its execution
cycle. The goal of course is to have little or no programming inputs when the
campaigns are actually created by the marketing manager. This gives the store
absolute flexibility in adapting to changing business requirements for
personalization.
Targeted Advertising
Initiative
Brand Advertising
Initiative
Summer Marketing
Campaign
May 01 -- Aug 31
May 01 -- Aug 31
Targeted Banner Advertisements
to all Customers
Suggestive Selling
Initiative
May01 -- Aug 15

Suggest Mens clothing if
male shopper

Suggest Womens clothing if
female shopper
Aug 15-- Aug 31
10%off ads to all Customers
Suggestive Selling
Initiative
Aug 15-- Aug 31
Suggest inventory > 1000 to all
shoppers
Customer
Profiles
Discounts
User
Groups
(Discounts can also be
targeted to specific user
groups)
Initiatives

406
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Table 15-1 lists the roles involved in the personalization effort.
Table 15-1 Roles involved in campaigns
Campaign design
Campaign creation is not a unidirectional process. Campaigns should have
well-defined business objectives that derive from known business data, user
behavior and expected events (holidays etc.).
After a campaign has been deployed and run, it must be monitored to ensure its
appeal and success with users. Such data can be obtained from numerous
reports that WebSphere Commerce Suite generates. Some of these reports
require Commerce Analyzer to be installed. We discuss reports in 15.5,
“Campaign reports” on page 440.
These statistics can be used to tune existing campaigns and also to drive future
campaigns. Figure 15-2 on page 407 shows an overview of this process.
In addition, one of the most important best practices we identified is to define
your e-marketing spots early - even if there is no immediate need for a given
spot.
This gives the marketing manager immense flexibility in deciding where a
particular marketing element goes without any intervention from the I/T
resources.
Role Tasks Deliverables
JSP Developer * Code the e-marketing spots into JSPs JSP files
System
Administrator
* Create rule services for campaigns.
* Refresh rule services whenever campaigns
are updated.
na
Marketing
manager,
Merchandising
manager
* Define campaigns, campaign initiatives,
and discounts.
* Pick available e-marketing spots defined by
JSP developer.
* Pick from available ad copy defined by
graphics artist or multimedia developer.
Campaign Rules
project.
Graphics artist,
Copy writer
* Create new ad copy marketing text.
* Create multimedia banners.
Multimedia files,
XML files with
marketing text

Chapter 15. Personalization
407
These spots can be defined in the database even if they are not actually coded
into the respective JSPs. WebFashion ships with a number of these spots
predefined, without the corresponding JSP code. However, we do not
recommend deploying the store without coding these spots into the JSP. A lot of
the code can be cut and pasted across the JSPs and the effort to do this up front
is not much greater than writing code for an individual JSP.
Figure 15-2 Campaign life cycle
15.2.2 Customer profiles
Customer profiles provide functionality within the member subsystem that allows
us to group together members into various target or focus groups.
Campaign Life cycle
Design Campaign
Deploy Campaign
Gather Statistics

Campaign Reports

Inventory Reports
Business Data

Inventory

User Data

Click-through HIstory
Business Objectives

Reduce Inventory

Increase Sales

Awareness Ads

Suggestive Selling

Discounts

408
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
A customer profile incorporates registration information, demographics, address
information, customer culture, purchase history, and other miscellaneous
attributes that define a dynamic group of customers. Customer profiles serve as
targets for advertising, promotions, and suggestive selling. You must create
customer profiles before creating campaigns.
Profiles are dynamic groupings because customers belong to them based on
their personal data, and purchase history, both of which may change.
For example, you might want to offer a special promotion to unregistered
customers as an incentive to register. If a new user comes to the site, they would
be able to see the promotion. When the user actually registers, they will no
longer be a part of the profile and will thus not see the promotion.
Customer profiles are created and edited using the Customer Profile notebook in
the Commerce Suite Accelerator. For more information on using the Commerce
Suite Accelerator tool, refer to the fairly detailed online documentation. Additional
information can also be found in“Create a new customer profile” on page 512.
15.2.3 Discounts
Discounts allow you to offer customers incentives to purchase. You can offer
percentage discounts (such as 10% off), or fixed-amount discounts (such as $15
off). Discounts can apply to specific products or to the total purchase.
Discounts are created using the Discount wizard in the Commerce Suite
Accelerator. Once created, the discounts must be published to the production
server. Discounts created using the Loader utility or imported during migration
from previous versions will function correctly, but may not display properly in the
Commerce Suite Accelerator.
Discounts can be either active or inactive. Discounts are set as active by default
when created, but can be deactivated at any time using the Commerce Suite
Accelerator. If you change a published discount from active to inactive, you must
republish the discount to the production server for the change to take effect. For
example, you might want to deactivate a discount before it expires if you notice
that the inventory level for a discounted product is too low for the increased
demand.
Note: Users can also be grouped using user groups. User groups are a static
grouping, because users must be explicitly assigned to these user groups. For
more information, see 11.1.3, “Member groups” on page 265.

Chapter 15. Personalization
409
15.2.4 Implementation example
In this example we shall create a new marketing campaign for marketing summer
merchandise. The campaign shall have the following two initiatives:
An awareness advertising initiative that advertises a10% discount on select
summer merchandise
A suggestive selling initiative that suggests products from men’s fashions
categories to male shoppers and women’s fashion categories to female
shoppers.
To support these initiatives, we will also need to create the following:
Male and Female customer profiles.
A 10% discount to all shoppers.
Prerequisites
Create an instance and publish the ITSO store based on WebFashion.
Enable Rule services and the required components. See 15.1.2,
“Collaborative personalization” on page 402 for directions on how to do this.
For testing purposes, we recommend you disable Commerce Suite caching.
See the online documentation for directions on how to do this.
Enabling campaigns
Here are the steps to enable the Blaze Advisor Rule Server. The following
components are enabled by default, so you may be able to skip this step on a
system with a default installation.
1.Launch the Commerce Suite Configuration Manager by clicking Start ->
WebSphere Commerce Suite -> Configuration.
2.Log in with a valid user ID and password.
3.Expand the tree by clicking <wcs_hostname> -> Instance List ->
<instance_name> -> Components -> RulesSystem.
4.In the right-hand pane, check the Enable component check box, and then
click Apply.
5.In the left-hand tree view, click Components ->
MarketingCenterInfrastructure.
6.In the right-hand pane, check the Enable component check box, and then
click Apply.
7.Restart the WebSphere Commerce Suite <instance_name> application
server from the WebSphere Administration Console.
Role:
System
Administrator

410
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Create discounts
Before we create the actual campaign, we need to create the discounts. These
discounts will be advertised by the awareness advertising campaign.
1.Launch the Commerce Suite Accelerator by entering the following URL in the
Microsoft Internet Explorer browser:
http://<wcs_hostname>/accelerator
2.Log in with marketing manager or higher access.
3.Select the appropriate store and language and click OK.
4.From the top menu, select Merchandise -> Discounts.
5.Click New.
6.On the General Information window, enter the information listed in Table 15-2,
and then click Next.
Table 15-2 Fields and values for discounts
7.On the next window, select Assign this discount to all customers, and then
click Next.
Note: If you installed the VisualAge for Java WebSphere Test Environment,
you might have to do an additional step.
As a part of the VisualAge for Java post-install configuration, you disable rule
services from the <instance_name>.xml file. To use campaigns, you need to
enable rule services again as follows:
1.Open the <instance_name>.xml file in the
<wcs_install>/instances/<instance_name>/xml folder.
For example, C:\ibm\wcs\instances\demo\xml\demo.xml
2.Search for the RuleServices tag in the file and modify it to look like this:
<RuleServices name="Personalization" display="true"
RuleServerEnabled="true">
<CampaignManagement display="true" CampaignEnabled="true"/>
</RuleServices>
Field Value
Name SummerSaleDiscount
Description 10 % discount to support summer sale campaign
Currency USD
Duration Always in effect (for ease of testing)
Role:
Merchandising
manager

Chapter 15. Personalization
411
8.For Discount Type, select Percentage off purchase, and then click Next.
9.For Percentage off total purchase, enter 10.
10.Select Specify a minimum qualification for this discount.
11. Specify the purchase amount as $5.
12.Click Finish.
13.Click OK.
14.On the list of discounts, ensure that the newly created discount is marked
active.
Create customer profile
Next, we create the two customer profiles to support our suggestive selling
campaign. The creation of customer profiles using the Commerce Suite
Acclerator has been described in great detail in “Create a new customer profile”
on page 512.
Refer to those steps to create two customer profiles for male and female
customers called male and female respectively.
Create a campaign
Now that all the initial groundwork is complete, we are ready to create a
campaign. This can be done by the marketing or merchandising manager by
using the WebSphere Commerce Suite Acclerator Web interface.
1.Launch Accelerator. Using Microsoft Internet Explorer launch the following
URL:
http://<wcs_hostname>/accelerator
2.Log in with marketing manager or higher access.
3.Select the appropriate store and language and click OK.
4.From the Marketing Menu, select Campaigns. A list of all the currently
defined campaigns is displayed.
5.On the right hand tool bar, click New...
6.When the Campaign General Definition window appears, enter the following
and then click Next:
– Campaign name: Summer Sale
– Description: Will target customers for summer sale
– Date: type in a valid beginning date.
– Check the Run associated initiatives indefinitely check box.
Role:
Marketing mgr.
Role:
Marketing mgr.

412
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
7.On the next page, type in your name as Campaign Owner and list a
measurable campaign objective. For example: “Campaign to reduce summer
inventory by 50%”.
These are included so that you can compare the objectives against the
results later on.
8.Click OK to complete the wizard, and OK again on the confirmation window.
You will be returned to the campaign’s home page.
In the next two sections, we shall add initiatives to this campaign. To follow
this example uninterrupted, you may skip directly to 15.2.4, “Implementation
example” on page 409.
15.3 Awareness advertising
As a part of a summer marketing campaign, we had defined a discount of 10%
off of every order greater than $20. However, discounts are applied after the
shopper has already made the purchase. So, unless a discounting strategy is
accompanied by a strong and well-planned awareness advertising campaign, we
would only be targeting those shoppers who would have bought the product
anyway!
In this example, we display an advertisement in the sidebar as soon as the
shopper places anything in his or her shopping cart (for example, the shopping
cart totals more than five dollars). While we have simplified the actual business
conditions for generalizing the example, we hope to demonstrate all the basic
tasks involved in creating an awareness advertising campaign.
Suggestive selling initiatives also use e-marketing spots that are very similar to
awareness advertising campaigns, and this example is also a good introduction
to working with e-marketing spots.
The next few sections will take the reader through the steps involved in creating
the awareness advertisement initiative. At a high level, these steps are:
Note: The campaign in the foregoing steps will not become active till two
additional steps are performed:
1.Publish the campaign.
2.Create rule services for the campaign.
We cannot publish a campaign without any initiatives, so we cannot
perform these steps just yet. If you are defining your own campaign
initiatives, remember to perform the steps detailed in sections “Publish the
campaign” on page 429 and “Create a rule service” on page 429.

Chapter 15. Personalization
413
Designing the initiative
Defining and creating the ad copy
Defining and creating the e-marketing spots
Defining the awareness initiative
15.3.1 Designing the initiative
The design phase of an initiative should coincide with the design of the entire
campaign.
We have already discussed the design considerations for campaigns as a whole.
On the other hand, awareness advertising campaigns present some unique
issues as well.
Advertising campaigns require a very tight integration between the actual
banners and the overall purpose of the campaign. Banners can be created using
multiple media such as animated GIFs, Flash, HotMedia, etc. These artifacts are
usually created by graphics artists. Additionally, JSP developers must modify
JSPs to include the banner ads as e-marketing spots.
As we have already stated, to give the marketing manager maximum flexibility in
designing campaigns, we must minimize the coding effort required every time a
new initiative is defined.
These are some of the best practices we identified:
Define a process for managing the publishing and updates to the ad copy.
Ad copy is likely to change frequently. Since it is often created by graphics
artists who may be in a different department or even a different company, it is
important to lay down a process for managing updates to the ad copy.
This involves both updating the file content for the ads and updating database
entries. We explore some options for this in the forthcoming sections.
Generalize advertising e-marketing spots to accommodate all different
collateral or ad copy.
This is more of a programming tip. We have a concrete example of doing this
in 15.3.3, “Defining and creating the e-marketing spots” on page 415.
15.3.2 Defining and creating the ad copy
Ad copy refers to all of the support material created for campaigns. Graphic
artists and writers create ad copy. Ad copy includes graphics that are used in
advertising, or marketing text. The IBM WebSphere Commerce Suite V5.1 online
documentation refers to such copy as collateral.

414
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Currently, there is no GUI interface for creating and defining new ad collateral.
Collateral, therefore, has to be registered manually into the database. The tables
relevant to this discussion are shown in Figure 15-3. As we can see, there are
three tables that are affected. While it is possible to update these tables directly
using SQL, we do not recommend this approach. In this section, we discuss XML
mechanisms for updating these tables.
Figure 15-3 Collateral data model
Collateral type
Advertising banners can be displayed using many different media such as
animated GIF, Flash, Java Applets, HotMedia, etc. Each of these media has
trade-offs with the type of client browser required and the richness of media
content that can be displayed on the banner.
The COLLTYPE table has a list of all the media types supported. WebFashion
currently supports:
Animated GIF
Shockwave Flash
Collateral_ID
Storeent_ID
CollType_ID
Name
URL
Field1
Field2
Collateral
Collateral
Type
CollType_ID
Name
CollType
Collateral_ID
Language_ID
Location
MarketingText
Field1
Field2
CollDesc
Collateral
Description

Chapter 15. Personalization
415
Collateral and collateral description
These tables contain the actual ad copy, including marketing text, URLs to
redirect the user to messages, etc.
The COLLATERAL table contains the following important fields:
The name of the collateral element
The URL that the user should be redirected to
The COLLDESC table contains locale-specific versions of the ad copy. This
includes, principally:
The location of the actual banner media files.
The marketing text to be displayed.
In this example, we discuss adding another medium, HotMedia. We created ad
copy using the HotMedia tool in two languages - English and Spanish. Each
language had different marketing text and a different HotMedia .mvr file.
We will use XML files to publish all this content to the server. Even the ad copy
developers can easily use some simple script files to publish the XML files to the
server.
15.3.3 Defining and creating the e-marketing spots
Once the ad copy has been fully defined, we need to define and create the
e-marketing spots on the various pages. Creating an e-marketing spot has two
different parts:
1.Registering a list of available spots with the database.
The database contains a list of all the available e-marketing spots.
Figure 15-4 shows the structure of the relevant tables.

416
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 15-4 E-marketing spots - partial data model
When the marketing manager begins defining the campaign initiative, he or
she selects an available e-marketing spot from a list that is displayed in the
Commerce Suite Accelerator. The Rules Engine also uses this list to invoke
the right initiative when a campaign is in progress.
Currently, there is no GUI interface for defining these e-marketing spots. We
use an XML-based mechanism to create and update these spots.
2.Modifying the JSPs to include the e-marketing spots.
JSP developers include marketing spots in their JSP by using special data
beans call Marketing Page Elements (MPEs). An MPE is identified by the
name of the marketing spot that it represents.
We use the AwarenessAdvertisementMPE to display a list of marketing
collateral items, which are generated by the Rules System. From the
AwarenessAdvertisementMPE we can then get a list of CollateralDataBeans
that define the ad copy.
Naming conventions are important here because both the marketing manager
and JSP developer must agree on the name of the e-marketing spot. We
recommend using a name that describes the location and type of content
such as “SidebarBottomAd”.
WebFashion ships with about 32 spots defined for suggestive selling. There is
already a spot defined on the sidebar. For the sake of illustration, however,
we create a new spot on the left sidebar bottom for awareness ads. We then
modified the right JSP, in this case sidebar.jsp to include our marketing page
element.
MPE_ID
Storeent_ID
MPEType_ID
Name
Description
MPE
MPEType_ID
Name
Description
MPEType
Current MPE Types are:
* Awareness Advertisement
* Suggestive Selling

Chapter 15. Personalization
417
15.3.4 Creating the awareness initiative
Now that the groundwork for the campaigns is complete, our marketing manager
can create campaigns as the business requirements dictate.
The Commerce Suite Accelerator tool has wizards that enable the marketing
manager to define these campaign initiatives. The high-level steps are as
follows:
1.Create a campaign.
a.Define the name.
b.Define the duration of the campaign.
c.List objectives at the start of campaign so they can be compared against
results.
2.Create an awareness advertising initiative.
a.Define the time period for which the initiative is effective.
b.Define where the ads are displayed.
We can pick from a list of e-marketing spots already defined.
c.Define conditions for the ad. A single awareness advertisement initiative
can have multiple targeted ads that are displayed based on these
conditions. Table 15-3 lists the conditions that can be used.
Table 15-3 Awareness advertising initiative conditions
Condition Description
What
The content to display.
We can choose from a list of previously published ad copy.
Who
Types of customer profiles to target
We can target all users of specific customer profiles that have
been previously defined.
When
Which days of the week the content should be displayed.
Choices include:
• Everyday
• Specific day of the week
• Weekdays
• Weekends

418
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
3.Create a Rule Service using Commerce Suite Admin Console tool.
For our example, we defined an awareness ad campaign initiative called
SummerSaleAd, which advertises a 10% discount on summer merchandise to
run in the SidebarBottomAd e-marketing spot. This ad would show up everyday,
to all customers who have more than $5 worth of goods in their shopping cart.
It is very easy to tailor these conditions to your own business requirements using
the tools that we have just discussed.
15.3.5 Implementation example - awareness advertisement
Let us now detail the steps involved in creating the awareness advertising
campaign initiative from scratch.
In this example we define the advertising campaign initiative to advertise a 10%
discount on summer merchandise. The graphics artists have determined that the
best way to implement this initiative would be to use HotMedia banner ads.
We shall create a new media type (HotMedia) that is supported as collateral.
Ad copy will be available in English and Spanish, and will advertise the 10%
discount.
The ad will redirect users to the catalog display page of the site.
The ad will be displayed everyday to all customers that have a total of more
than $5 worth of goods in their shopping cart.
Which
Which customer behaviors to target.
Targetable customer behaviors include:
• Shopcart contents (product or category)
• Previous purchase (product or category)
• Shopping cart amount (<, = , >)
Condition Description

Chapter 15. Personalization
419
Prerequisites
For details on the prerequisites for creating campaign, refer to “Prerequisites”
on page 409.
Install HotMedia and publish according to instructions in the WebFashion
guide.
Defining and creating the ad copy
The first step is to have ad copy available to use for our campaign.
Define a new media type for collateral

These steps need only be performed if you want to use additional media for
advertisements.
1.In order to add HotMedia as an additional collateral medium to the
COLLTYPE table, the first step is to create a DTD. We can use the
GenerateDTD tool in the Loader package as follows:
GenerateDTD -dbname <db_name> -dbuser <db_user_name> -dbpwd <password>
-tablenames colltype -outfile CollType.dtd
This step needs to be performed just once. We have an example of the
generated DTD, CollType.dtd in the /pzn/LoadCollateralType folder in the
additional materials zip file.
For more information on downloading and using the additional materials zip
file, refer to Appendix D, “Additional material” on page 583.
2.Create an XML file LoadCollaterals.xml as shown in Example 15-1.
Example 15-1 LoadCollaterals.xml
<?xml version="1.0" encoding="UTF-8"?>
<!--Created By Ashish Cowlagi.
Add Additional Collateral types into this XML file.-->
<!DOCTYPE mall SYSTEM "CollType.dtd">
<mall>
<colltype colltype_id="1" name="Image"/>
Note: Admittedly, this is a slightly trivial condition. However, it covers all the
bases and is simple enough to describe here.
An example application of a practical scenario is the case of discount ranges.
Let’s assume we offer a discount of 10% on purchases of $50 or more and
12% on $100 or more. In that case, as soon as the shopping cart total reaches
$40 we could start displaying the ad for the 10% discount. If the shopping cart
is already over $50, then we can start displaying the 12% discount ad.
Role:
Administrator

420
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
<colltype colltype_id="2" name="Flash"/>
<colltype colltype_id="3" name="HotMedia"/>
</mall>
Notice that we reference the DTD file that we created in the previous step.
3.Use the IDResolve tool in the Loader package to create an XML file suitable
for loading.
IDResolve -dbname <db_name> -dbuser <db_user_name> -dbpwd <password>
-infile Colltype.xml -outfile CollTypeRes.xml -method mixed
The mixed method ensures that records already present are just updated.
4.Load the XML data into the database using the Loader utility.
MassLoad -dbname <db_name> -dbuser <db_user_name> -dbpwd <password> -infile
CollTypeRes.xml -method sqlimport
Defining new collateral

The next step is to create new collateral or ad copy for our 10 percent discount
ads. Collateral is already defined in XML files present inside the store archive.
If we were to add the collateral before the store was published, we could just
update the XML files and publish the store. The steps given here assume you
want to do an incremental load after the store was already published.
Note: For the sake of easy maintenance, we included the two existing
media types in this XML file. Since it is a small list, it doesn’t hurt to do this.
In a future step, we see how we deal with existing database records while
loading XML files.
Role:
Graphic artist
Copy writers

Chapter 15. Personalization
421
1.Create a DTD for the Loader XML file as follows:
GenerateDTD -dbname <db_name> -dbuser <db_user_name> -dbpwd <password>
-infile CollateralTables.txt -outfile LoadCollaterals.dtd
This time we chose to supply the table names for the DTD generator using a
separate file called CollateralTables.txt. This file is available in the
/pzn/LoadCollaterals folder in the additional materials zip. The file contains a
list of all tables required for this DTD as shown in Example 15-2.
The complete DTD file is also available in the above folder.
Example 15-2 CollateralTables.txt
storeent
collateral
colltype
colldesc
SAR files and database updates: The foregoing scenario is likely to be a
very common one in a large number of cases. The SAR has XML files that
load a variety of store data, like collateral.
If we want to change or update some of this data after the store has been
published, you have the following options:
Modifying the database directly.
Updating the SAR and republishing
Creating an additional XML file for publishing the updated rows
It is clear that modifying the database can lead to stores that are very hard to
manage, deploy and move between development, test, and production. We
strongly recommend against this practice.
However, deciding between the latter two methods can be a little harder.
Updating the SAR for all changes has the advantage of giving us a single
place to hold all store updates. This immensely simplifies management of a
store. On the other hand, this can be a very time-consuming process and not
suitable for every update.
For this reason, all the database updates in this example are done using
incremental XML updates. However, in all these cases, we also supply the
complete XML file for the SAR in the additional materials zip.
The reader may select either method, or even a combination of the two,
depending on the amount of data being loaded and the development
methodology being applied.

422
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
2.Create the LoadCollaterals.xml file that contains the required Collateral as
shown in Example 15-3
Example 15-3 LoadCollaterals.xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- Created by Ashish Cowlagi -->
<!DOCTYPE mall SYSTEM "LoadCollaterals.dtd">
<mall>
<storeent
1 storeent_id="@storeent_id_1"
member_id="&MEMBER_ID;"
type="S"
identifier="ITSOFashion"/>
<collateral
2 collateral_id="@collateral_id_1"
name="JeansAd"
storeent_id="@storeent_id_1"
colltype_id="3"
url="http://www-4.ibm.com/software/webservers/commerce/servers/"
field1="Test marketing Ad 2 "
field2="10 pc off of any order over 50"/>
<colldesc
collateral_id="@collateral_id_1"
language_id="&en_US;"
3 location="/webapp/wcs/stores/servlet/ITSOFashion/en_US/images/SummerAd.mvr"
marketingtext="For a limited time, get 10% off selected Summer
Merchandise! "
field1="Details..."
field2="field 2 data"/>
<colldesc
collateral_id="@collateral_id_1"
language_id="&es_ES;"
4 location="/webapp/wcs/stores/servlet/ITSOFashion/en_ES/images/SummerAd.mvr"
marketingtext="Por un tiempo limitado, aproveche el 10% descuento en
mercaderia de verano seleccionada."
field1="Detalles..."
field2="field 2 data"/>
</mall>
The storeent tag
1
identifies the store for which this update is being made.
You should substitute the value of the identifier attribute with the name of the
store.
The collateral tag
2
defines the collateral and its basic attributes like URL
and collateral type.

Chapter 15. Personalization
423
Notice the interesting
@collateral_id_1
variable that we use to reference the
next collateral_ID in order. The IDResolver will automatically generate the
right unique identifiers. This allows you to do incremental updates without
worrying about unique ID values. Notice also that you have two data fields
available in this tag.
The colldesc tags
3
define the actual ad copy for the two locales - English
and Spanish. Notice that we specify a different .mvr (HotMedia animation) file
for each of the locales. Notice also that we specify marketing text in the two
languages.
3.Use the IDResolve tool in the Loader package to create an XML file suitable
for loading.
IDResolve -dbname <db_name> -dbuser <db_user_name> -dbpwd <password>
-infile LoadCollaterals.xml -outfile LoadCollateralsRes.xml -method mixed
You can look inside the generated LoadCollateralsRes.xml file to ensure that
the variables have been replaced by proper values of attributes.
4.Load the XML data into the database using the Loader utility.
MassLoad -dbname <db_name> -dbuser <db_user_name> -dbpwd <password> -infile
LoadCollateralsRes.xml -method sqlimport
Publish the ad copy files
Now that we have defined the collateral, we need to publish the HotMedia .mvr
files to the right locations. If you are unfamiliar with HotMedia and .mvr files, the
online documentation for HotMedia has fairly detailed instructions and examples.
Sample mvr files used in this example are available in the /pzn/images folder of
the additional materials zip file.
Publish the SummerAd.mvr, English version file to
<wcs_install>/webapp/wcs/stores/servlet/ITSOFashion/en_US/images/Summer
Ad.mvr.
Tip: If you wish to update the XML files within the SAR, you need to update
three different files.
The collateral tag should be added in the /data/Campaigns.xml file
The colldesc tags should be added in the
/data/<locale>/Campaigns.xml files.
The storeent tag is not required.
Samples of the complete files are provided in the additional materials zip
file under the /pzn folder.
Role:
Graphics artist

424
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Defining and creating the e-marketing spots
We shall now define and create the e-marketing spots.
Define the e-marketing spot
Before we use the e-marketing spot, it needs to be defined in the database. Web
Fashion provides a fairly exhaustive list of e-marketing spots. However, for the
purpose of illustration, we create one called SidebarBottomAd.
1.Create a DTD for the Loader XML file as follows:
GenerateDTD -dbname <db_name> -dbuser <db_user_name> -dbpwd <password>
-infile MPETables.txt -outfile LoadMPE.dtd
The MPETables.txt file is available in the /pzn/LoadMPE folder in the
additional materials zip. The file contains a list of all tables required for this
DTD as shown in Example 15-4.
The complete DTD file is also available in the above folder.
Example 15-4 MPETables.txt
storeent
mpe
mpetype
2.Create the LoadMPE.xml file that contains the required Collateral as shown in
Example 15-5.
Example 15-5 LoadMPe.xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- Created by Ashish Cowlagi -->
<!DOCTYPE mall SYSTEM "LoadMpe.dtd">
<mall>
<storeent
storeent_id="@storeent_id_1"
member_id="&MEMBER_ID;"
Note: The SummerAd.mvr files included in the additional materials zip file are
intended to be placeholders only. They do not employ any inter activity and are
not intended to be examples of good use of the HotMedia technology.
The keen reader may even notice that the sample provided is borrowed from
the WebFashion HotMedia sample, and embellished with a few extra slides!
While we hope that you will excuse this omission, we believe we have laid
down a process that graphics artists can use to independently supply
multimedia content.
Role:
Team effort:
JSP developer
Marketing mgr

Chapter 15. Personalization
425
type="S"
identifier="ITSOFashion"/>
<mpe
mpe_id="@mpe_id_1"
storeent_id="@storeent_id_1"
mpetype_id="2"
1 name="SidebarBottomAd"
description="Display awareness advertisements in the bottom of the
sidebar." />
</mall>
Notice the attribute
1 name="SidebarBottomAd"
. This is what we will use to refer to
this e-marketing spot in JSPs.
3.Use the IDResolve tool in the Loader package to create an XML file suitable
for loading.
IDResolve -dbname <db_name> -dbuser <db_user_name> -dbpwd <password>
-infile LoadMPE.xml -outfile LoadMPERes.xml -method mixed
You can look inside the generated LoadMPERes.xml file to ensure that the
variables have been replaced by proper values of attributes.
4.Load the XML data into the database using the Loader utility.
MassLoad -dbname <db_name> -dbuser <db_user_name> -dbpwd <password> -infile
LoadMPERes.xml -method sqlimport
Modify the JSP to include the e-marketing spot
Now that the e-marketing spot has been defined, we can create the right JSP
using the Awareness Advertising Marketing Page Element (MPE). The sample
JSP is provided in the /pzn/webapp folder in the additional files zip.
1.Although the definition of the marketing spot does not force us to use a
particular JSP, we should be careful to use the appropriate JSP as implied by
the name.
Since we want to place the ad at the bottom of the left sidebar, open the
sidebar.jsp file. This file can be found in the
<wcs_install>/stores/web/<store_name> folder.
Tip: If you wish to update the XML files within the SAR, you need to update
the /data/Campaigns.xml file to add the mpe tag. The storeent tag is not
required.
Samples of the complete files are provided in the additional files zip under the
/pzn folder.
Role:
JSP Developer

426
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
2.Locate the point on the JSP where you want to insert the ad. This can be less
than obvious, so you might want to experiment by inserting some plain text.
You can look inside the solution JSP provided.
3.The first step is to create the MPE and identify it by name. You can limit the
amount of collateral to the amount appropriate for the available screen area.
// Create new awareness ad
AwarenessAdvertisementMPE ad1 = new AwarenessAdvertisementMPE();
// This is how we identify which MPE we want to display
ad1.setName("SidebarBottomAd");
ad1.setMaximumNumberOfItems(new Integer(1));
4.The next step is to use the data beans manager to populate the MPE.
// get Ad 1 Populated
DataBeanManager.activate(ad1,request);
5.Once the bean is populated, we can obtain a list of collateral data beans.
CollateralDataBean[] ads = ad1.getCollateralList();
6.We can then iterate this array to get individual elements. Here is a snippet of
the code used to display the actual ad using information obtained from the
collateral data bean.
<APPLET CODE="hm30.class" NAME="HotMedia" WIDTH="150"HEIGHT="150"
codebase="/hm/" >
<PARAM NAME="mvrfile" value="<%=adCopy.getLocation()%>">
</APPLET>
<BR>
<font class="text"><%= adCopy.getMarketingText()%> </font>
<font class="sidebarhot">
<A HREF=<%= adCopy.getUrlLink()%>>
<%=adCopy.getDescriptionCustomerField1()%>
</A>
</font>
7.The complete code for inserting the MPE is provided in Example 15-6.
Example 15-6 Sidebar.jsp
<%//begin code 6180:pzn %>
<%
// Create new awareness ad
AwarenessAdvertisementMPE ad1 = new AwarenessAdvertisementMPE();
// This is how we identify which MPE we want to display
ad1.setName("SidebarBottomAd");
ad1.setMaximumNumberOfItems(new Integer(1));
// get Ad 1 Populated
DataBeanManager.activate(ad1,request);

Chapter 15. Personalization
427
CollateralDataBean[] ads = ad1.getCollateralList();
for (int i =0; i<ads.length; i++)
{
CollateralDataBean adCopy = ads [i];
%>
<tr>
<td>
<%
if (adCopy.getTypeName().equalsIgnoreCase("Hotmedia"))
// this is the expected type but bad things can happen if its something
// else by mistake
// Also, we can code support for the other types of copy (like flash) here
{
%>
<APPLET CODE="hm30.class" NAME="HotMedia"
WIDTH="150"HEIGHT="150" codebase="/hm/" >
<PARAM NAME="mvrfile" value="<%=adCopy.getLocation()%>">
</APPLET>
<BR>
<font class="text"><%= adCopy.getMarketingText()%></font>
<font class="sidebarhot">
<A HREF=<%= adCopy.getUrlLink()%>>
<%=adCopy.getDescriptionCustomerField1()%>
</A>
</font>
<%
}// if stmt
}//for loop
%>
</td>
<%//end code 6180:pzn %>
Creating the awareness initiative
Now that all the initial groundwork is complete, the marketing manager can
create campaign initiatives as required. This can be done completely using the
WebSphere Commerce Suite Accelerator Web interface.
Create an awareness advertising initiative
8.From the campaign’s home page, select the campaign we just created by
checking the Summer Sale Campaign check box.
9.Click Initiatives.
10.On the campaign Initiatives page, click New.
Role:
Marketing mgr.

428
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
11.Select the Awareness advertisement radio button, then click OK.
12.When the Campaign Initiative General Definition window appears, enter the
following and then click Next:
– Initiative name (required): Disc10Ads
The name that you type here is not the name of the MPE.
– Description: Advertise 10% discount on summer merchandise
– Start date (required): <enter valid start date>
– End date (required): check Run this initiative indefinitely check box.
13.In the next window we will pick where the ad will be displayed. We shall use
the e-marketing spot called SidebarBottomAd that was already defined. Pick
the SidebarBottomAd from the list on the left. Then click Add.
14.Click Next. The campaign initiative conditions window is displayed.
Define conditions for the campaign initiative
We shall now define conditions under which the ads will be displayed. We can
also define multiple conditions here so different ads display under different
conditions.
15.Click New.
16.On the General window of the wizard, type a description for the condition. For
example: 10 pc discount ads display on sidebar for greater than $5 in
shopping cart.
17.Click Next.
18. This window allows you to pick which ads to display. In a previous step we
had created new collateral called Jeans Ad. Select this ad copy from the list
on the left and click <<Add.
19.Click Next.
20.In this condition we shall target all customers. You can also have different ads
that display to different customer profiles -- for example by gender.
Select “Target all customers” and Click Next.
21.Select Everyday and click Next.
22.The “Which customer behaviors should be targeted?” window displays. Click
Add to add a new behavior.
23.From the drop-down list, select Current shopcart greater than.
24.In the input field that appears, type 5 for the amount.
25.Click OK in the initiative condition window.
26.Click OK in the change condition window.

Chapter 15. Personalization
429
27.Click OK in the initiative window.
Publish the campaign
The next steps is to publish the campaign to a rule services project. The
campaign should be published whenever any of its initiatives or conditions
change.
28.From the top menu, pick Merchandise->Campaigns.
29.Select the campaign that we just created by checking the SummerSale.
check box.
30.Click Publish.
Create a rule service
Before creating the rule service, find the rules project that we just published on
the server. This is created as a <initiative>.adv file. In our example, the file was
located in the following folder:
<wcs_install>\instances\demo\rules\repository\UserTemplate\Store10001\C
ampaign\Campaign10152\Deployment\
31.Launch the Commerce Administration Console by typing the following URL
on Microsoft Internet Explorer.
http://<wcs_hostname>/adminconsole
32.Log in as a Store Administrator.
33.Select your store and language. Then click OK.
34.From the top menu select Rule Services --> Administration.
35.The Rule Services list displays. Click Add Service.
36.The Add Rule Service window appears. Create a rule service with the
following parameters:
Table 15-4 Rule service
You may have to increase the number of agents parameter in a production
environment if performance is found to be unacceptable.
Parameter Value
Name of Rule Service SummerSales
Project File name Your Project filename here. For example
C:/WebSphere/wcs/instances/demo/rules/repository/User
Template/Store10001/Campaign/Campaign10152/Deployment
/SummerSale.adv
Number of Agents 2
Session Timeout 60000

430
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Notice the use of forward slashes “/” in the project file name.
37.Click OK to create the rule service. You are brought back to the Rule services
list page. The rule service is created asynchronously so it might not appear
immediately on the list.
If you are using Windows, you can see processor activity from the Windows
Task Manager.
After this activity stops, or after a few minutes, right-click on the browser
window and select Refresh. Click OK in the warning dialog.
38.You should see the rule service in the list.
Testing the awareness advertisement
39.Launch the WebFashion store.
40.Notice that the sidebar has no advertisement at present.
41.Add an item of value greater than $5 to the shopping cart.
42.You should see the HotMedia ad on the sidebar.
Congratulations! Your awareness advertising campaign is now active.
15.4 Suggestive selling
The suggestive selling initiative is the second part of the campaign. In this
suggestive selling initiative, we shall suggest products to customers based on
their customer profiles. We shall suggest items from the men’s fashions
categories for male shoppers and items from the women’s fashion categories for
female shoppers.
In this example, we shall use the store home page (StoreCatalogDisplay.jsp) to
display these suggestive selling spots. We shall suggest appropriate products for
male and female shoppers. We shall be using the customer profiles that we
defined earlier to identify the shopper.
Suggestive selling uses e-marketing spots to display content -- just like
awareness advertising campaigns. Thus, many of the concepts behind creating
suggestive selling campaigns are common with the foregoing section. While we
will point out all the differences, we shall defer to the previous section on
awareness advertising for detailed steps on some of the common concepts.
Note: Every time the campaign project is re-published, you will have to
refresh the rule service from the Administration Console.

Chapter 15. Personalization
431
The next few pages will take you through the detailed steps involved in creating a
suggestive selling initiative. At a high level, those steps are:
Designing the initiative
Defining and creating e-marketing spots
Creating the suggestive selling initiative
15.4.1 Designing the initiative
The design phase of the suggestive selling initiative, should coincide with the
design phase of the entire campaign.
We have already discussed design considerations for campaigns as a whole. We
also identified some specific best practices for suggestive selling initiatives:
For every e-marketing spot that is created to display suggestive selling
content, consider what content will be displayed if none of the personalization
conditions match.
Suggestive selling spots are often placed on strategically important places.
This screen real estate is too valuable to leave empty if no personalization
conditions match.
The StoreCatalogDisplay JSP has an excellent example of how this can be
done.
For every e-marketing spot, set the maximum number of items that can be
displayed, given the amount of screen space available.
This will give marketing managers the flexibility of defining as many products
as they like without having to worry about display considerations.
15.4.2 Defining and creating e-marketing spots
The first step is to define and create e-marketing spots on various pages.
Creating an e-marketing spot has two parts:
1.Registering a list of available spots with the database.
Just like the awareness advertisement spots, suggestive selling spots also
have to be registered with the database. We discussed this process in detail
in “Defining and creating the e-marketing spots” on page 424.
In this section we shall use one on the spots that is pre-defined in
WebFashion.
2.Modifying the JSPs to include the e-marketing spots.

432
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
We also have to code the e-marketing spots into the JSPs as we did the
awareness advertising spots in the previous initiative. As with awareness
advertising spots, suggestive selling spots are also represented by Marketing
Page Elements (MPEs).
For suggestive selling initiatives, we shall use the CatalogEntryMPE, which
displays a list of catalog entries that match the conditions of the initiative for
the current shopper. It also has methods for specifying the default catalog
entries to display in the event that no items are selected by the marketing
content selection system. In addition we use the CatalogEntryDataBean and
CatalogEntryDescriptionAccessBean to display the individual products.
15.4.3 Creating the suggestive selling initiative
Now that the groundwork for the campaigns is complete, our marketing manager
can create campaigns as the business requirements dictate.
The Commerce Suite Accelerator tool has wizards that enable the marketing
manager to define these campaign initiatives. The high-level steps are:
1.Create a campaign.
a.Define the name.
b.Define the duration of the campaign.
c.List objectives at the start of campaign so they can be compared against
results.
In this example, we shall use the SummerSale campaign that we had already
created in 15.2.4, “Implementation example” on page 409.
2.Create a suggestive selling initiative.
a.Define the time period for which the initiative is effective.
b.Define where the suggestive selling spots are displayed.
We can pick from a list of e-marketing spots already defined.

Chapter 15. Personalization
433
c.Define conditions for suggestive selling. A single suggestive selling
initiative can have multiple targeted suggestions that display based on
these conditions. The following conditions can be used:
Table 15-5 Awareness advertising initiative conditions
3.Create a Rule Service using the Commerce Suite Administration Console
tool.
In our example, we use the rule services project that we created in section
15.2.4, “Implementation example” on page 409.
Condition Description
What The products to be shown. Products can be suggested based on:
Specific SKUs, partial SKUs
Category
Product name including partial names
Inventory level range
list price range
availability date
Who Types of customers customer profiles to target
We can target all users of specific customer profiles that have been
previously defined.
When Which days of the week the content should be displayed. Choices
include:
Everyday
Specific day of the week
Weekdays
Weekends
Which Which customer behaviors to target. Targetable customer behaviors
include:
Shopcart contents (product or category)
Previous purchase (product or category)
Shopping cart amount (<, = , >)
Note: When recommending products by SKU, you can either specify a
product or specific items. To specify products, pick the SKUs that have
“product_id” in the SKU. For example, in WebFashion the SKU
sku-@product_id_386 represents the product “Cargo Pants”. The SKU
sku-389 represents a specific item of type “Cargo Pants” with specific
attributes.

434
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
For our example, we defined a suggestive selling campaign initiative called
SummerSaleAd, which advertises a 10% discount on summer merchandise to
run in the SidebarBottomAd e-marketing spot. This ad would show up everyday
to all customers who have more than $5 worth of goods in their shopping cart.
It is very easy to tailor these conditions to your own business requirements using
the tools that we have just discussed.
15.4.4 Implementation example - suggestive selling
Let us now detail the steps involved in creating the suggestive selling initiative
from scratch.
Implementation overview
This initiative will make the suggestions listed in Table 15-6
Table 15-6 Initiative suggestions
The suggestions will be displayed on the store home page.
Prerequisites
See the prerequisites for creating a campaign in “Prerequisites” on page 409.
Defining and creating e-marketing spots
The first step is to define and create the e-marketing spots.
Define the e-marketing spot
As we noted earlier, WebFashion ships with a comprehensive list of e-marketing
spots already defined.
In 15.3.5, “Implementation example - awareness advertisement” on page 418,
we discussed a mechanism for defining custom spots. In this section, we shall
use one of the spots already defined.
The e-marketing spot is called “StoreHomePage”. The XML tag in the
<SAR>/data/Campaigns.xml looks like this:
<mpe
mpe_id="@mpe_id_1"
Customer Profile Suggested products
Male shopper Team Shirt, Jean shorts
Female shopper Body suit, sporty tank top
Anonymous or Guest shopper Items from the New Arrivals category
Role:
Team effort:
JSP developer
Marketing mgr.

Chapter 15. Personalization
435
storeent_id="@storeent_id_1"
mpetype_id="1"
name="StoreHomePage"
description="Display suggestive sellings on your home page."
/>
For now, no action is required.
Modify the JSP to include the e-marketing spot
The StoreHomePage spot displays suggestive selling products on the store’s
home page. This is implemented in the StoreCatalogDisplay.jsp.
Looking inside this JSP, we find that this e-marketing spot has been coded into
the JSP as well. We shall examine the code inside the JSP. However, no coding
is required at this point. The JSP is shown in Example 15-7.
Example 15-7 Partial contents of StoreCatalogDisplay.jsp
// First -- get the top category called HOMEPAGE_PROMO
String promoCategoryId = null;
for (int i = 0; i < topCategories.length; ++i)
{
category = topCategories[i];
if (category.getIdentifier().trim().equals("HOMEPAGE_PROMO"))
{
//For promo category simply store the id.
promoCategoryId = category.getCategoryId();
}
else
{
//Display the regular top level categories.
%>
<!-- HTML Deleted for clarity -->
<!--START PROMO -->
<%
// create the e-Marketing Spot
CatalogEntryMPE productSpot = new CatalogEntryMPE(); 2
// IMPORTANT - set the correct name here
productSpot.setName("StoreHomePage");
productSpot.setMaximumNumberOfItems(new Integer(5));
//Set the default list of promoted products to the
//contents of the HOMEPAGE_PROMO category.
List defaultCatalogEntryIdList = new ArrayList();
Role:
JSP developer

436
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
if (promoCategoryId != null )
{
CategoryDataBean subCategories[];
%>
<jsp:useBean id="promoCategory"
class="com.ibm.commerce.catalog.beans.CategoryDataBean" scope="page">
<%
promoCategory.setCategoryId(promoCategoryId);
promoCategory.setCatalogId(catalogId);
com.ibm.commerce.beans.DataBeanManager.activate(promoCategory, request);
%>
</jsp:useBean>
<%
subCategories= promoCategory.getSubCategories();
ProductDataBean promo_products[] = promoCategory.getProducts();7a
ProductDataBean promo_product;
for (int k = 0; k < promo_products.length; ++k)
{
promo_product = promo_products[k];
defaultCatalogEntryIdList.add(new 7b
Integer(promo_product.getProductID()));
}
}
//Setup the default product id list.
productSpot.setDefaultCatalogEntryIdList(defaultCatalogEntryIdList);7c
//Activate the MPE promotion bean.
DataBeanManager.activate(productSpot, request);3
//Get the list of promoted products.
CatalogEntryDataBean[] productResults = productSpot.getCatalogEntries();4
CatalogEntryDataBean promoProduct = null;
CatalogEntryDescriptionAccessBean prodDesc = null;
for (int i = 0; i < productResults.length; i++) 5
{
promoProduct = productResults[i];
prodDesc = promoProduct.getDescription();
%>
<td align="middle" valign="top" width="200">
<a href="ProductDisplay?catalogId=<%=catalogId%>&storeId=<%= storeId%>
productId=<%= promoProduct.getCatalogEntryID()%> 6
&langId=<%=languageId%>
&parent_category_rn=<%=promoCategoryId%>"
>
<img src="<%=storeDir%>/<%= prodDesc.getFullImage() %>"
alt="<%= prodDesc.getShortDescription()%>"
width="150" height="150" border="0">
</a>

Chapter 15. Personalization
437
<br>
<font class="text">
<%= prodDesc.getLongDescription()%>;
<a href="ProductDisplay?catalogId=<%=catalogId%>
&storeId=<%= storeId%>&productId=<%= promoProduct.getCatalogEntryID()%>
&langId=<%=languageId%>&parent_category_rn=<%=promoCategoryId%>">
<%=infashiontext.getString("DETAILS")%>
</a>
</font>
</td>
<%
} // end for loop
%>
<!--END PROMO -->
The major steps in the JSP are:
1.Locate the point in the JSP where you want to add code.
2.Create the MPE and identify it by name. We also set the maximum number of
items that can be displayed. The default value in the existing
StoreCategoryDisplay.jsp is 5. We recommend changing it to 3.
// create the e-Marketing Spot
CatalogEntryMPE productSpot = new CatalogEntryMPE();
productSpot.setName("StoreHomePage");
productSpot.setMaximumNumberOfItems(new Integer(3));
3.Populate the MPE using the data bean manager:
//Activate the MPE promotion bean.
DataBeanManager.activate(productSpot, request);
4.Get a list of products found in the promotion:
//Get the list of promoted products.
CatalogEntryDataBean[] productResults = productSpot.getCatalogEntries();
5.Iterate over the list to obtain the individual products by using the following
code:
CatalogEntryDataBean promoProduct = null;
CatalogEntryDescriptionAccessBean prodDesc = null;
for (int i = 0; i < productResults.length; i++)
{
promoProduct = productResults[i];
prodDesc = promoProduct.getDescription();

6.Display the individual products by calling methods CatalogEntryDataBean
and CatalogEntryDescriptionAccessBean.

438
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
7.Before we activate the bean, we can also specify the default products to use.
To do this:
a.We get a list of items in the promo category.
b.Create a ProductDataBean containing the default items.
c.Set the default list in the MPE.
Creating the suggestive selling initiative
Now that all the initial groundwork is complete, the marketing manager can
create campaign initiatives as required. This can be done completely using the
WebSphere Commerce Suite Accelerator Web interface.
Notice that in this initiative, we haven’t really done any coding so far, since all the
coding was already there. This serves to underline our strong recommendation
to code all JSPs with the e-marketing spots ahead of time.
Create an awareness advertising initiative
8.From the campaign’s home page, select the campaign we have created by
checking the Summer Sale Campaign check box.
9.Click Initiatives.
10.On the campaign Initiatives page, click New.
11.Select the Suggestive selling radio button, then click OK.
12.When the Campaign Initiative General Definition window appears, enter the
following and then click Next:
– Initiative name (required): Summer Sale
– Description: Pitch summer merchandise based on gender
– Start date: <enter valid start date>
– End date (required): check Run this initiative indefinitely check box.
13.In the next window we will pick where the ad will be displayed. We will use the
e-marketing spot called StoreHomePage that was already defined. Select the
StoreHomePage from the list on the left. Then click Add.
14.Click Next. The campaign initiative conditions window is displayed.
Define conditions for the campaign initiative
We will now define conditions for personalizing the product suggestions. We will
define two conditions here - for male and female shoppers respectively.
15.Click Add.
16.In the General window of the wizard, type a description for the condition. For
example: Pitch Team Shirt, Jean shorts to Male shoppers.
Role:
Marketing mgr.

Chapter 15. Personalization
439
17.Click Next.
18. This page allows you to pick which products to suggest.
19.Select Suggest the following specific product(s).
20.Click Find.
21.In the Name field, type Jean Shorts and click Find.
22.From the list that appears, select the jeans shorts product. This has an SKU
such as sku-@product_id_9999.
23.Click Add.
24.Repeat steps 20 through 23 to add another product, “Team Shirt”, to the SKU
list.
25.Click Next.
26.From the list on the left, select the Male customer profile. Then click Add.
27.Select Everyday and click Next.
28.Click Finish.
29.Repeat step 16 through 28 to create a condition based on Table 15-7.
Table 15-7 Conditions
30.Click OK in the initiative condition window.
31.Click OK in the change condition window.
32.Click OK in the initiative window.
Publish the campaign
The next step is to publish the campaign to a rule services project. The campaign
should be published whenever any of its initiatives or conditions change.
33.From the top menu, select Merchandise->Campaigns.
34.Select the campaign that we just created by checking the SummerSale
check box.
35.Click Publish.
Description Pitch Body suit, sporty tank top to female shoppers
What Suggest the products: Body Suit, Tank top
Who Target the customer profile “Female”
When Everyday
Which Applicable to all shoppers

440
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Refresh the rule services project
Before the campaign becomes active, the administrator needs to refresh the rule
services project.
36.Launch the Commerce Suite Administration Console by typing the following
URL:
http://<wcs_hostname>/adminconsole
37.Log in as a Store Administrator.
38.Select your store and language. Then click OK.
39.From the top menu select Rule Services -> Administration.
40.From the List, select the SummerSale Project and click Refresh.
41.Click OK .
42.The Rule services are updated asynchronously. To find out if the changes
have been committed, select the Summer Sale project again. Then click
View last request.
43.The status should read Completed.
44.Exit the Administration Console.
Testing the awareness advertisement
45.Launch the WebFashion store.
46.Notice the products being displayed on the home page.
47.Log in as a male shopper.
48.Check that specified products are being suggested on the home page.
49.Repeat the test by logging in as a female shopper.
Congratulations! Your suggestive selling campaign is now active.
15.5 Campaign reports
Once the campaign has been deployed, it needs to be monitored on a regular
basis. WebSphere Commerce Suite provides many different reporting options for
this purpose.
User Traffic reports
– Enable user traffic listener
– Very basic
– Show up in analyzer
– No additional components

Chapter 15. Personalization
441
– Samples or details of what they show
Commerce Analyzer reports
– More powerful
– Install commerce analyzer
– Sample types of reports
Note:
For details on installing and configuring Commerce Analyzer, refer to
Appendix C, “WebSphere Commerce Analyzer” on page 555.
For details on accessing reports, refer to 17.3, “Reporting” on page 518.

442
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
443
Chapter 16.
Auctions
The negotiation subsystem provides the elements to create and manage
auctions within WebSphere Commerce Suite. Auctions can be implemented as
part of an existing store, such as a B2C or B2B store, or as an auction-only store.
This chapter describes the components of the negotiation subsystem and
auctions. The example auction highlights the key features of auctions available
using WebSphere Commerce Suite V5.1, Pro Edition, as well as demonstrates
how to create, manage and integrate auctions with an existing store.
This chapter is organized into the following sections:
Negotiation subsystem overview
Auctions in WebSphere Commerce Suite
Auction example overview
Use case 1: create the ITSO store auction
Use case 2: integrate the auction and ITSO store
16

444
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
16.1 Negotiation subsystem overview
The negotiations subsystem includes all logic and data relevant to negotiating or
determining the price and associated quantity of an individual product or set of
products. This subsystem allows you to create and manage auctions, and
includes support for the following tasks:
Create auctions
Create auction styles (templates for creating auctions)
Create bid control rules
Search for auctions
View auctions
Manage auctions
Change existing auctions
Manage bids
Manage discussions about auctions
You can create an auction to be started immediately or at a later date, and
conduct multiple auctions simultaneously. Bidders must read the rules you have
established for the auction before participating. Winners are notified through
messages or e-mail, and orders are placed for the product on auction.
Discussion forums let you communicate with bidders about auctions.
Negotiation subsystem object models
Figure 16-1 shows the relationship between the entity beans containing
information about auction interaction with the order subsystem. When an auction
is closed, the highest bid or bids win the auction, and an order is generated for
each winning bid.

Chapter 16. Auctions
445
Figure 16-1 Negotiations object model - auction and order subsystem view
Additional negotiations object models are as follows:
Auction and bidding view
Auction bid rules view
Customer and auction interaction view
These object models are documented in the IBM WebSphere Commerce Suite
V5.1 online documentation.
URL commands
Table 16-1 contains a list of the URL commands used for auctions.
Table 16-1 Negotiation subsystem commands
Command name Short description
AdminBidDelete Withdraw one or more bids.
AutoBidCreateForm Generate an autobid reference number.
AutoBidDelete Allow customers to withdraw autobids submitted
for Open Cry auctions.
AutoBidSubmit Validate creating and updating autobid input.
AutoBidUpdateForm Provide an autobid modification page.

446
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
BidCreateForm Generate a bid reference number and display a bid
creation page.
BidDelete Allow customers to withdraw bids they have
submitted.
BidSubmit Validate creating and updating bid input.
BidUpdateForm Provide customers with a bid modification page.
CloseBidding Close the bidding for an auction.
CreateAuction Create an auction.
CreateAuctionStyle Create an auction style.
CreateBidRule Create a bid control rule for open cry or sealed bid
auctions.
CreateForumMessage Create an administrator message.
CompleteOrder Create an order.
DeleteAuction Retract an auction.
DeleteAuctionStyle Delete one or more auction styles.
DeleteBidRule Delete a bid control rule.
DeleteMail Mark one or more messages for deletion.
DisplayAuctionBids Generate a list of all bids submitted for open cry
and Dutch auctions.
DisplayAuctionItem Display the product display template for an auction.
DisplayAuctionRules Display the rules for an auction.
DisplayShopperBids Display all the bids submitted by a customer.
DoAuctionNotify Send auction notifications.
FinalizeAuction Initiate order processing.
GalleryDelete Remove an auction from the customer's Auction
Gallery.
GalleryDisplay Display all the auctions present in the customer's
Auction Gallery.
ModifyAuction Update a current or future auction.
Command name Short description

Chapter 16. Auctions
447
16.2 Auctions in WebSphere Commerce Suite
WebSphere Commerce Suite provides an auctioning component to sell products
to the highest bidder. This component provides an environment for implementing
auctions as part of your e-commerce Web site.
This section includes the following topics:
Benefits of auctions
Types of auctions
Auction rules
Auction style
Autobids
CreateAuction command
CleanJob command
Delete obsolete auction records
16.2.1 Benefits of auctions
Understanding when to use auctions and what the benefits are for given
business situations is helpful. Auctions offer special advantages for the following
situations:
When the merchant needs to liquidate inventory.
ModifyAuctionStyle Update an auction style.
ModifyBidRyle Update a bid control rule.
ModifyForumMessage Delete forum messages or change their status from
private to public.
MonitorAuctions Start and close auctions using the schedule.
ProcessAutoBids Process autobids.
ProcessDutchBids Process Dutch auction bids.
ProcessOpenCryBids Process Open Cry auction bids.
ShopperCreateForumMessage Create a customer message.
UpdateGallery Update a customer's Auction Gallery.
Command name Short description

448
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
When the retailer is uncertain about the size of the market and the willingness
of buyers to purchase a product, for example when selling used or
reconditioned products.
When a product price has been set too high initially, and you want to
determine a price controlled directly by market demand.
When the retailer wants to promote new product lines.
16.2.2 Types of auctions
WebSphere Commerce Suite V5.1 supports three types of auctions: open cry,
sealed bid, and Dutch auctions. The Commerce Suite Accelerator provides a
user interface for creating and managing auctions.
Open cry auction
All bids are available for participants to see. Participants may have bids
submitted in open cry auctions automatically by setting up autobids that specify
the maximum bid value and other information.
Sealed bid auction
With sealed bid auctions, the bidder can only view the bids that they have
submitted. They cannot see bids submitted by other users. The auction
administrator can see the details of all bids for each auction. Bidding takes place
over a specified time period; at the end of that period, the highest bid wins.
Dutch auction
Dutch auctions let the auction owner set a price that may be accepted by the
bidder, if not accepted, the price may be lowered or raised.
This is not a true Dutch auction, as implemented in the Dutch Flower Market. A
true Dutch auction uses a continuously decreasing price, similar to a countdown
timer, where a person clicks a button when they are willing to pay the current
displayed price. This person then enters the requested quantity, and the clock is
reset to some higher initial value to start the countdown once again.
The Dutch auction offered in Commerce Suite better fits the “Bargain Basement”
model. For example, prices are reduced once per week until inventory is gone.
You can bid now at the current higher price, or you can wait and take a chance
that the auction item will still be available next week, at a lower price.

Chapter 16. Auctions
449
With Commerce Suite, you may conduct several auctions simultaneously. For
each auction, you establish a set of rules that participants must read before
submitting bids. These rules include details such as the type of auction,
information about the product, the auction schedule, and any special rules for
bidding as defined by the type of auction.
16.2.3 Auction rules
Every auction is governed by a set of rules that the bidder must read before
participating. Auction rules are established when creating an auction and include
items such as the following:
Auction type
Product name
Quantity available
Auction start date and time
Whether a reserve price exists for the auction
The deposit amount to be forfeited if the winner refuses to accept the
auctioned items
The conditions under which the auction will end, such as a scheduled end
date and time
Bid control rules include the following:
– Minimum bid price
– Quantity
– Minimum quantity
This allows the auction owner to specify a minimum quantity for the sale.
For example, if you want to buy this screw, you need to buy at least 100 of
them.
– Bid increment within a price range
Pricing mechanisms for the auction
If auction rules change during an auction, bidders must reread the rules before
submitting or updating bids. Bids submitted prior to a rule change are not
affected and may still win the bidding.

450
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
16.2.4 Auction style
The auction wizard helps you create an auction style, which is a custom template
with default values for the fields when you create the auction. Auction styles are
based on the three types of auctions supported by Commerce Suite (see 16.2.2,
“Types of auctions” on page 448). Auction styles are most useful when standard
and defined rules for auctions are set.
16.2.5 Autobids
Participants may have bids submitted in open cry auctions automatically by
setting up autobids that specify the maximum bid value and other information.
This feature is also known as proxy bidding in other significant auction sites in
the market.
The ProcessAutoBids command uses the maximum bid price, bid quantity and
bid creation time to determine the current leaders. The ProcessAutoBids
command then automatically submits bids for those who have autobid orders to
keep them among the leaders. As a comparison, in a footrace, there is no winner
until after the finish line has been crossed.
Autobids may also be known as order bids, where the user places an order with
the system to bid on their behalf.
16.2.6 Enable scheduler jobs for auctions
Enabling the scheduler to run auction commands is an important first step
towards creating an auction store. The following auction commands are
executed periodically for the auction status to be updated:
MonitorAuctions
ProcessOpenCryBids
ProcessDutchBids
ProcessAutoBids
DoAuctionNotify
CompleteOrder
FinalizeAuction
These commands start and stop auctions, determine the high bid and lowest
winning bid, update the available quantity for Dutch auctions, submit bids from
autobids, send automated messages to customers via e-mail, create an auction
from winning bids, and determine winners for open cry and sealed bid auctions.
Note: Since there can be more than one item on auction, there can be more
than one current winning bid.

Chapter 16. Auctions
451
Auctions use the job scheduler, a component of a commerce server that
schedules and launches jobs according to a timing framework. A job is a
Commerce Suite command scheduled to run at a specified time or interval. For
example, the MonitorAuction command is a scheduler job.
Before working with auctions for the first time, you must activate auction
scheduler jobs by updating the scheduler configuration table (see 16.4.1,
“Activate the job scheduler” on page 456).
16.2.7 CreateAuction command
When creating an auction from the Commerce Suite Accelerator, the
CreateAuction command is executed with the required parameters. The
CreateAuction command creates an auction by completing the following tasks:
Validate availability of product for purchase
Validate for duplicate auctions
Check inventory
Update inventory
Insert into AUCTION table
Update the onauction column in the CATENTRY table
Update the long and short descriptions in the AUCTDESC table
Figure 16-2 displays the syntax for the CreateAuction command.

452
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 16-2 CreateAuction command syntax
16.2.8 CleanJob command
Creating and managing auctions is dynamic, highly time sensitive, and involves a
number of tasks to be executed in the background.
These background tasks are invoked by the job scheduler. The SCHSTATUS
table is updated each time the job scheduler executes a command. Therefore,
over time the SCHSTATUS table can get overloaded with data. In order to keep
the job scheduler performing efficiently, it is important to clean up the tables that
are frequently used by it. The following is a sample command for cleaning up the
schstatus table of the obsolete auction records:
http://<hostname>/webapp/wcs/stores/servlet/CleanJob?endTime=2001:10:05:15:29:0
6&URL=basemall.JSP
The above command will delete all job instance entries in the SCHSTATUS table
that were completed before the time specified, which is 2001:10:05:15:29:06.
http://host_name/path/
CreateAuction?prfnbr=s
&autype=s
CreateAuction
&auldesc=s
&austartprice=s
&aucurprice=s
&aucurquant=s
&ausdesc=s
&auprdmacro=s
&minbid=s
&store_rn=s
&quant=s
&aurulemacro=s
&auruletype=s
&austdate=s
&austtim=s
&auendtim=s
&auenddat=s
&audaydur=s
&autimdur=s
&aubidrule=s
&audeposit=s

Chapter 16. Auctions
453
Figure 16-3 displays the syntax for the CleanJob command.
Figure 16-3 CleanJob command syntax
16.2.9 Delete obsolete auction records
Auctions that have closed, although their status has changed, still have an entry
in the auction table. To delete obsolete auction records, do the following:
1.Ensure that <wcs_install_path>\bin, and <db2_install_path>\bin are in the
PATH environment variable.
2.Change to the directory to which you want log files written.
3.Delete the obsolete auction records by typing the following:
dbclean -table auction -type <typename> -db <database> -days <daysold>
-loglevel <loglevel>
For the -type parameter, you can specify settlement_closed to indicate a
completed auction record, or retracted to indicate a retracted auction.
4.Examine the dbclean.log_yyyy.mm.dd_hh.mm.ss.zzz file to verify that the
command was successful.
16.3 Auction example overview
The auction examples are designed to highlight the auction features within
WebSphere Commerce Suite V5.1, Pro Edition. We have included guidelines,
procedures, and sample code for creating and integrating an auction with the
ITSO store.
http://host_name/path/
CleanJob?
CleanJob
&URL=s
&endTime=s
&langld=s
&jobid=s
Note: The procedure documented above can be used to delete other auction
tables, such as AUCTIONLOG, AUTOBIDLOG, and BIDLOG.

454
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
16.3.1 Requirements
When implementing an auction, we set up an auction for the existing ITSO store
to meet the following requirements:
Liquidate out the off-season products and reduce inventory.
Determine product price, which are controlled directly by market demand.
Promote new product lines.
Make the look and feel of the auction the same as the existing ITSO store
(based on Web Fashion).
16.3.2 Solution outline
WebSphere Commerce Suite V5.1 includes the auctioning components as part
of the negotiation subsystem, and Commerce Suite Accelerator for implementing
and managing auctions. In addition, a sample auction template is provided for
the front-end pages (JSPs) and related properties files.
Analysis
We will use the sample auction template files provided by WebSphere
Commerce Suite V5.1 as a starting point, which we will integrate with the ITSO
store.
Complete the following high-level steps to set up the auction for your store:
Check architecture requirements
Enable scheduler jobs for auctions
Installing sample auction into ITSO store
Update VIEWREG table in store database
– Modify the properties files in the existing ITSO store to provide a link to the
auction.
– Modify the properties files supplied with the sample auction for integration
with the ITSO store.
– Modify the JSPs supplied with the sample auction for integration with the
ITSO store
Note: An update to the VIEWREG table is only required if you install the ITSO
auction into the auction sub-directory rather than the store Web root.

Chapter 16. Auctions
455
Design
We are not required to design any new components. All the components and
commands needed are supplied in the sample auction files provided with
Commerce Suite. Table 16-1 on page 445 shows all the available URL
commands and brief descriptions. Table 16-2 on page 459 shows all the JSPs
involved and their respective view commands.
16.3.3 Auction example use cases
The ITSO auction example includes two use cases that demonstrate how to
implement an auction, and how to integrate the auction with a B2C store.
Use case 1: create the ITSO store auction
In the first use case, we install, configure, and create the ITSO store auction for
use with the sample auction files provided with Commerce Suite.
Use case 2: integrate the auction and ITSO store
In the second use case, we fully integrate the auction with the ITSO store by
adding a link from the ITSO store to the auction and modifying the content JSP
look and feel to match the ITSO store. This requires the modification of many
auction JSPs.
16.4 Use case 1: create the ITSO store auction
In the first use case, we will create an auction using the sample auction files
supplied with WebSphere Commerce Suite V5.1. This section is organized into
the following tasks:
Activate the job scheduler
Install the sample auction files
Note: Prior to modifying the auction, we recommend that you complete the
following steps:
Test the functionality of the store before adding actions.
Use the sample auction files provided with Commerce Suite to verify that
the auction is working properly.
Note: During the modification process, we made an effort to incorporate
best-practices design and code within the JSPs provided by the sample
included with Commerce Suite.

456
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Update the VIEWREG table for auctions
Create an auction from Commerce Suite Accelerator
Verify the auction
16.4.1 Activate the job scheduler
To activate the job scheduler for auctions, complete the following steps:
1.Change to the directory of the wcs.auction.sql script listed by platform:
Windows <wcs_install_path>\schema
AIX/usr/lpp/CommerceSuite/schema
Solaris/opt/WebSphere/CommerceSuite/schema
2.Modify the sender e-mail address in the wcs.auction.sql script, by replacing
the host@<hostname> with your preferred e-mail address. This is the
address that displays as the originator of auction related messages sent from
the system (for example, host@m23vnx58.itso.ral.ibm.com). Example 16-1
displays our modified wcs.auction.sql.
Example 16-1 Sample wcs.auction.sql
update schconfig set sccactive='A' where sccpathinfo in ('MonitorAuction',
'ProcessOpenCryBids', 'ProcessDutchBids', 'ProcessAutoBids', 'DoAuctionNotify',
'CompleteOrder', 'FinalizeAuction');
update schstatus set scsstate='I' where scsjobnbr in (2052, 2053, 2054, 2055,
2056, 2057, 2058);
insert into iseditatt values
(11,11,1,'sender','host@m23vnx58.itso.ral.ibm.com');
insert into iseditatt values
(12,12,1,'sender','host@m23vnx58.itso.ral.ibm.com');
insert into iseditatt values
(13,13,1,'sender','host@m23vnx58.itso.ral.ibm.com');
insert into iseditatt values
(14,14,1,'sender','host@m23vnx58.itso.ral.ibm.com');
insert into iseditatt values
(15,15,1,'sender','host@m23vnx58.itso.ral.ibm.com');
insert into iseditatt values
(16,16,1,'sender','host@'m23vnx58.itso.ral.ibm.com');
insert into iseditatt values
(17,17,1,'sender','host@m23vnx58.itso.ral.ibm.com');
insert into iseditatt values
(18,18,1,'sender','host@m23vnx58.itso.ral.ibm.com');
3.Start a DB2 command prompt by clicking Start -> Programs -> IBM DB2 ->
Command Window.
4.Connect to WebSphere Commerce Suite store database.

Chapter 16. Auctions
457
db2 connect to <wcs_database>
Replace <wcs_database> with your Commerce Suite database name (for
example, our Commerce Suite store database name is WCS).
5.Execute the wcs.auction.sql script to enable the Commerce Suite job
scheduler, by typing the following:
db2 -tvf <wcs_install_path>\schema\wcs.auction.sql
Replace <wcs_install_path> with your Commerce Suite installation path (for
example, c:\ibm\wcs).
Commerce Suite is now enabled to process auction commands and bids.
16.4.2 Install the sample auction files
To use the sample auction files (JSPs, images, HTML) provided with Commerce
Suite, you must copy these files from the directories where they were originally
installed into store directories.
To install the sample auction files for the ITSO store directory, do the following:
1.Create an auction directory for your store.
For example:
c:\ibm\wcs\stores\web\itso\Auction
2.Copy the auction sample JSP files to your store auction directory.
For example:
copy c:\ibm\wcs\samples\web\Auction\*.* c:\ibm\wcs\stores\web\itso\Auction
Note: This redbook includes installation instructions only for WebSphere
Commerce Suite V5.1, Pro Edition for Windows NT and Windows 2000.
For other platforms, refer to the IBM WebSphere Commerce Suite V5.1 online
documentation.

458
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
3.Copy the auction sample locale-neutral images to your store images
directory.
For example:
copy c:\ibm\wcs\samples\web\Auction\images\*.*
c:\ibm\wcs\stores\web\itso\images
4.Copy the auction sample locale-specific images to your store locale images
directory.
For example:
copy c:\ibm\wcs\samples\web\Auction\images\*.*
c:\ibm\wcs\stores\web\itso\images
5.Copy the auction sample properties file (locale specific) to your store
properties directory.
For example:
copy c:\ibm\wcs\samples\properties\AuctionSample_en_US.properties
c:\ibm\wcs\stores\properties\itso
6.Copy the sample address properties file (locale specific) to your store
properties directory.
For example:
copy c:\ibm\wcs\samples\properties\Address_en_US.properties
c:\ibm\wcs\stores\properties\itso
Note:
The address.jsp and register.jsp files will be copied into an auction folder
but we will not use it. These files we will use com from the
<wcs_install_path>\stores\web\itso\ folder. You may delete these two files
or you can keep them for reference.
An alternative way of adding the sample auction to your existing store
would be to use WebSphere Commerce Studio. For details on how to
enable the sample auction store in your store, see WebSphere Commerce
Suite V5.1 Handbook, SG24-6167.

Chapter 16. Auctions
459
16.4.3 Update the VIEWREG table for auctions
For the purposes of better organizing our Web assets, we created the auction
folder to contain auction Web assets for the ITSO store. As a result, we need to
update the VIEWREG table within our store database to reflect the auction
directory. Table 16-2 lists the viewname and properties stored within the
VIEWREG table for the ITSO store database.
Table 16-2 Viewnames and new property values that need to be updated
Note: The procedure of copying files directly to the running store is OK for test
purposes, but not recommended for a controlled development environment.
The recommended method is to import the auction files and directory structure
documented above into WebSphere Studio, modify the content, publish the
files to the local file system and create a new SAR file for deployment.
Viewname Properties
AuctionAckView docname=Auction/auc_bid_ack.jsp
AuctionErrView docname=Auction/aucerr.jsp
AuctionSample docname=Auction/Auction.jsp
AuctionLogon docname=Auction/AuctionLoginForm.jsp
AuctionStoreSelection docname=Auction/auc_storeselection.jsp
AuctionRulesView docname=Auction/auc_rule.jsp
AutoBidCreateFormView docname=Auction/auc_autobid_create.jsp
AutoBidSubmitErrorView docname=Auction/auc_err_bid_submit_frame.jsp
AutoBidUpdateFormView docname=Auction/auc_autobid_modify.jsp
BidCreateFormView docname=Auction/auc_bid_create.jsp
BidListView docname=Auction/auc_all_bids.jsp
BidSubmitErrorView docname=Auctionauction/auc_err_bid_submit_fra
me.jsp
BidUpdateFormView docname=Auction/auc_bid_modify.jsp
ShopperAuctionListView docname=Auction/auc_shopper_auction_list.jsp
ShopperBidListView docname=Auction/auc_shopper_bid_list.jsp
AdminBidDeleteAckView docname=Auction/aucbidm.jsp

460
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
BidOverrideView docname=Auction/BidOverride.jsp
BidOverrideSubjectView docname=Auction/BidOverrideSubject.jsp
StartAuctionView docname=Auction/StartAuction.jsp
StartAuctionSubjectView docname=Auction/StartAuctionSubject.jsp
WinnerView docname=Auction/Winner.jsp
WinnerSubjectView docname=Auction/WinnerSubject.jsp
CompleteOrderView docname=Auction/CompleteOrder.jsp
CompleteOrderSubjectView docname=Auction/CompleteOrderSubject.jsp
DisplayHomeView docname=Auction/auc_home.jsp
DisplayMailBoxView docname=Auction/auc_mail_box.jsp
ShopperForumMsgListView docname=Auction/auc_shopper_msg_list.jsp
ShopperAddMsgView docname=Auction/auc_msg_add.jsp
ShopperAppendMsgView docname=Auction/auc_msg_append.jsp
BidFormView docname=Auction/auc_bidform.jsp
AutoBidFormView docname=Auction/auc_autobidform.jsp
BestBidView docname=Auction/auc_show_best_bid.jsp
MailListView docname=Auction/auc_maillist.jsp
MailDisplayView docname=Auction/auc_mail_display.jsp
AuctionHomeView docname=Auction/auc_main_home.jsp
DisplayMenuView docname=Auction/auc_navigation.jsp
ShowTimeView docname=Auction/auc_show_time.jsp
Viewname Properties

Chapter 16. Auctions
461
To update the VIEWREG table, do the following:
1.Start a DB2 Command window by clicking Start -> Programs -> IBM DB2 ->
Command Window.
2.Connect to the WebSphere Commerce Suite store database as follows:
db2 connect to <wcs_database>
Replace <wcs_database> with your Commerce Suite store database name
(for example, WCS).
3.The VIEWREG table will need to be updated for all of the viewnames listed in
Table 16-2 on page 459.
a.To update the VIEWREG table one entry at a time, use the following
command for each entry in Table 16-2 on page 459:
update <table_schema>.viewreg set properties =
'docname=Auction/auc_bid_ack.jsp' where viewname = 'AuctionAckView';
b.To automate this process of updating the VIEWREG table, we have
included in the additional materials SG246180.zip a script called
update_auc_viewreg.sql, which can be run as follows:
cd \<unzip_path>\sg246180\auctions\schema
db2 -tvf update_auc_viewreg.sql
16.4.4 Create an auction from Commerce Suite Accelerator
In order to create an auction using the Commerce Suite Accelerator, you need
access to the merchandising menu. Access to the merchandising menu requires
access group privileges when logged in as a merchandising manager, site
administrator, or merchant.
This section describe the following tasks for creating and managing auctions
using the Commerce Suite Accelerator:
Creating an open cry auction using a style
Creating a bid control rule for a sealed bid auction
Creating a sealed bid auction with a bid control rule
Note: You can update the table using the DB2 Control Center or by using an
SQL script, which we provide called update_auc_viewreg.sql. The script can
be found in the additional material, in the
<unzip_path>\sg246180\auctions\schema folder.
If you decided to uninstall auction then run rollback_auc_viewreg.sql found in
the <unzip_path>\sg246180\auctions\schema folder.

462
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Creating a Dutch auction
Retracting an auction
Changing an auction
Creating an open cry auction using a style
To create an open cry auction, do the following:
1.Launch the Commerce Suite Accelerator by typing the following URL in the
Microsoft Internet Explorer:
http://<hostname>/accelerator
2.Log on to Commerce Suite Accelerator as a user with access group
permissions of one of the following: merchandising manager, site
administrator, or merchant (for example, we used wcsadmin).
3.Select the store and language.
4.Before entering the auction, it is important to know the product SKU and
quantity of the product available in inventory that you would like to auction. To
find the quantity of inventory for a given SKU do the following:
a.From the Accelerator menu bar, select Merchandise -> Products.
b.When the Available Products page appears, select the desired product
and click Change. For example, Bomber jacket sku-245.
c.From the left-hand panel of the product wizard, click Inventory. The
resulting page looks like Figure 16-4.
Note: Take note of the available inventory for the SKU, current inventory 97
for sku-235.

Chapter 16. Auctions
463
Figure 16-4 Inventory of product with SKU sku-235
5.From the Commerce Suite Accelerator menu bar, select Merchandise ->
Auctions.
6.The next page provides the option of creating a new auction or finding an
existing auction. Click New.
7.When the Auction Type page appears, select Create auction using style,
select Custom_Open_Cry from the pull-down list, and then click Next.
8.When the Auction Product page appears, enter the product SKU. If you do
not know the SKU, click Find to search for a product SKU by name.
9.When the Find Product page appears, enter Bomber jacket in the Name field
and then click Find. A results window should be displayed with all Bomber
Jacket SKUs.

464
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
10.Select the check box beside the product SKU you want to auction, and then
click OK. For example, we selected sku-235.
11.After returning to the Auction Product page, enter the quantity that you would
like to auction, and click Next. For example, we entered 10.
12.When the Auction Duration page appears, enter the following and then click
Next:
– Start date: <year, month, day>
– Start time: <time in 24-hour format>
– End date: <year, month, day>
– End time: <time in 24-hour format>
You can also set a rule for closing the auction based on the number of days
with no bids.
13.When the Pricing page appears, enter the following and then click Next:
– Currency: USD
– Deposit: (If any deposit is required to bid on this auction)
– Reserve price: (To win the auction you need to at least meet the reserved
price).
– Pricing mechanism: select either NonDiscriminative or Discriminative.
14.When the Display page appears, which specifies what template to use in
displaying auction rules and the product display for an auction, enter the
following and then click Next.
– Auction rule template: Auction/auc_rule.jsp (required, default JSP)
Note: Although check boxes are available for each product row, selecting
more than one check box disables the OK button. Therefore, you will be able
to select only one product at a time to create an auction.
Note: The validation for the available quantity is checked at this point.
Therefore it would be wise to confirm the availability of the quantity you wish to
auction by querying the INVENTORY table. You can do this either manually or
by using Commerce Suite Accelerator.
Note: If you are using an auction style, you may now click Finish or click Next
to specify more auction options.

Chapter 16. Auctions
465
– Product display: Auction/auc_ItemDisplay.jsp (required, default JSP)
– Short description: Bomber jacket
– Long description: Bomber jacket
15.The Auction Bid Control Rule page appears. If you have already created and
saved a bid rule, it can be assigned to the auction. Refer to 16.2.3, “Auction
rules” on page 449 for instructions on how to create a bid rule.
16.After clicking Finish, you should see a message like the following:
Auction created successfully. Auction ID is 10001.
If you do not see this, it is possible that the inventory is less than the number
you entered to auction. The auction creation pages do not provide a way to
find the available quantity. As indicated earlier, find the available quantity by
querying the INVENTORY and CATENTRY tables. For example, the following
query will return the available quantity for a product with the name “jacket”,
partnumber sku-235 and in the store with an ID of 10001:
select i.quantity from catentdesc c, inventory i, catentry ce where
ce.partnumber like '%sku-235%' and c.name like '%jacket%' and c.catentry_id
= ce.catentry_id and ce.catentry_id = i.catentry_id and i.store_id = 10051
17.Your auction is now ready for bidding on its start date. To view a summary of
the auction you created, go to the Auctions page and select the auction. Click
Summary. It will display the Auction Summary page with the information
shown in Table 16-3.
Table 16-3 Auction summary
Note: In our example, we created a subdirectory called Auction off of the root
of the store directory (..\web\<store>\Auction). We separated the main store
JSPs and auction JSPs to avoid conflicts and provide better organization of
the files. As a result of creating a separate Auction directory for the auction
JSPs, the template file name for product display must be prefixed as follows:
Auction/<template_file_name>
For example:
Auction/auc_ItemDisplay.jsp
In addition, the VIEWREG table must be updated to reflect this path (see
16.4.3, “Update the VIEWREG table for auctions” on page 459).
Field Description
Auction ID The unique ID assigned by the system to each auction.
Auction type The type of auction: Open Cry, Sealed Bid, or Dutch.

466
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Creating a bid control rule for a sealed bid auction
To create a bid control rule for a sealed bid auction, do the following:
1.Launch the Commerce Suite Accelerator by typing the following URL in the
Microsoft Internet Explorer:
http://<hostname>/accelerator
2.Log on to Commerce Suite Accelerator as a user with access group
permissions of one of the following: merchandising manager, site
administrator, or merchant (for example, we used wcsadmin).
3.Select the store and language.
Auction status The auction status: future, current, closed, or settlement
closed.
SKU The SKU of the product on auction.
Product name The name of the product on auction.
Product short description A short description of the product on auction.
Rule template The JSP page that will be used to display the rules for
this auction. In this case, the page is provided with the
auction sample.
Product template The JSP page that will be used to display the product on
auction. In this case, the page is provided with the
auction sample.
Bid control rule name The name of a bid control rule, if one had been defined
for this auction.
Currency The store selected currency.
Quantity The quantity of products to be auctioned.
Reserve price The reserve price, if one had been defined for this
auction. This is the price below which bids are not
accepted.
Deposit The amount of the deposit, if one had been required for
this auction.
Start date The start date and time of the auction.
End date The end date and time of the auction.
Short description A short description of the auction, if one had been
included.
Field Description

Chapter 16. Auctions
467
4.From the Commerce Suite Accelerator menu bar, select Merchandise -> Bid
Control Rules.
5.When the Bid Control Rule List page appears, click New.
6.When the General page appears, enter the following and then click Next:
– Name: <Bid rule name> (required)
– Description: Bid control rule name
– Type: select Sealed Bid
7.When the Rule page appears, enter the following and then click Finish:
– Minimum bid amount: 10 (example)
– Minimum bid quantity: 1 (example)
The newly created bid control rule is ready to use for sealed bids. When you
created a new sealed bid, you can see this rule on the Auction Bid Control Rule
page as one of the options in the pull-down list.
Creating a sealed bid auction with a bid control rule
To create a sealed bid auction with a bid control rule, do the following:
1.Launch the Commerce Suite Accelerator by typing the following URL in the
Microsoft Internet Explorer:
http://<hostname>/accelerator
2.Log on to Commerce Suite Accelerator as a user with access group
permissions of one of the following: merchandising manager, site
administrator, or merchant (for example, we used wcsadmin).
3.Select the store and language.
4.From the Commerce Suite Accelerator menu bar, select Merchandise ->
Auctions.
5.The next page provides the option of creating a new auction or finding an
existing auction. Click New.
6.When the Auction Type page appears, select Create auction using style,
select Custom_Sealed_Bid from the pull-down list, and then click Next.
7.When the Auction Product page appears, enter the product SKU. If you do
not know the SKU, click Find to search for a product SKU by name.
Note: To create the bid control rule for the open cry auction type, follow the
same steps as for a sealed bid except in the General page choose the Open
Cry option instead of the Sealed Bid option.

468
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
8.When the Find Product page appears, enter Bomber jacket in the Name field
and then click Find. A results window should be displayed with all Bomber
Jacket SKUs listed.
9.Select the check box beside the product SKU you want to auction, and then
click OK. For example, we selected sku-235.
10.After returning to the Auction Product page, enter the quantity that you would
like to auction, and click Next. For example, we entered 10.
11.After returning to the Auction Product page, enter the quantity that you would
like to auction, and click Next. For example, we entered 10.
12.When the Auction Duration page appears, enter the following and then click
Next:
– Start date: <year, month, day>
– Start time: <time in 24-hour format>
– End date: <year, month, day>
– End time: <time in 24-hour format>
You can also set a rule for closing the auction based on the number of days
with no bids.
13.When the Pricing page appears, enter the following and then click Next.
– Currency: USD
Note: Although check boxes are available for each product row, selecting
more than one check box disables the OK button. Therefore, you will be able
to select only one product at a time to create an auction.
Note: Although check boxes are available for each product row, selecting
more than one check box disables the OK button. Therefore you will be able to
select only one product at a time to create an auction.
Note: The validation for the available quantity is checked at this point.
Therefore it would be wise to confirm the availability of the quantity you wish to
auction by querying the INVENTORY table. You can do this either manually or
by using Commerce Suite Accelerator.
Note: If you are using an auction style, you may now click Finish or click Next
to specify more auction options.

Chapter 16. Auctions
469
– Deposit: (If any deposit is required to bid on his auction)
– Reserve price: (To win the auction you need to at least meet the reserved
price).
– Pricing mechanism: select either NonDiscriminative or Discriminative.
14.When the Display page appears, which specifies what template to use in
displaying auction rules and the product display for an auction, enter the
following and then click Next.
– Auction rule template: Auction/auc_rule.jsp (required, default JSP)
– Product display: Auction/auc_ItemDisplay.jsp (required, default JSP)
– Short description: Bomber jacket
– Long description: Bomber jacket
15.The Auction Bid Control Rule page appears. If you have already created and
saved a bid rule, it can be assigned to the auction. Refer to 16.2.3, “Auction
rules” on page 449 for instructions on how to create a bid rule.
16.After clicking Finish, you should see a message like the following:
Auction created successfully. Auction ID is 10001.
17.Your auction is now ready for bidding on its start date. To view a summary of
the auction you created, go to the Auctions page and select the auction. Click
Summary.
Creating a Dutch auction
To create a Dutch auction, do the following:
1.Launch the Commerce Suite Accelerator by typing the following URL in the
Microsoft Internet Explorer:
http://<hostname>/accelerator
Note: In our example, we created a sub directory called Auction off of the root
of the store directory (..\web\<store>\Auction). We separated the main store
JSPs and auction JSPs to avoid conflicts and provide better organization of
the files. As a result of creating a separate Auction directory for the auction
JSPs, the template file name for product display must be prefixed as follows:
Auction/<template_file_name>
For example:
Auction/auc_ItemDisplay.jsp
In addition, the VIEWREG table must be updated to reflect this path (see
16.4.3, “Update the VIEWREG table for auctions” on page 459).

470
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
2.Log on to Commerce Suite Accelerator as a user with access group
permissions of one of the following: merchandising manager, site
administrator, or merchant (for example, we used wcsadmin).
3.Select the store and language.
4.From the Commerce Suite Accelerator menu bar, select Merchandise ->
Auctions.
5.The next page provides the option of creating a new auction or finding an
existing auction. Click New.
6.When the Auction Type page appears, select Create auction using style,
select Custom_Dutch from the pull-down list, and then click Next.
7.When the Auction Product page appears, enter the product SKU. If you do
not know the SKU, click Find to search for a product SKU by name.
8.When the Find Product page appears, enter Bomber jacket in the Name field
and then click Find. A results window should be displayed with all Bomber
Jacket SKUs listed.
9.Select the check box beside the product SKU you want to auction, and then
click OK. For example, we selected sku-235.
10.After returning to the Auction Product page, enter the quantity that you would
like to auction, and click Next. For example, we entered 10.
11.When the Auction Duration page appears, enter the following and then click
Next:
– Start date: <year, month, day>
– Start time: <time in 24-hour format>
– End date: <year, month, day>
– End time: <time in 24-hour format>
12.When the Auction Pricing page appears, enter the following and then click
Next:
Note: Although check boxes are available for each product row, selecting
more than one check box disables the OK button. Therefore, you will be able
to select only one product at a time to create an auction.
Note: The validation for the available quantity is checked at this point.
Therefore it would be wise to confirm the availability of the quantity you wish to
auction by querying the INVENTORY table. You can do this either manually or
by using Commerce Suite Accelerator.

Chapter 16. Auctions
471
– Currency: USD
– Offer Price: (required)
13.When the Display page appears, which specifies what template to use in
displaying auction rules and the product display for an auction, enter the
following and then click Next:
– Auction rule template: Auction/auc_rule.jsp (required, default JSP)
– Product display: Auction/auc_ItemDisplay.jsp (required, default JSP)
– Short description: Bomber jacket
– Long description: Bomber jacket
14.After clicking Finish, you should see a message like the following:
Auction created successfully.
Retracting an auction
Sometimes you decide not to hold a particular auction you previously scheduled.
To stop an auction from taking place (retract), do the following:
1.Launch the Commerce Suite Accelerator by typing the following URL in the
Microsoft Internet Explorer:
http://<hostname>/accelerator
2.Log on to Commerce Suite Accelerator as a user with access group
permissions of one of the following: merchandising manager, site
administrator, or merchant (for example, we used wcsadmin).
3.Select the store and language.
4.From the Commerce Suite Accelerator menu bar, select Merchandise ->
Auctions.
Note: In our example, we created a sub directory called Auction off of the root
of the store directory (..\web\<store>\Auction). We separated the main store
JSPs and auction JSPs to avoid conflicts and provide better organization of
the files. As a result of creating a separate Auction directory for the auction
JSPs, the template file name for product display must be prefixed as follows:
Auction/<template_file_name>
For example:
Auction/auc_ItemDisplay.jsp
In addition, the VIEWREG table must be updated to reflect this path (see
16.4.3, “Update the VIEWREG table for auctions” on page 459).

472
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
5.When the Auction page appears, select the auction you wish to retract. Click
Retract to retract the auction.
6.A confirmation window will appear. Click OK. The Auctions page refreshes to
show the status change.
Changing an auction
For future auctions, you can change all parameters. For current auctions, you
can change the following:
End date/time (postpone only)
Quantity (increase only)
Offered price (Dutch auctions only)
To change the quantity to be auctioned, do the following:
1.Launch the Commerce Suite Accelerator by typing the following URL in the
Microsoft Internet Explorer:
http://<hostname>/accelerator
2.Log on to Commerce Suite Accelerator as a user with access group
permissions of one of the following: merchandising manager, site
administrator, or merchant (for example, we used wcsadmin).
3.Select the store and language.
4.From the Commerce Suite Accelerator menu bar, select Merchandise ->
Auctions.
5.When the Auction page appears, select the auction you wish to change. Click
Change.
6.When the Auction Product page appears, update the quantity to your desired
number. Click OK.
The Auctions page displays, showing the updated quantity.
16.4.5 Verify the auction
Now that the auction is enabled, the auction files have been copied, and the
store database has been updated, the auction is ready to be verified.
1.To access the auction sample, enter the following URL in a Web browser:
http://<hostname>/webapp/wcs/stores/servlet/AuctionSample?storeId=<storeID>
Note: After clicking OK to confirm the retraction, this action cannot be undone.

Chapter 16. Auctions
473
Where <hostname> is your server hostname, and <storeID> is your store
reference number.
For example:
http://m23vnx58.itso.ral.ibm.com/webapp/wcs/stores/servlet/AuctionSample?st
oreId=10201
You should see a welcome page like Figure 16-5.
Figure 16-5 Sample auction welcome page
2.Log in as a registered user from the ITSO store (Web Fashion).
3.Choose the store you want to view auctions for and click OK.
4.You should now see the auction home page as seen in Figure 16-6.

474
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure 16-6 Sample auction home page
5.Depending on your auction start date and time, you can click Current
Auctions or Future Auctions to see the auction.
16.5 Use case 2: integrate the auction and ITSO store
In use case 2, we describe how to integrate an auction with the ITSO store. The
integration effort includes the following objectives:
Provide links from the ITSO store and auction
We will provide two links, one from the header and other one from the My
account page of the ITSO store.
Replace frames with JSP includes
Modify all the links in auction JSPs to create header and footer include files
instead of frame structure.
Provide the same look and feel for the ITSO store and the auction.

Chapter 16. Auctions
475
The sample auction provided with WebSphere Commerce Suite V5.1 does
not have the same look and feel as the In Fashion or Web Fashion sample
stores. For example, the auction store uses HTML frames across all its
display pages (JSPs); however, the ITSO store (which is based on Web
Fashion) uses JSP includes.
Figure 16-7 displays the My account page of the ITSO store (based on Web
Fashion) prior to modification.
Figure 16-7 My account page before modification

476
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
16.5.1 Provide links from the ITSO store and auction
Many e-commerce Web sites include auctions. In this section we will describe
how we provided links to and from the ITSO store and the auction. To accomplish
this task we modified the My account page (account.jsp), the header (header.jsp,
auc_common.jsp), and the properties file (infashiontext_en_US.properties).
Modify account.jsp
We chose the My account page (account.jsp) to link the auction pages to the
ITSO store pages, since bidders must register before submitting bids.
1.To add the auction link to the My account page, add the section of code
shown in Example 16-2 after the completion of the table row tag to
TrackOrderStatus in the file account.jsp.
Example 16-2 Sample account.jsp - add auction link
<% // 6180_Auction %>
<tr>
<td align="left" valign="top" width="280" bgcolor="#CC6600">
<font
class="subheader"><%=infashiontext.getString("AUCTION_HOME")%></font>
</td>
<td>&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top" width="280" class="topspace">
<font
class="text"><%=infashiontext.getString("AUCTION_HOME_MESSAGE")%></font><p>
<table cellpadding="0" cellspacing="0" border="0" align="left">
<tr>
<td align="left" valign="top">
<table cellpadding="4" cellspacing="0" border="0">
<tr>
<td align="left" valign="middle" bgcolor="#FFCC99">
<A
href="AuctionHomeView?storeId=<%=storeId%>&langId=<%=languageId%>&catalogId=<%=
catalogId%>"><font
class="strongtext"><%=infashiontext.getString("AUCTION_HOME2")%></font></a>
</td>
</tr>
</table>
</td>
</tr>
</table>
</td>
<td>&nbsp;</td>
</tr>
<tr>

Chapter 16. Auctions
477
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
<% // 6180_Auction end %>
2.The account.jsp main table has four table data columns. The first and third
columns are white space, which maintain the row span rather than every table
row being declared. For this reason, insert three new rows when adding the
auction link. You also need to increase the row span size in auction.jsp as
seen in Example 16-3.
Example 16-3 Sample account.jsp - increase row span
<!--MAIN CONTENT STARTS HERE-->
<table cellpadding="2" cellspacing="0" width="580" border="0">
<tr>
<td width="10" rowspan="13">&nbsp;</td>
<% // 6180_Auction increased rowspan from 10 to 13%>
<td align="left" valign="top" colspan="3" class="categoryspace">
<font class="category"><%=infashiontext.getString("MY_ACCOUNT3")%></font>
<hr width="580" color="#336666" noshade align="left">
</td>
</tr>
<tr>
<td align="left" valign="top" width="280" bgcolor="#CC6600">
<font
class="subheader"><%=infashiontext.getString("PERSONAL_INFO")%></font>
</td>
<td width="20" rowspan="12">&nbsp;&nbsp;</td>
<% // 6180_Auction increased rowspan from 5 to 12%>
<td align="left" valign="top" width="280" bgcolor="#CC6600">
<font class="subheader"><%=infashiontext.getString("ADDRESS_BOOK")%>
</td>
</tr>

478
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Modify auc_common.jsp
The auc_common.jsp should also be modified to ensure the auction pages can
access the store name and resource properties files used by the store. The
auc_common.jsp file is used as a JSP include file in all the auction JSPs. The
code changes shown in Example 16-4 are intended to provide the store name
and the infashiontext_en_US.properties file to all the auction-related JSPs.
Example 16-4 Sample auc_common.jsp
String storeName = null;
......
/* add the following section inside if (storeDir == null) loop before end of
the loop */
storeName =
sdb.getDescription(aCommandContext.getLanguageId()).getDisplayName();
request.setAttribute("storeName", storeName);
request.setAttribute("storeDir", storeDir);
.....
/* add the following section before %> tag
// 6180_Auction
ResourceBundle infashiontext = (ResourceBundle)
request.getAttribute("ResourceText");
if (infashiontext == null) {
infashiontext = ResourceBundle.getBundle(storeDir + "/infashiontext",
locale );
request.setAttribute("ResourceText", infashiontext);
}
// 6180_Auction end
Modify header.jsp
In addition to the link added to the My account page, we added a link in
header.jsp to the auction. This provides the access to browse the auction without
being logged in as a registered user.
Note: The modified account.jsp can be found in the the additional material, in
the <unzip_path>\sg246180\auctions\web directory. This file can be copied to
the <wcs_install_path>\stores\web\<store> directory. We recommend that you
back up the original account.jsp.
Note: The ITSO modified auc_common.jsp can be found in the additional
materials in the <unzip_path>\sg246180\auctions\web\Auction folder.

Chapter 16. Auctions
479
Add the code shown in Example 16-5 before MY ACCOUNT in header.jsp. When the
user clicks on Auction, and they are already logged on, they will be redirected to
the auction Welcome page. Otherwise they will be directed to the auction logon
page.
Example 16-5 Sample header.jsp - link to auction
<% String userType = userRegistrationDataBean.getRegisterType().trim();
%>
<% /* 6180-Auction */ %>
<td align="middle" valign="middle">
<%
/*
* Check if the customer is registered or not.
* If registered, clicking on Auction will take
* the user straight to the auction home page.
* Otherwise, user will be asked to login.
*/
if (userType.equalsIgnoreCase("G"))
{
%>
<font class="buttonson"><a
href="AuctionSample?langId=<%=languageId%>&storeId=<%=storeId%>&catalogId=<%=ca
talogId%>" style="color:
#CCCC99"><%=infashiontext.getString("AUCTION_HOME")%></a></font></td>
<%
}
else
{
%>
<font class="buttonson"><a
href="AuctionHomeView?langId=<%=languageId%>&storeId=<%=storeId%>&catalogId=<%=
catalogId%>" style="color:
#CCCC99"><%=infashiontext.getString("AUCTION_HOME")%></a></font></td>
<%
}
/* 6180-Auction End */
%>

480
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Modify infashiontext_en_US.properties
The changes made to the My account page (account.jsp) refer to the
infashiontext_en_US.properties file for the auction text to displayed. Having the
textual content in a properties file is good coding practice, because it makes it
easy to enable the store for multicultural use. In our example auction, we created
a new folder called auction. In order for JSPs to process the properties file, we
need to specify the auction directory.
Add the lines in Example 16-6, with references to the auction and to the
properties file to the infashiontext_en_US.properties file.
Example 16-6 Sample
infashiontext_en_US.properties
# added for Auction
AUCTION_HOME = AUCTION HOME
AUCTION_HOME_MESSAGE = You can view current and future auctions as well as your
bids.
AUCTION_HOME2 = AUCTION HOME
AUCTION_SIDEBAR = /Auction
# End of addition for Auction
After modifying the account.jsp, header.jsp, auc_common.jsp and
infashiontext_en_US.properties files, the My account page should look like
Figure 16-8.
Note: The modified header.jsp can be found in the additional materials, in the
<unzip_path>\sg246180\auctions\properties directory.

Chapter 16. Auctions
481
Figure 16-8 My account page after modification

482
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
16.5.2 Replace frames with JSP includes
By clicking the Auction Home link provided on the My account page, as seen in
Figure 16-9, the user will be redirected to the Auction home page. Figure 16-9
displays the auction sample home page before modification, which includes
frames.
Figure 16-9 Auction home page - before modification (frames)
Create auc_sidebar.jsp
To replace the functionality provided by the navigation frames, we created a JSP
called auc_sidebar.jsp for navigation. In addition to removing frames with JSP
includes, the auction will have the same look and feel of the ITSO store (Web
Fashion).

Chapter 16. Auctions
483
Figure 16-10 displays the auction home page for the ITSO store (Web Fashion).
The same header and footer files being used in the ITSO store have been added
to the auction pages.
Figure 16-10 Auction home page - after modification (no frames)
Note: The ITSO-created auc_sidebar.jsp can be found in the additional
material in the <unzip_path>\sg246180\auctions\web\Auctions directory.

484
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
16.5.3 Create same look and feel for auction and ITSO store
In order for the auction store to look similar to the ITSO store (Web Fashion), the
frames have been replaced with JSP includes. The auction sample store view
commands did not require the store ID, catalog ID and language ID to be passed
as name value pairs in the URL. But in order to include the header and footer and
all the hyper link in the JSPs, the above-mentioned parameters are required in
the URL. The links in the navigation bar (auc_sidebar.jsp) have also been
modified to include these parameters.
The view commands and corresponding JSPs that were modified are listed in
Table 16-2 on page 459.
Task for modifying each JSP
To update each auction JSP to use the auc_sidebar.jsp, the following
modifications will need to be made:
1.Import the essential Java packages:
<%@ page language="java" %>
<% // All JSPs requires the first 4 packages for auc_common.jsp which is
used for multi language support %>
<%@ page import="java.io.*" %>
<%@ page import="java.util.*" %>
<%@ page import="com.ibm.commerce.server.*" %>
<%@ page import="com.ibm.commerce.command.*" %>
2.Add the following lines before the HTML header:
//Parameters may be encrypted. Use JSPHelper to get
//URL parameter instead of request.getParameter().
JSPHelper jhelper = new JSPHelper(request);
String catId = jhelper.getParameter("catalogId");
3.Add a link for fashionfair.css stylesheet just after <TITLE>xxx</TITLE> tag
and before </HEAD>:
<link rel=stylesheet href="<%=storeDir%>/fashionfair.css" type="text/css">
4.Include header.jsp and auc_sidebar.jap just after the <BODY> tag:
String incfile;
incfile = "/" + storeDir + "/header.jsp";
String sidebar = "/" + storeDir +
infashiontext.getString("AUCTION_SIDEBAR") + "/auc_sidebar.jsp";
%>
<jsp:include page="<%=incfile%>"/>
<jsp:include page="<%=sidebar%>"/>

Chapter 16. Auctions
485
5.Add closing table tags and footer.jsp just above the </BODY> tags:
</td>
</tr>
</table>
</td>
</tr>
</table>
<%
incfile = "/" + storeDir + "/footer.jsp";
%>
<jsp:include page="<%=incfile%>"/>
6.The previous steps are compulsory. Some of the auction JSPs contain tables
to display lists (for example, auc_all_auction_list.jsp). For this kind of table
you need to do the following:
a.Make table border 1, cellspacing 0 and cellpadding 0:
<TABLE border="1" width="600" cellpadding="0" cellspacing="0">
b.Remove bgcolor from the table header row (for example, <TR> after
removing the bgcolor).
c.Add strongtext font class for all table header columns:
<font class="strongtext">table header</font>
d.If the table displays a form, then the table header row bgcolor will be
#cc6600 and the text font style will be subheader. For a data row there is
no bgcolor and the left column font style is strongtext:
<TR bgcolor="#cc6600">
<TD width=200 align="left"><font class="subheader">xxx</font></TD>
</TR>
e.For the page title use font style category or product and then a horizontal
rule:.
<BR>
<FONT class="product">Current Auction</FONT>
<hr width="580" noshade align="left">
<BR>
f.If any JSP contains the frameset definition, such as auc_bid_create.jsp or
auc_main_home.jsp, then all the frame JSPs can merge together and
make it one file. Alternatively, you could create a JSP include file for each
frame JSP and include these in your main JSP.

486
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Copy the ITSO-modified auction JSPs
The above sections have described how to install and modify the sample auction
that comes with WebSphere Commerce Suite V5.1. In this section we describe
how to deploy the auction files that we developed while writing this redbook.
Copy the ITSO-modified auction files to your store auction directory as follows:
1.Copy the JSPs:
copy c:\temp\sg246180\auctions\web\Auction\*.*
c:\ibm\wcs\stores\web\itso\Auction
Where itso is the store directory name.
2.Copy the non-locale-specific images:
copy c:\temp\sg246180\auctions\web\images\*.*
c:\ibm\wcs\stores\web\itso\images
3.Copy the locale-specific images:
xcopy c:\temp\sg246180\auctions\web\en_US\*.*
c:\ibm\wcs\stores\web\itso\en_US\images\*.* /e/s
4.Copy the properties files:
copy c:\temp\sg246180\auctions\properties\*.*
c:\ibm\wcs\stores\properties\itso
5.Copy the ITSO-modified ITSO store files (Web Fashion):
a.Back up the original account.jsp and header.jsp.
b.Copy the ITSO modified files account.jsp, header.jsp, if you have not
already modified these files:
copy c:\temp\sg246180\auctions\web\account.jsp
c:\ibm\wcs\stores\web\itso
copy c:\temp\sg246180\auctions\web\header.jsp c:\ibm\wcs\stores\web\itso
6.Alternatively to copying the ITSO-modified header.jsp, edit your existing
header.jsp found in the
<wcs_install_path>\stores\web\<store_name>\header.jsp directory.
Add the link as commented in the ITSO modified header.jsp to your
header.jsp:
/* 6180-Auction start */
<code_unpacked_path>\auctions\web\header.jsp. Paste above MYACCOUNT table
column. You also need to move the following lines above the newly copied
auction section from MYACCOUNT section.
String userType = userRegistrationDataBean.getRegisterType().trim();
/* 6180-Auction End */

Chapter 16. Auctions
487
7.Alternatively to copying the ITSO-modified account.jsp, edit your existing
account.jsp found in the <wcs_install_path>\stores\web\<store_name>
directory and add the link from the ITSO-modified file
<unzip_path>\sg246180\auctions\web\account.jsp.
a.Copy the section between:
/* 6180-Auction start */
/* 6180-Auction End */
b.Paste it as the last row of the table.
c.You also need to modify the existing section row spans. Look through
<unzip_path\sg246180\auctions\web\account.jsp. You will see the tag
start with the following:
// 6180_Auction and have information what to do
8.Update the VIEWREG table as described in 16.4.3, “Update the VIEWREG
table for auctions” on page 459.
9.Create an auction as described in 16.4.4, “Create an auction from Commerce
Suite Accelerator” on page 461.
10.Stop and start the WebSphere Commerce Suite instance via the WebSphere
Application Server Administrator’s Console.
The auction and ITSO store have now been integrated and are ready for testing.
16.5.4 Verify the auction and ITSO store integration
In order to verify the functionality of integrating the auction and the ITSO store,
an auction must first be created. Refer to 16.4.4, “Create an auction from
Commerce Suite Accelerator” on page 461 for details.
Now you can go to the store Web site and click the My account link, which will
take you to the auction page where you can see current auctions, future auctions
and bids. If you are not logged on yet then it will take you to the Auction logon
page. You also can access an auction via the My account page. Create some
bids for a specific auction for testing purposes.
Note: We found that sometimes we had to restart the IBM WS AdminServer
Windows service.

488
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
489
Chapter 17.
Managing a store
WebSphere Commerce Suite V5.1 defines I/T specialist roles and business roles
for the people who administer and maintain Web-based e-commerce solutions.
Depending on the size and capacity of the organization, these roles and tasks
may be performed by one or several people, or one person may be designated to
perform more than one role.
This chapter discusses the I/T specialist and business user roles and tasks for
managing an e-commerce Web site. In addition, we discuss how business
reports can be generated using WebSphere Commerce Analyzer.
This chapter is organized into the following sections:
I/T specialist roles and tasks
Business user roles and tasks
Reporting
17

490
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
17.1 I/T specialist roles and tasks
WebSphere Commerce Suite defines the following I/T specialist roles:
Network administrator
System administrator
Site administrator
Store administratorr
Database administrator
17.1.1 Network administrator
The network administrator is responsible for the installation and configuration of
networks and such hardware and software combinations as firewalls, routers,
and network hubs. Also, this administrator controls and limits access to the Web
site, conducts security awareness campaigns, establishes and maintains
network security systems, and protects all sensitive business data by setting the
access rights for physical files where the actual data is stored.
17.1.2 System administrator
The system administrator is the person whose primary responsibilities include
the installation, configuration, and operations for the following:
HTTP Server
WebSphere Application Server
WebSphere Commerce Suite server
WebSphere Commerce Analyzer server
IBM DB2 server
Payment Manager server
MQSeries Server
Secureway Directory Server
Blaze Advisor Rules Server
On the WebSphere Commerce Analyzer server, the system administrator also
performs the following tasks:
Administers the DB2 Warehouse Center
Schedules the generation of business reports

Chapter 17. Managing a store
491
Performs maintenance activities, such as backups, on the WebSphere
Commerce Analyzer server
Diagnoses and resolves problems that might occur.
17.1.3 Site administrator
The site administrator is responsible for configuring, administering and
maintaining WebSphere Commerce Suite. The site administrator should have
hardware and operating system skills.
The site administrator also defines and manages users and groups, controls
access, manages payments, configures the messaging system, and specifies
command security and performance monitoring. The site administrator uses the
Commerce Suite Administration Console to perform these tasks.
User and group access management
The site administrator creates roles and then assigns roles and access groups to
the users based on their role and position in the organization.
Access control
The site administrator defines new roles and gives users authority to use specific
commands and access the database with respect to specific stores. Commerce
Suite provides the following standard access control groups:
Customer
Access control for the customer group is used to specify commands that can
be used by all site users including guests, registered customers, and
administrators.
Merchant
The merchant has access to all menus in the Commerce Suite Accelerator,
for the purpose of supervising the overall store objectives, including
managing and tracking the store sales.
Marketing manager
The marketing manager monitors and analyzes customer behavior. In
WebSphere Commerce Suite V5.1, Pro Edition, the marketing manager can
create and modify customer profiles for targeted selling and create and
manage campaigns.

492
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Merchandising manager
The merchandising manager determines the best way to display, price, and
sell products for the online store. The merchandising manager traces
customer purchases and suggests discounts. In WebSphere Commerce
Suite V5.1, Pro Edition, the merchandising manager determines suggestive
selling techniques, and creates and manages auctions and bid controls.
Order clerk
An order clerk is a defined role in WebSphere Commerce Suite that manages
order processing, ensuring that orders are properly fulfilled, payment is
received, and orders are shipped. The order clerk can search for customer
orders, view details, and manage order information.
Customer service representative
The customer service representative manages customer inquiries, customer
registration, and order information. In WebSphere Commerce Suite V5.1, Pro
Edition, the customer service representative also works with auctions, such
as withdrawing bids and managing discussion forums.
Store developer
The store developer creates the initial store, member groups, product display
and other store pages, shopping metaphors, and order and payment systems
including taxing and shipping. The store developer is also responsible for the
look and feel of the store and any required code customization.
Site administrator
The site administrator installs, configures, and maintains Commerce Suite
and the associated software and hardware. The site administrator responds
to system warnings, alerts, and errors, and diagnoses and resolves system
problems. This role typically controls access and authorization, manages the
Web site, monitors performance, and manages load-balancing tasks.
The site administrator tasks of managing users, groups, and access control can
be performed using the Commerce Suite Administration Console.
For example, to create an access group, complete the following steps:
1.Start the Commerce Suite Administration Console by entering the following
URL in a Web browser, and then log on as a site administrator:
http://<hostname>/adminconsole
2.Select Site, then click OK.
3.From the Access Management menu, select Access Groups.
4.Click New.

Chapter 17. Managing a store
493
5.In the Detailed Information window, specify the following and then click Next:
– Name: <access_group_name>
– Description: <access_group_description>
6.In the Command Access for Access Group window, select the commands for
the access group by selecting the command, and then click Add. When done,
click Finish (see Figure 17-1).
Figure 17-1 Command access for access group selection
For more detailed information on access groups, refer to the Site Administrator,
IBM WebSphere Commerce Suite V5.1 product guide, or the IBM WebSphere
Commerce Suite V5.1 online documentation.
Command security
The site administrator can assign controller and view commands to access
groups for access control. Commands are assigned to different access groups
based upon the information in the ACCCMDGRP table. The site administrator
can define who can execute commands and exclude certain users from the
command access.

494
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
To assign access levels for commands, use the WebSphere Commerce Suite
Administration Console.
For example, to restrict customer commands for a store, complete the following
steps:
If you have not already created a store owner, complete the following steps:
1.Create an organization in the ORGENTITY table using the following SQL
script as your guide:
insert into member (member_id, type) values (1000, 'O');
insert into orgentity (orgentity_id, orgentityname, orgentitytype) values
(1000, 'YourOrganization', 'O');
where member_id and orgentity_id equal 1000 and O is organization.
2.Start the Commerce Suite Administration Console by entering the following
URL in a Web browser, and then log on as a site administrator:
http://<hostname>/adminconsole
3.Select Site, then click OK.
4.From the Access Management menu, select Customer Command
Restriction.
5.From the drop-down list, select a store owner.
6.Select a command, then click Add or Remove. When all the necessary
commands have been excluded, click OK.
When a customer command is excluded from the customer commands list for
an owner, this command should be defined as an administration command.
For more detailed information on command security, refer to the Site
Administrator, IBM WebSphere Commerce Suite V5.1 product guide and the IBM
WebSphere Commerce Suite V5.1 online documentation.
Outbound messaging system
The WebSphere Commerce Suite messaging system allows the site
administrator to manage all aspects of defining and sending messages
generated within Commerce Suite. The site administrator can control the manner
in which administrators, customers, and back-end systems are notified of various
events, such as customer orders or system errors.
Note: Before running the script, check the MEMBER table for the next
available member ID.

Chapter 17. Managing a store
495
The messaging system can send messages using transports such as MQSeries,
e-mail using SMTP, and file transfer using UTF-8 encoding. The supported
outbound protocol for e-mail is SMTP, and the message encoding depends on
the specified language.
The site administrator determines which transports are to be supported by the
site, and configures them on a site-wide basis. The site administrator activates
and configures transports and message types for the site, or allow store
administrators to specify their own settings for the following:
Add transports.
Activate or deactivate transports.
Configure transports. This supplies default configurations that a store
administrator can override.
Assign transports to message types. These assignments can be overridden
by store administrators.
Only the site administrator can perform the following tasks:
Enable error notification to send e-mail messages to administrators.
Enable the MQSeries JMS transport to send messages to the back-end
system.
Enable order status notification to update customers or administrators on the
status of existing orders.
The configuration of the outbound messaging system for WebSphere Commerce
Suite V5.1 is performed using the Commerce Suite Administration Console.
For example, to add a new transport to your site, do the following:
1.Start the Commerce Suite Administration Console by entering the following
URL in a Web browser, and then log on as a site administrator:
http://<hostname>/adminconsole
2.Select Site, then click OK.
3.From the Messaging menu, select Transports.
4.Click Add.
5.Check the transport you wish to add to the site. You can select all transports
by selecting the top check box.
6.Click Add to accept the changes, or click Cancel to return to the Transport
Configuration page.
For more detailed information on the Commerce Suite messaging system, refer
to the following:

496
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Chapter 14, “Messaging integration” on page 361 of this redbook for
examples.
WebSphere Commerce Suite V5.1 Handbook, SG24-6167, Commerce Suite
messaging using MQSeries and e-mail chapter.
Site Administrator, IBM WebSphere Commerce Suite V5.1, messaging
integration chapter.
IBM WebSphere Commerce Suite V5.1 online documentation.
Payment Manager administration
The site administrator can access payment processing and administration
functions. From the Payment Manager, the site administrator can perform the
following tasks:
View existing users or configure new and existing users
View existing merchant settings or configure new and existing merchant
settings
View existing Payment Manager settings or configure new and existing
Payment Manager settings
View existing cassette settings or configure new and existing casette settings
Configure trace enablement
Payment processing and administration are provided via the Commerce Suite
Accelerator, the Administration Console, and the Payment Manager user
interface.
The Commerce Suite Accelerator provides a button that launches the Payment
Manager user interface. The Administration Console also includes links to all
Payment Manager administration functions from the Payment Manager menu.
This is useful when you are setting up your store and want to configure the
Payment Manager cassette for the store or assign the Payment Manager
administrator role to the WebSphere Commerce Suite administrator.
For example, to complete the setup of Payment Manager for your store, do the
following:
1.Start the WebSphere Commerce Suite Administration Console or WebSphere
Payment Manager user interface.
2.Assign Payment Manager user roles to Commerce Suite users as required.
To assign Payment Manager user roles, select Users. The default Commerce
Suite site administrator, wcsadmin, is assigned the Payment Manager
administrator role by default. You may wish to assign other Commerce Suite
users various Payment Manager roles.

Chapter 17. Managing a store
497
3.Authorize cassettes for your store by doing the following:
a.Select Merchant Settings.
b.Click your store name in the Merchant name column.
c.Select the cassettes you wish to authorize for your store.
d.Click Update.
4.Configure cassettes for your store by doing the following:
a.Select Merchant Settings.
b.Select a cassette to configure by clicking the icon appearing in the row for
your store and the column for the cassette you want to configure.
c.Click Accounts on the cassette’s page for your store and do one of the
following:
• To change existing accounts, click the account name.
• To create a new account, click Add an Account.
For more detailed information on Payment Manager, refer to the following:
WebSphere Commerce Suite V5.1 Handbook, SG24-6167, Payment
Manager chapter.
e-commerce Payment Solutions Implementation and Integration using
WebSphere Payment Manager, SG24-6177
Site Administrator, IBM WebSphere Commerce Suite V5.1 product guide
IBM WebSphere Commerce Suite V5.1 online documentation
WebSphere Payment Manager product guides
Performance monitoring
The performance monitor is a tool used by the site administrator for measuring
the performance of a Commerce Suite server from a local or remote machine to
detect performance problems.
The WebSphere Commerce Suite application server gathers statistics for URLs,
tasks, and JSPs accessed. For each data key, an associated set of counters is
provided with the following information:
Important: If you created your store manually, you must add a new merchant
(your store) in order to authorize cassettes for your store. When creating a
new merchant, the merchant number specified must match the Commerce
Suite store ID. You can create a new merchant by selecting Merchant
Settings then clicking Add a Merchant.

498
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Number of occurrences (count)
Total time spent in the task
Maximum time
Minimum time
Sum of squares of the values
Standard deviation
Store number (SID)
Last response time
Last access time
Collectively this data is referred to as performance data and collected on a
per-machine basis. Each instance running on a WebSphere Commerce Server
collects and stores data. The data is displayed sorted by a variety of selectors,
such as standard deviation or total time.
To enable performance monitoring, use the Commerce Suite Configuration
Manager. The Commerce Suite Administration Console is used to access the
performance monitor once enabled.
For example, to use the performance monitor, do the following:
1.Ensure that the performance monitor is enabled.
a.Launch the Configuration Manager.
b.Select the Instance, then open the Components folder.
c.Select PerfMonitor, then click Enable Component.
d.Click Apply.
e.From the WebSphere Application Server Administration Console, stop
then re-start the instance.
2.Open the Commerce Suite Administration Console.
3.From the Performance menu, click Statistics.
4.Click Start monitor. The performance values will be collected.
For more detailed information on the Commerce Suite performance monitoring
tools, refer to the following:
Site Administrator, IBM WebSphere Commerce Suite V5.1 product guide
IBM WebSphere Commerce Suite V5.1 online documentation
Fundamentals, IBM WebSphere Commerce Suite V5.1 product guide

Chapter 17. Managing a store
499
17.1.4 Store administrator
In WebSphere Commerce Suite the store administrator is responsible for
configuring messages, administering Blaze rule services, and managing
payments.
Outbound messaging system store administration
The store administrator is responsible for enabling the transport methods that are
used by the store. The store administrator can add, activate, deactivate, and
configure transport methods for the store, and assign transport methods to
message types. The store administrator has the option to either accept the
settings created by the site administrator or override them. The following is a list
of the tasks involved in store administration:
Add transports
Activate or deactivate transports
Configure transports
Assign transports to message types
To configure the outbound messaging system, use the WebSphere Commerce
Suite Administration Console.
For example, to add a new transport to your store, do the following:
1.Open the Administration Console and log on as a store administrator.
2.From the Messaging menu, select Transports.
3.Click Add.
4.Check the transport you want to add to the store. You can select all transports
by selecting the check box at the top-left. If there are no transports available,
then you have already added all of the transports made available by the Site
Administrator.
5.Click Add to add the transport, or click Cancel to return to the Transport
Configuration page.
Important: Once a store administrator has overridden a site-level setting, any
future changes made by the site administrator to that particular setting will not
affect that store. Changes made to other settings at the site level that have not
been modified by the store administrator will still apply.
For example, if e-mail is configured for the site with the SMTP host of
smtp.host1.com, but Store A has specified smtp.host2.com, any future
changes at the site-level to e-mail will not affect the settings for e-mail Store A.

500
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Blaze Advisor Rule Server administration
In WebSphere Commerce Suite, a store administrator processes rules and
provides personalized marketing content consisting of advertisements and
suggestive selling techniques, which can be summarized into two main tasks:
Enabling WebSphere Commerce Suite personalized marketing content
Deploying marketing campaigns to a production machine
The Commerce Suite Configuration Manager and Commerce Suite Accelerator
are used to perform these tasks.
For example, to enable your site to generate personalized marketing content, the
following steps must be performed:
1.Enable the Rule Server using the RuleServices node under Instances in
the Configuration Manager.
2.Ensure that the MarketingCenterInfrastructure and the RulesSystem
components are enabled in the Configuration Manager.
3.Register your campaign assets (e-marketing spots and ad copy) in the
database.
4.Create e-marketing spots on the JavaServer Pages files for your store.
5.Create customer profiles and campaigns.
6.Publish the campaigns, and deploy them to the production server.
7.Add rule services, or refresh existing rule services for the new content.
For example, to deploy marketing campaigns to the production server, do the
following:
1.Configure the following directory as a shared directory:
RepositoryRoot /UserTemplate/Store sid /Campaign
where RepositoryRoot is the path where the Blaze Innovator repository is
installed, and sid is the store ID reference number.
2.From the production server, map to the shared directory.
3.Find the files generated on the development machine by the Commerce Suite
Accelerator. These files contain the information required by the rule server to
implement the campaigns. These files will be located in the following
directory:
Important: The rule server is governed by certain limitations, contained in the
License Information booklet. You need a separate license from Blaze Software
to exceed these limitations.

Chapter 17. Managing a store
501
RepositoryRoot /UserTemplate/Store sid /Campaign/Campaign cid /Deployment/
where RepositoryRoot is the path where the Blaze Innovator repository is
installed, sid is the store ID reference number, and cid is the campaign
reference number.
The following files are created for each campaign:
– CampaignName.adv
– CampaignName.rb
– CampaignName.dbcp
– CampaignName.jcp
– CampaignName.cdd
– CampaignName.flown
where CampaignName is the name of the campaign, and n is a number. There
may be more than one file with the .flown extension.
4.Move all of these files to the production server. These should be placed in the
following directory:
Commerce_Suite_install_path /instances/instance_name /rules/projects
Make this directory a shared directory as well. If you are running multiple
production servers, you can reference this directory as the rule project
source, eliminating the need to replicate these files in a similar path on every
production server.
5.Add a rule service for the campaign.
Rule services
The WebSphere Commerce Suite uses rule services to interact with the Blaze
Advisor Rule Server. A rule service acts as an interface to facilitate
communication between the two applications. The rule service also provides a
convenient way to update the rule-based portion of your site without having to
stop the entire WebSphere Commerce Suite.
A rule service exists in a one-to-one relationship with a campaign. Each
campaign published using the Commerce Suite Accelerator must have a
corresponding rule service. This design provides flexibility, since each marketing
service, and therefore campaign, can be started, stopped, and refreshed
independently of every other service.
Whenever a customer profile, campaign, or rule service is updated using the
Commerce Suite Accelerator, it is necessary to transfer the files to the
appropriate location on the production server and refresh the rule service.

502
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
The rule services can be distributed among any number of Java Virtual Machines
(JVMs). Therefore the actions performed on rule services are delivered through
the job scheduler. The actions are not performed immediately, but rather added
to the job queue. It may be necessary to use the View Last Request action in the
Rule Service list to get status updates on the various rule services.
To maintain rules, use the WebSphere Commerce Suite Administration Console.
For example, to add a rule service, do the following:
1.Start the Administration Console and log on as a store administrator.
2.From the Rule Services menu, select Administration.
3.Click Add Service.
4.Specify the entries for the Add Rule Service window as required. Help is
available for each page if you require help using the fields.
5.Click OK to add and start the new rule service. The rule service displays in
the Rule Service list.
6.Check the status of the service to verify that the request was successful.
Refer to the “Check the status of a rule service” topic in the online help.
For more detailed information on rule services, refer to the Site Administrator,
IBM WebSphere Commerce Suite V5.1 product guide, or the online
documentation for WebSphereCommerce Suite V5.1.
Database cleanup
Maintaining store data is one of the primary tasks of the store administrator.
WebSphere Commerce Suite provides a database cleanup utility to assist the
store administrator to maintain database contents.
When the utility deletes a record in a table, it also deletes the corresponding
records in other tables that are linked to that table, to preserve the referential
integrity of the database. The database cleanup utility is configurable, extensible,
and adaptable.
The store administrator can delete the following record types using the database
cleanup utility:
Members
Guest customers
Temporary customer addresses
Old orders
Messages

Chapter 17. Managing a store
503
User traffic log records
Records in the staging log table that have been propagated to the production
database
Records in the cache log table that identify invalid or purged cache pages
Records in the catalog entry, campaign log, sales assistant statistics, and
customer profile tables, and in WebSphere Commerce Suite Professional
Edition, Product Advisor statistics, product comparison statistics, and product
explorer statistics
Closed or retracted auctions.
After using the database cleanup utility on DB2 databases, you should run the
REORG utility to reclaim table space after cleaning up the database. You should
also run the RUNSTATS utility to update the database access plan.
For example, to add a new configuration setting for the database cleanup utility,
do the following:
1.Open a DB2 command prompt.
2.Enter the following:
db2 insert into cleanconf (tabname, type, condition, namearg, daysarg)
values ('R1','obsolete','where col1>10 and (days (CURRENT TIMESTAMP) -
days(lastupdate))>?','no','yes')
where ? is replaced by the -days parameter from the command line below.
The 'no' indicates that the name parameter is not used in the condition. The
'yes' indicates that the days parameter is used in the condition. 'obsolete'
describes the cleanup type for table R1.
3.To invoke the database cleanup utility command on a DB2 database to clean
the records that are two days old from the new table, enter the following:
dbclean -table R1 -db <dbname> -type obsolete -days 2 -loglevel 1
For more detailed information on the database cleanup utilities, refer to the online
documentation for WebSphereCommerce Suite V5.1 and Fundamentals, IBM
WebSphere Commerce Suite V5.1 product guide.
17.1.5 Database administrator
The database administrator develops regular and periodic maintenance
strategies for WebSphere Commerce Suite database server to prevent problems
with the online store or mall.
The database administrator does the following tasks on a regular basis:
Schedule database maintenance

504
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Diagnostics information logging
Maintain database logs
Table space management
Access plan generation
Table reorganizations
Database uses monitoring
Database cleanup utility
Periodic database maintenance tasks include the following:
Database tuning
Disaster recovery strategy
Maintaining correct code level
For more detailed information on database administration, refer to the online
documentation for WebSphereCommerce Suite V5.1, or the Fundamentals, IBM
WebSphere Commerce Suite V5.1 product guide.
17.2 Business user roles and tasks
The WebSphere Commerce Suite Accelerator is used by the business users to
perform tasks on the online store for the following roles:
Order clerk
Customer service representative
Marketing manager
Merchandising manager
Merchant
How to use Commerce Suite Accelerator
When the user logs on to the Commerce Suite Accelerator, the Accelerator home
page menu shows only those tasks the logged-in user is authorized to perform.
These tasks are based on access groups and authority levels, which are defined
by the site administrator by using the WebSphere Commerce Suite
Administration Console.
The Commerce Suite Accelerator interface consists of several notebooks,
wizards, windows, and lists to help you complete your tasks. A help link is
included in the upper right corner to launch help for each page. Notebooks and
wizards consist of a series of windows.

Chapter 17. Managing a store
505
A notebook opens when you change existing information in the Commerce Suite
system, such as a customer profile, or a product price. To navigate a notebook,
use the links on the left side. Click OK to close the notebook. You can use one or
more pages in a notebook, and you do not have to progress sequentially. As you
progress through a wizard, the left side dynamically refreshes to indicate where
you are in the creation process.
A wizard launches when you create new information, such as a new customer
order or a new product campaign. To navigate a wizard, use the Next and
Previous buttons, and click Finish when you have completed the pages. Unlike
a notebook, you must progress through a wizard sequentially.
Dialogs are single pages that allow you to input information to complete a task.
For example, a search dialog contains search criteria fields. Provide the
appropriate information and click Find to display the results.
You can perform the following tasks with a list:
To work with a particular list item, do one of the following:
– Select the check box to the left of the item and click one of the buttons on
the page.
– Select the item from the first column in the list to change information (such
as the details of an existing discount) or view a summary (such as the
details of a customer order).
To select all the items in the search results list, select the check box icon at
the top left of the list.
To sort the list by column, click the icon beside the appropriate column
heading. The list sorts by this column in ascending order.
To navigate through a long list, click Top, Bottom, Next, or Previous.
The following sections will explain the responsibilities of the above-mentioned
roles and give examples of how to perform their tasks by using WebSphere
Commerce Suite Accelerator.
17.2.1 Order clerk
The order clerk tracks and manages orders that have been placed by customers,
ensuring that orders are properly fulfilled, payment is received, and orders are
shipped.
The order clerk can search for customer orders, view details, manage order
information, and keep order information up to date. The customer service
representative can then use this information to address customer inquiries about
their orders and change necessary information for customers.

506
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Perform order clerk tasks using the Accelerator
When an order clerk logs on to the WebSphere Commerce Suite Accelerator, the
tasks that an order clerk is authorized to perform will be displayed.
The Customer Orders menu within the Commerce Suite Accelerator gives an
order clerk access to perform the following tasks:
Find and view a list of orders for each store
View details of orders through report summaries
Change order status
Cancel orders
Add comments to orders
Process customer orders that use Payment Manager to handle payments
Change the status of a customer order
To change the status of a specific customer order from new to shipped or
canceled, do the following:
1.Start the Commerce Suite Accelerator. If you are an order clerk or merchant
or site administrator you will see the Customer Order menu.
2.From the Customer Orders menu, select Orders.
3.Check the customer’s order check box, and click Change Status.
4.Under Change the status to the following, do one of the following:
– Select Canceled to change the status of the customer order from new to
canceled.
– Select Shipped to change the status of the customer order from new to
shipped.
– Select Submitted to change the status of the customer order from new to
submitted. For example, if an order was placed but is waiting for inventory
to be fulfilled, you may re-submit the original order once the inventory has
been replenished.
5.In the Comments scroll box, use the default text or type another reason for
the change in status (for example the product has been delivered to the
shipping address, or the customer has decided not to purchase the ordered
product). Customers will be e-mailed this comment. This scroll box accepts
up to 1024 single byte alphanumeric characters.
6.Click OK to change the status of the customer order and to send the
comment to the customer.

Chapter 17. Managing a store
507
17.2.2 Customer service representative
No matter how well your online store is designed to provide a customer with
self-service features, there will be occasions when a customer requires personal
contact. The customer service representative handles customer inquiries,
whether through e-mail, fax, or phone. The customer service representative
primarily deals with customer registration and orders, but also assists with the
management of customer problems. All customer registration data is kept in a
Commerce Suite user registry. The registration information includes information
such as name and primary address, password and challenge question and
answer, and demographic information.
Tasks performed using the Accelerator
When a customer service representative logs on to the WebSphere Commerce
Suite Accelerator, tasks that a customer service representative is authorized to
perform will be displayed.
The Customer Service menu within the Commerce Suite Accelerator gives a
customer service representative access to perform the following tasks:
View a list of customers
Find registered customers
Find existing orders
Place an order on behalf of a registered customer
Place an order on behalf of a non-registered customer
Change customer registration information and passwords
List and view auctions, withdraw auction bids on behalf of the customer, and
manage auction discussion forums (this task is available only in WebSphere
Commerce Suite V5.1, Pro Edition)
Create an order for a guest shopper
The site administrator, merchant and customer service representative have
access to create an order on behalf of registered and non-registered customers.
To create an order on behalf of a customer who has not registered with the store
and does not have a customer registration profile, do the following:
1.Open the Commerce Suite Accelerator. If you are a customer service
representative or merchant or site administrator, you will see the Customer
Service menu.
2.From the Customer Service menu, click Place Guest Order. The New
Customer Order wizard launches, showing the New Customer Order -
Products page first.
3.Click Add Products to search for products to add to the customer order. Here
you can insert product name or SKU, and then click Find.

508
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
4.The Add Product Search result will be displayed. To add a product from this
list to the customer order, select the check box to the left of the product, type
the quantity to order in the Quantity field, and click OK.
If you insert a product name and the selected product list is more than the
default number of items, then there will be top, bottom, previous and next link
at the top of the page. You can browse to find the specific item. You can move
a product into the order list by repeating steps 3 and 4. Click Next on the
Product page when you finish adding the product into the order list.
5.The Billing Address page will be displayed. Fill in the following mandatory
fields:
– Last name
– Street address
– City
– State/Province
– Country
– ZIP/Postal code
If you click Next without filling all mandatory fields, a JavaScript alert box will
ask you to complete the required field. Fill in all the fields and click Next.
6.The Shipping Address page will be displayed. If the shipping address is the
same as the billing address, then select Same as billing address and click
Next. Otherwise, complete all the fields and click Next.
7.The Shipping page will be displayed. Select one of the shipping methods from
the drop-down list and click Next.
8.The Payment page will display. Select one of the Payment method from the
drop-down list. Type all other necessary information for your selected
payment method and click Next.
9.The Comment page will be displayed. To include a comment with this
customer order, type it in the Comments scroll box, select Send these
comments to the customer if you want to e-mail the comment to the
customer, and click Next.
10.On the Order Confirmation and Adjustments page, enter the required fields
and click Recalculate. Click Back to return to the previous page, if
necessary. Help is available for each page.
11.When you have completed all pages, click Finish on the Confirmation and
Adjustments page to create the order. On successfully completing the order,
you will receive a JavaScript message box with the order number.
Note: The shipping address also has the same mandatory fields as the billing
address.

Chapter 17. Managing a store
509
Create an order for a registered customer
To create an order on behalf of a registered customer, do the following:
1.Open the Commerce Suite Accelerator. If you are a customer service
representative or merchant or site administrator you will see the Customer
Service menu.
2.From the Customer Service menu, select Customers. A list of customers for
the store displays.
3.Select the check box to the left of the customer that you want to work with,
and click Place Order to create a new customer order. The New Customer
Order wizard launches, displaying the New Customer Order - Products page
first.
4.To complete the order, follow steps 3 to 11 in “Create an order for a guest
shopper” on page 507.
Update customer information
To update a customer’s registration information, such as a customer’s profile,
address, contact information, or demographics, do the following:
1.Open the Commerce Suite Accelerator. If you are a customer service
representative or merchant or site administrator you will see the Customer
Service menu.
2.From the Customer Service menu, select Customers. A list of registered
customers for the store displays.
3.Open the Customer Information notebook to update customer information by
doing one of the following:
a.Select the check box to the left of the customer that you want to work with,
and click Change.
b.From the Customer login ID column, click the customer logon ID.
4.Update the fields as required and use the links on the left side to switch
between customer information pages. Help is available for each page.
5.Click OK to save the changes and close the notebook.
Change a customer’s registration profile
To change a customer’s registration profile, such as the logon password,
authentication information, store account status, title, name, preferred language
or currency, do the following:
Note: The registered customer billing address and shipping address will
display automatically if this information already exists in the store.

510
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
1.Follow steps 1-3 in “Update customer information” on page 509.
2.From the notebook (left-hand side) click General. The General window will be
displayed. You can update the following information:
– Password
– Password confirmation
– Certificate status (drop-down list)
– Account status (radio button with Enabled or Disabled options)
– Title (drop-down list)
– First name
– Middle name
– Last name
– Challenge question
– Answer to challenge question
– Preferred language (drop-down list)
– Preferred currency (drop-down list)
3.Click OK to save the changes and close the notebook.
Change a customer’s address
To change a customer’s contact address, which was provided during registration,
do the following:
1.Follow steps 1-3 in “Update customer information” on page 509.
2.From the notebook (left-hand side) click Address. Address window will
display. You can update the following information:
– Street address
– City
– State/Province
– Zip/Postal code
– Country
3.Click OK to save the changes and close the notebook.
Change a customer’s contact information
To change a customer’s contact information, which was provided during
registration, such as a phone number, fax number, or e-mail address, do the
following:
Note: If you change the password field, then you have to re-type the password
in the password confirmation field.
Note: All these fields are mandatory.

Chapter 17. Managing a store
511
1.Follow steps 1-3 in “Update customer information” on page 509. From the
notebook (left-hand side) click Contact. The Contact window will display. You
can update the following information:
– Preferred method of communication (drop-down list)
– E-mail address 1
– E-mail address 2
– Phone number 1, Type (drop-down list), and listed (check box)
– Phone number 2, Type (drop-down list), and listed (check box)
– Fax number 1
– Fax number 2
– Best time to call (drop-down list)
– Include promotional material with shipments (check box)
2.Click OK to save the changes and close the notebook.
Change a customer’s demographic information
To change a customer’s demographic information, which was provided during
registration, do the following:
1.Follow steps 1-3 in “Update customer information” on page 509.
2.From the notebook (left-hand side) click Demographics. The Demographics
window will display.You can update the following information:
– Age (drop-down list)
– Gender (drop-down list)
– Marital status (drop-down list)
– Annual income (drop-down list)
– Number of household members
– Number of children
– Return customer (drop-down list)
– Employer
– Interests/Hobbies
3.Click OK to save the changes and close the notebook.
17.2.3 Marketing manager
In WebSphere Commerce Suite, the marketing manager communicates the
market strategy and brand messages to the customers. The marketing manager
monitors, analyzes, and understands customer behavior. In addition, the
marketing manager creates or modifies customer profiles for targeted selling,
and creates and manages campaigns and promotions. Campaign event planning
can be handled by a team comprising the merchant, marketing manager, and
merchandising manager. Either the marketing manager or the merchandising
manager projects the sales for a promotional event and analyzes its
effectiveness.

512
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
The marketing manager is concerned with the operation of the store from a
business perspective. The marketing manager also develops the marketing
strategy and tracks the success of the store as a business.
Perform marketing manager tasks using the Accelerator
When a marketing manager logs on to the WebSphere Commerce Suite
Accelerator, the tasks that he or she is authorized to perform will be displayed.
The Marketing menu within the Commerce Suite Accelerator gives a marketing
manager access to perform the following tasks:
Create and maintain customer profiles
Create and maintain campaigns
Manage campaign initiatives
View business reports.
Create a new customer profile
Customer profiles define a group of customers that have a common set of
characteristics. These profile identify targets for campaigning, promotions and
suggestive selling.
A customer profile incorporates the following information:
General
Registration
– Registration status
– Registration date
– Last registration update
Demographics
– Gender
– Age
– Income
– Marital status
– Children
– Household
Address
– City
– State
– Country
– ZIP Code
– Phone number
– E-mail
Culture
– Currency
– Language

Chapter 17. Managing a store
513
Purchase history
– Amount spent
– Number of orders
– Last purchase
– Last visit date
Miscellaneous
– Company
– Interests
– Customer groups
– Preferred method of communication
Profiles are considered dynamic because customers belong to them based on
their personal data and purchase history, both of which may change.
Create a new customer profile
To create a new customer profile, complete the following steps:
1.Open the Commerce Suite Accelerator. If you are a marketing manager,
merchandising manager, merchant, or site administrator, you will see the
Marketing menu.
2.From the Marketing menu, select Customer Profiles. The Customer Profiles
page displays, containing the customer profiles currently defined for the
selected store.
3.Click New. The Customer Profiles notebook with the General window
displays.
4.Complete the fields for each page as required, and use the links on the left
side to switch between pages. Help is available for each page if you require
help using the fields.
5.Click OK to save the profile and close the notebook. The customer profile is
displayed in the Customer Profile page.
Create a new customer profile based on gender
To create a new customer profile based on gender, do the following:
1.Follow steps 1-3 in “Create a new customer profile” on page 512.
2.Type the name and description of the profile. From the left navigation bar,
select Demographics -> Gender
3.The Gender window displays. Define the customer gender criteria for this
customer profile. To do this, select Target the following genders, then select
Male or Female.

514
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Create a new customer profile based on age group
To create a new customer profile based on age group, do the following:
1.Follow steps 1-3 in “Create a new customer profile” on page 512.
2.From the left navigation bar, select Demographics -> Age.
3.The Age window displays. Define the customer age criteria for this customer
profile. To do this select Target the following age groups and select one or
more ages as required.
17.2.4 Merchandising manager
In WebSphere Commerce Suite, the manager communicates the market strategy
and brand messages to the customers. The marketing manager monitors,
analyzes, and understands customer behavior. In addition, the marketing
manager creates or modifies customer profiles for targeted selling, and creates
and manages campaigns and promotions. Campaign event planning can be
handled by a team comprising the merchant, marketing manager, and
merchandising manager. Either the marketing manager or the merchandising
manager projects the sales for a promotional event and analyzes its
effectiveness.
Perform merchandising manager tasks
When a merchandising manager logs on to the WebSphere Commerce Suite
Accelerator, the tasks that he or she is authorized to perform will be displayed. A
merchandising manager is authorized to perform all the tasks performed by the
marketing manager.
The Merchandise menu within the Commerce Suite Accelerator gives a
merchandise manager access to perform the following tasks:
Manage products, including updates to product information about name,
stock keeping unit (SKU), description, images, attributes, inventory, list prices,
vendor, discounts (which have to be created first via the Discount menu under
the Merchandise menu), sales tax, shipping tax, shipping charges and soft
product - download URL, description and availability.
Create auctions.
Manage auctions, including change exsting auction, manage bids, manage
discussions, retract auctions, close auctions, create and manage auction
styles, and create and manage bid control rules.
Create and manage discounts, including view discount summary, activate
discounts, deactivate discounts, and delete discounts.
Manage offers.

Chapter 17. Managing a store
515
View marketing event statistics, including Product Advisor statistics, product
explorer statistics, product comparison statistics and sales assistant statistics.
View WebSphere Commerce Analyzer generated advanced business reports.
Change offer
To change an offer for a product, such as the offer’s display priority, start and end
dates, rules, prices, or member groups, use the Offer notebook and complete the
following steps:
1.Open the Commerce Suite Accelerator. If you are a merchandising manager
or merchant or site administrator you will see the Merchandise menu.
2.From the Merchandise menu, click Products. A list of products for the store
displays.
3.Select the check box to the left of the product you want to work with and click
Offers. A list of offers for the product displays.
4.Open the Change Offer notebook by doing one of the following:
a.Select the check box to the left of the offer you want to work with and click
Change.
b.From the Offer column, click the ID for the offer.
5.Update the fields as required and use the links on the left side to switch
between each offer page. Help is available for each page.
6.Click OK to save the changes and close the notebook.
Change the display priority of an offer
To change the display priority of an offer, do the following:
1.Follow steps 1 to 4 in “Change offer” on page 515.
2.The Change Offer - General window displays. In the Precedence field, type a
value to indicate the priority for displaying the offer to customers. A product
can be associated with multiple offers. The higher the precedence value, the
higher its display priority.
For example, an offer with a precedence of 2 is displayed to the customer if
available. If that offer is not available, then an offer with a precedence of 1 is
displayed.
3.Click OK to save the changes and close the notebook.
Note: Since the merchandising manager has access to all of the marketing
manager tasks, the merchandising manager will have access to the Marketing
menu.

516
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Change the minimum quantity to order for an offer
To change the minimum quantity of the product that a customer must order
before he or she can use the offer, do the following:
1.Follow steps 1 to 4 in “Change offer” on page 515.
2.The Change Offer - General window displays. In the Minimum quantity field,
type the minimum quantity of the product that customers must order before
they can use the offer.
For example, for a special offer on children’s books, you can indicate that
customers must purchase at least three children’s books before they can take
advantage of the price discount offered.
3.From the Quantity unit drop-down list, select the unit of measure used to
determine the minimum quantity for ordering the product at the offer price. For
example, if you sell books online, you may base the minimum quantity on the
total weight of each order. If the minimum quantity for ordering the product for
this offer is not based on units, select Not applicable.
4.Click OK to save the changes and close the notebook.
Change the maximum quantity to order for an offer
To change the maximum quantity of the product that customers need to order
before they qualify for the offer, do the following:
1.Follow steps 1 to 4 in “Change offer” on page 515.
2.The Change Offer - General window displays. In the Maximum quantity field,
type the maximum quantity of the product that customers must order to
qualify for the offer.
For example, for a special offer on magazines, you can limit the number of
magazines that customers can purchase at the discounted price to five
magazines by typing 5 in this field.
3.From the Quantity unit drop-down list, select the unit of measure used to
determine the maximum quantity for ordering the product at the offer price.
For example, if you sell books online, you may base the minimum quantity on
the total weight of each order. If the maximum quantity for ordering the
product for this offer is not based on units, select Not applicable.
4.Click OK to save the changes and close the notebook.
Change the offer availability date and time
To change the offer availability date and time, do the following:
1.Follow steps 1 to 4 in “Change offer” on page 515.
2.The Change Offer - General window displays. Change when the offer is
available for customers to view and use, as follows:

Chapter 17. Managing a store
517
a.To specify the date that the offer is available, do one of the following:
i.Click the calendar icon beside the Start date fields to open a calendar
and select the date when the offer is available. Using the calendar
control ensures that the date is specified in the appropriate format.
ii.In the Year, Month, and Day fields, type the year (in the format YYYY),
month (MM), and day (DD) that the offer is available.
b.To specify the time that the offer is available, in the Time field, type the
time in the format HH:MM. Use the 24-hour clock format (for example,
type 16:30 to indicate 4:30 p.m.).
c.To specify the date that the offer is no longer available to customers, do
one of the following:
i.Click the calendar icon beside the End date fields to open a calendar
and select the date when the offer expires. Using the calendar control
ensures that the date is specified in the appropriate format.
ii.In the Year, Month, and Day fields, type the year (in the format YYYY),
month (MM), and day (DD) that the offer expires.
d.To specify the time that the offer is no longer available, in the Time field,
type the time in the format HH:MM. Use the 24-hour clock format (for
example, type 16:30 to indicate 4:30 p.m.).
3.Click OK to save the changes and close the notebook.
17.2.5 Merchant
In WebSphere Commerce Suite V5.1, a merchant is a super user who has
access to customer service, order clerk, marketing manager and merchandising
manager responsibilities. If you want to create a user who can perform all tasks
in the Commerce Suite Accelerator, the user must be a member of both the
merchant and customer service representative access groups for the store.
Note: If you specify a date, you must also specify a time. The following are
valid scenarios for offer start dates and times, and end dates and times:
If you provide both start and end dates and times, the offer is valid during
the specified range.
If you do not provide start and end dates and times, the offer never expires.
If you provide an end date and time, but not a start date and time, the offer
is valid from no particular date and time to the end date and time.
If you provide a start date and time, but not an end date and time, the offer is
valid from the start date and time and never expires.

518
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Accelerator features for a merchant
In WebSphere Commerce Suite Accelerator, the merchant and site administrator
are authorized to perform all the tasks of order clerk, customer service
representative, marketing manager and merchandising manager. Figure 17-2
shows the WebSphere Commerce Suite Accelerator home page menu for a
merchant or site administrator.
Figure 17-2 Accelerator home page menus for merchant or site administrator
17.3 Reporting
After you set up your store, you are likely to be interested in how successful the
store is. You might want to have access to specific information about the success
of different campaigns and initiatives. You might also want to know more about
the customers who are using the store and the responses to specific campaigns
and initiatives.

Chapter 17. Managing a store
519
WebSphere Commerce Analyzer is an optional application included with the
WebSphere Commerce Suite V5.1, Pro Edition. If installed, it provides a robust
business intelligence solution designed to analyze and report on the activities of
your customers. This information can help you adjust your marketing strategy to
better meet the needs of your customers.
17.3.1 What is IBM WebSphere Commerce Analyzer?
The IBM WebSphere Commerce Analyzer is a new, optionally installable feature
of IBM WebSphere Commerce Suite V5.1, Pro Edition. WebSphere Commerce
Analyzer provides predefined reports about the marketing and shopping
activities in the store. A marketing manager can use these reports to help
manage the success of the store.
WebSphere Commerce Analyzer creates and maintains a datamart containing
information that is needed to generate business reports about the store. The
datamart is an IBM DB2 relational database that is created on the WebSphere
Commerce Analyzer server. The datamart contains information that is obtained
from the WebSphere Commerce Suite database server. IBM DB2 provides the
tools you need for database administration. The installation program also installs
the Brio Broadcast Server (BCS) reporting tool, provided by Brio Technology as
part of Brio Enterprise Server 6.2. The Brio Broadcast Server reporting tool
generates the business reports.
The business reports provide information about the effectiveness of marketing
promotions as well as information about sales and the customers who use the
store. These reports can help the marketing manager to make decisions about
the marketing strategy and the products sold in the store.
The marketing manager can access the business reports from the
browser-based WebSphere Commerce Suite Accelerator, which is installed with
WebSphere Commerce Suite. For security purposes, the marketing manager
must provide a user ID and password to access the reports.
After installation, the report generation process can be scheduled to run on a
daily basis. For example, you can run the reports just after midnight or at some
other time when there is little activity for the store you are managing.
WebSphere Commerce Analyzer provides information about one store and
supports one language, one locale, and multiple currencies.
WebSphere Commerce Analyzer, DB2, and the Brio Broadcast Server reporting
tool are provided on separate CDs in the WebSphere Commerce Suite package.
Note: The reports cannot be customized.

520
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
17.3.2 High-evel implementation steps
It is recommended that you install the WebSphere Commerce Analyzer server on
a computer that is not used for other functions. This configuration provides better
performance than installing the WebSphere Commerce Analyzer server on one
of the WebSphere Commerce Suite servers.
The following checklist is for the installation, configuration, and reports
generation using WebSphere Commerce Analyzer:
1.Make sure WebSphere Commerce Analyzer server machine meets the
hardware requirements.
2.Install Microsoft Windows NT 4.0 with Service Pack 6a or Microsoft Windows
2000.
3.On the WebSphere Commerce Analyzer server, create a user ID with
administrator privileges.
4.On the WebSphere Commerce Suite server, make sure a user ID exists with
the same name, password, and privileges as WebSphere Commerce
Analyzer.
5.Configure WebSphere Commerce Suite database server to support remote
Open Database Connectivity (ODBC).
6.Enable the UserTrafficEventListener and CampaignRecommendationListener
components through the WebSphere Commerce Suite Configuration
Manager.
7.On the WebSphere Commerce Suite server, share the directory where
WebSphere Commerce Suite is installed, for example C:\ibm\wcs.
8.Give read access permission to the above-created user ID.
9.On the WebSphere Commerce Suite Web server, share the WebSphere
Commerce Suite HTML document root directory, for example
C:\ibm\http\htdocs.
10.Give read and change access permission to the above created user ID.
11.Create a WebSphere Commerce Suite relative report path, for example
C:\ibm\http\htdocs\wca\reports.
12.On the WebSphere Commerce Analyzer server, map the WebSphere
Commerce Suite product install directory.
Note: Detailed instructions for pre-installation, installation, configuration and
post-configuration can be found in Appendix C, “WebSphere Commerce
Analyzer” on page 555.

Chapter 17. Managing a store
521
13.On the WebSphere Commerce Analyzer server, map the WebSphere
Commerce Suite HTML Document Root.
14.Gather information required during installation and configuration.
15.Set access control to the business reports.
16.Remove the default printer if it is a network printer shared over NetBIOS.
17.Install WebSphere Commerce Analyzer:
– Install IBM DB2 Universal Database Enterprise Edition, Version 7.1.0.28
(fp2a) or later (can be installed before installing WebSphere Commerce
Analyzer).
– Install Brio Broadcast Server Version 6.2.
– Install WebSphere Commerce Analyzer.
18.Configure WebSphere Commerce Analyzer.
19.Post-configure WebSphere Commerce Analyzer.
20.Save copies of the business reports.
For more detailed information on the WebSphere Commerce Analyzer
installation and configuration refer to:
Appendix C, “WebSphere Commerce Analyzer” on page 555
IBM WebSphere Commerce Analyzer: Installation and Configuration Guide
17.3.3 Business reports
Reports provide vital information for managing the success of the business.
WebSphere Commerce Analyzer generates predefined reports about the
marketing and shopping activities on the store. Reports generated by
WebSphere Commerce Analyzer through the Brio Broadcast server provide
information about the effectiveness of campaigns as well as information about
sales and the customer who use the store. These reports can be used to help
make decisions about the marketing strategy and the products sold in the store.
The business reports are organized into the following categories:
Marketing activities
Products
Sales grouped by geographic distribution
Note: Reports cannot be customized in WebSphere Commerce Analyzer. The
Reports provides information about one store and support one language, one
local, and multiple currencies.

522
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Sales grouped by customer demographics
Reports on marketing activities
The reports on marketing activities are organized into the following groups:
Campaigns
Initiatives
e-marketing spots
Combination of campaigns, initiatives, and e-marketing spots
Each group contains reports on the following:
Units abandoned
Impressions displayed
Impressions clicked
Impressions clicked and followed by orders
Table 17-1 summarizes the reports on marketing activities.
Table 17-1 Reports on marketing activities
Organized by Report Scope Time Period Formats
Campaigns
Initiatives
e-Marketing
Spots
Impressions
displayed
Impressions clicked
All
Top 10
Yesterday
This week
This month
This quarter
This year
Table
Bar chart
Units abandoned
Impressions
followed by orders
Yesterday
This week
This month
Campaigns,
Initiatives,
e-Marketing
Spots
combination
Impressions
displayed
Impressions clicked
Top 10 Yesterday
This week
This month
This quarter
This year
Impressions
followed by orders
Yesterday
This week
This month
Units abandoned All
Top 10

Chapter 17. Managing a store
523
Reports on products
The reports on products show the following information for products in the store.
Sales value
Units sold
Units abandoned
Sales value and units sold
The reports on products are summarized in Table 17-2.
Table 17-2 Reports on products
Reports by geographic area
The reports by geographic area are organized into the following groups:
Countries
States or Provinces
Cities
Postal codes
Each group contains reports on the following:
Sales value and units sold
Impressions displayed
Impressions clicked
Impressions clicked followed by orders
Organized by Report Scope Time Period Formats
Products Sales value
Units sold
Top 10
Bottom 10
Yesterday
This week
This month
This quarter
This year
Table
Bar chart
Units
abandoned
Top 10
Sales value
and units sold
All Table

524
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Table 17-3 summarizes the reports by geographic area.
Table 17-3 Reports on geographic area
Reports by customer demographics
The reports by customer demographics showpercentagesof sales value and
units sold grouped by various characteristics of the customers. The
characteristics are:
Age range
Income range
Gender
Marital status
The reports grouped by customer demographics are summarized in Table 17-4.
Table 17-4 Reports on sales value and units sold by customer demographics
Reports by time period
The reports by time period show sales value and units sold in detail for several
time periods. With these reports you can see, for example, which hour of the day
had the highest sales in terms of sales value and units sold.
Organized by Report Scope Time Period Formats
Countries
States or
Provinces
Cities
Postal Codes
Sales value
Units sold
All Yesterday
This week
This month
This quarter
This year
Table
Impressions
displayed
Impressions
clicked
Top 10 Table
Bar chart
Impressions
followed by
orders
Yesterday
This week
This month
Grouped by Report Scope Time Period Formats
Age range
Income range
Gender
Marital status
Sales value
and Units sold
All Yesterday
This week
This month
This quarter
This year
Table

Chapter 17. Managing a store
525
The time periods are:
Each Hour Of Yesterday
Each Day Of This Week
Each Day Of This Month
Each Week Of This Month
Each Month Of This Quarter
Each Month Of This Year
Each Quarter Of This Year
The reports by time period are summarized in Table 17-5.
Table 17-5 Reports on sales value and units sold by time period
Viewing the business reports
To view the business reports:
1.Open the Commerce Suite Accelerator. If you are a marketing manager,
merchandising manager, merchant, or site administrator, you will see the
Store menu.
2.Click Store -> Reports.
3.On the left side of the window, find the topic you want.
4.Click the topic to expand the section.
5.Scroll down until you find the report you want to view.
6.Click the report. The report you selected is displayed on the right side of the
window.
For more detailed information on business reports generated through
WebSphere Commerce Analyzer, refer to the IBM WebSphere Commerce
Analyzer: Users Guide.
Report Scope Time Period Formats
Sales value
Units sold
All Hours of the day
Days of the week
Weeks of the month
Months of the quarter
Months of the year
Quarters of the year
Table
Bar chart
Pie chart
Days of the month Table
Bar chart

526
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
17.3.4 Inventory report
WebSphere Commerce Suite V5.1 or WebSphere Commerce Analyzer V5.1
does not provide any inventory reports. The Change Product - Inventory page in
WebSphere Commerce Suite Accelerator displays the current inventory for a
product. This page can be used to maintain the inventory of a product, including
changing the current inventory to another value and specifying how the system
should handle inventory when a product is selected to be included in a customer
order.
The value is dynamically updated each time you view this page. Before you close
the notebook in WebSphere Commerce Suite Accelerator, ensure that you click
Inventory from the left navigation frame to return to this page to see the most
current inventory for the product. If the value of the Current inventory label has
changed, type an appropriate value in the inventory field.
To view the inventory for a product, do the following:
1.On the machine where WebSphere Commerce Suite is installed, click Start
-> Programs -> IBM WebSphere Commerce Suite -> Commerce Suite
Accelerator. Depending on your user role, one or more menus display.
2.From the Merchandise menu, select Products. A list of products for the store
displays.
3.Open the Change Product notebook by doing one of the following:
a.Select the check box to the left of the product that you want to work with
and click Change.
b.From the SKU column, click the SKU for the product.
4.From the left navigation frame, click Inventory. The Change Product -
Inventory page displays. The current inventory for the product displays on this
page. For an example, see Figure 17-3.

Chapter 17. Managing a store
527
Figure 17-3 Product inventory page

528
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
529
Part 4
Appendixes
Part 4

530
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1

© Copyright IBM Corp. 2001
531
Appendix A.
Use cases
Table A-1 lists the use cases created as part of Chapter 7, “Application design
guidelines” on page 115.
Table A-1 List of use cases
A
Use case ID Use case name Use case description
UC#1 Logon with LDAP User requests a login into the
store specifying User ID and
Password.
UC#2 User login authentication User’s credentials are verified in
directory and JNDI object with
user profile is sent to Commerce
Suite (see A.1, “UC#2 logon with
LDAP” on page 532).
UC#3 User profile update User data is inserted/updated
into Commerce Suite database
(see A.3, “UC#3 user profile
update” on page 533).
UC#4 Reorder User submits an order based on a
previous one.
UC#5 Orders’ schedule User submits a recurring order.
UC#6 Scheduled order deletion User deletes a recurring order

532
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
A.1 UC#2 logon with LDAP
Refer to 7.3, “Use case model” on page 127.
A.2 UC#2 user login authentication
Table A-2 UC#2 - user login authentication
ID UC#2
Name User login authentication.
Description Validation of a user in directory.
Primary Actor(s) LDAP AuthenticationCmd task called from Commerce Suite login
controller command.
Secondary
Actor (s)
N/A
Input(s) User ID and password.
Output(s) A user profile retrieved from directory.
An error/exception condition on failed authentication.
Preconditions SecureWay directory is running.
Success End
Condition
User ID and Password have been successfully validated in the
directory and the user profile was retrieved from directory.
Failure End
Condition
User login failed, due to any of the following conditions:∙
User ID and/or Password are not valid.
An error/exception condition occurred in directory.
Commerce Suite error/exception condition occurred.
Steps See also Figure A-1 on page 533.
1. The LogonCmd used AuthenticationCmd task to validate user
credentials.
2. The user profile is returned back from the directory to the store.

Appendix A. Use cases
533
Figure A-1 UC#2 - user login authentication
A.3 UC#3 user profile update
Table A-3 UC#3 - user profile update
Front-End
(ComSuite)
Commerce Suite store
Database
(DB2 7.1)
Directory
User Services
LoginCmd
LDAP AuthenticationCmd (UserID,Passwd)
UC#2
UserID,Passwd
Authentication failed
User Profile
Send Error page
ID UC#3
Name User profile update.
Description User profile is replicated from the directory to the store.
Primary Actor(s) Commerce Suite login command with LDAP AuthenticationCmd
task.
Secondary
Actor (s)
N/A
Input(s) User ID and password.
Output(s) OK = nothing on success.
An error/exception condition returned on failure.
Preconditions N/A

534
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure A-2 UC#3 - user profile update
A.4 UC#4 reorder
Table A-4 UC#4 - reorder
Success End
Condition
All relevant Commerce Suite member subsystem successfully
updated.
Failure End
Condition
An error/exception condition occurred.
Steps See also Figure A-2 on page 534
The LogonCmd receives the user profile from the directory and
updates the Commerce Suite database.
ID UC#3
Front-End
(ComSuite)
Database
(DB2 7.1)
LoginCmd
Update user profile
UC#3
(UserID,Password,User Profile)
Commerce Suite store
Error page
Ok or Error page
ID UC#4
Name Reorder
Description User submits an order based on a previous one.

Appendix A. Use cases
535
Figure A-3 Reorder
Primary Actor(s) Commerce Suite OrderCopy Command.
Secondary
Actor (s)
N/A
Input(s) fromOrderId, toOrderId, URL.
Output(s) OK = nothing on success, the view URL specified in URL input.
An error/exception condition returned on failure.
Preconditions User is logged, user has already submitted at least one order.
Success End
Condition
A new order is created.
Failure End
Condition
An error/exception condition occurred.
Steps See also Figure A-3
OrderCopy command receives input data (fromOrderId_i,
toOrderId,URL) from user and creates an order in the database.
ID UC#4
Front-End
(ComSuite)
Database
(DB2 7.1)
OrderCopy
Create an order
UC#4
(fromOrderId_i,toOrderId,URL
Commerce Suite store
URL page/
Error page
Ok or Error page

536
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
A.5 UC#5 order schedule
Table A-5 UC#5 - order schedule
ID UC#5
Name Orders’ schedule.
Description User submits a recurring order.
Primary Actor(s) Commerce Suite OrderSchedule command.
Secondary
Actor (s)
N/A
Input(s) orderId, interval, start, URL.
Output(s) OK = nothing on success, the view URL specified in URL input.
An error/exception condition returned on failure.
Preconditions User is logged, user has already submitted at least one order.
Success End
Condition
A new recurring order is created.
Failure End
Condition
An error/exception condition occurred.
Steps See also Figure A-3.
OrderSchedule command receives input data (orderId, interval,
start, URL) from user and creates a job in the scheduler which
submits an order with the specified frequency and from the specified
start date.

Appendix A. Use cases
537
Figure A-4 Order schedule
A.6 UC#6 scheduled order deletion
Table A-6 UC#6 - scheduled order deletion
Front-End
(ComSuite)
Database
(DB2 7.1)
OrderSchedule
Create a job in the job schedulerr
UC#5
(orderId,interval,start,URL)
Commerce Suite store
URL page/
Error page
Ok or Error page
ID UC#6
Name Scheduled order deletion.
Description User deletes a recurring order.
Primary Actor(s) Commerce Suite ScheduleOrderCancel command.
Secondary
Actor (s)
N/A
Input(s) orderId, URL.
Output(s) OK = nothing on success, the view URL specified in URL input.
An error/exception condition returned on failure.
Preconditions User is logged, user has submitted at least a recursive order.

538
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure A-5 Scheduled order deletion
Success End
Condition
The job is deleted from the scheduler.
Failure End
Condition
An error/exception condition occurred.
Steps See also Figure A-3.
ScheduleOrderCancel command receives input data (orderId, URL)
from user and deletes the job in the scheduler matching the order
selected.
ID UC#6
Front-End
(ComSuite)
Database
(DB2 7.1)
ScheduleOrderCancel
Deletes a job in the job scheduler
UC#6
(orderId,URL)
Commerce Suite store
URL page/
Error page
Ok or Error page

© Copyright IBM Corp. 2001
539
Appendix B.
Loader package
The Loader package primarily serves as a tool to load and/or update large
amounts of data in the WebSphere Commerce Suite database. The data to be
loaded is required to be in XML format. The utilities of the Loader package can
be used to load and/or update very selective data in the WebSphere Commerce
Suite store database.
The appendix is organized into the following sections:
Loader package components
Load process
Installation on remote machine
Sample data load
Loader usage considerations
B

540
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
B.1 Loader package components
The different components that make up the Loader package can be seen in
Figure B-1 on page 541. The components are briefly described below:
DTD Generator
The DTD Generator creates a DTD and schema to use with the Loader
package. This utility uses an input file containing database table names and
generates either a DTD alone or a DTD and a schema with a detailed XML
file describing the database, depending on how you invoke the DTD
Generator command. Usage of the command is explained in the following
sections.
ID Resolver
The ID Resolver generates identifiers for XML elements that require them. If
your XML content already supplies identifiers, you do not have to run the ID
Resolver. For example, the ID Resolver may be used as follows:
– When you are loading new content in XML format, and identifiers for the
data are required.
– When you are updating content where identifiers already exist for an
object in the database.
Loader
The Loader utility loads valid and well-formed XML input into the database.
Data must be in XML format with an associated document type definition
(DTD). The Load command has to be invoked to load data.

Appendix B. Loader package
541
Figure B-1 Load process
Create new
DTD
Create XML
file
Resolve XML
file
Load XML file
DTD Generator
ID Resolver
Loader
New DTD
XML
Resolved
XML
Default DTD
DTD

542
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
B.2 Load process
The data loading process involves a number of well-defined steps, including the
following:
Preprocessing phase
– Determine the subsystem, database schema and in particular the tables to
load data into.
– Generate a document type definition (DTD) using the DTD Generator
utility.
The DTD generator analyzes table definitions in the database to discover
the relationship between tables and primary keys and indexed columns.
– Create data input files in XML format.
Load phase
– Resolve IDs in the input files with the ID Resolver utility.
The ID Resolver substitutes symbols with unique values determined from
database primary keys or unique indexes. If a unique index does not exist
in a table, additional hints can be provided in IDResolveKeys.properties.
– Load the data using the Loader utility
B.3 Installation on remote machine
To install the Loader package on the remote machine, complete the following
steps:
1.Install the IBM JDK 1.2.2 on the remote system. IBM JDK 1.2.2 can be
installed from WebSphere Application Server CD by choosing the custom
installation and selecting the IBM JDK 1.2.2 component.
2.Install the Loader package by copying files listed in Table B-1 from
WebSphere Commerce Suite installation to the remote system. The variable
wcs_home is the WebSphere Commerce Suite installation path and the
variable loader_path is the Loader package installation path on the remote
machine.
Important: Back up the database before using massloader on your database.
In case of errors during execution, it is easier to roll back from a backup
database rather than fix the errors.

Appendix B. Loader package
543
Table B-1 Installation of the Loader package
3.Create batch files for DTD Generator, ID Resolver and the Loader. See
Example B-1, Example B-2 and Example B-3 below. The batch file are
included in the additional material SG246180.zip file, in the
<unzip_path>\sg246180\catalog directory.
Example: B-1 GenerateDTD.bat
@echo off
setlocal
set lib=%LOADER_HOME%\lib
Commerce Suite installation Remote system
wcs_home\lib\loader\DTDGenerator.zip loader_home\lib\
wcs_home\lib\loader\Logger.zip loader_home\lib\
wcs_home\lib\loader\IdResGen.zip loader_home\lib\
wcs_home\lib\loader\MassLoader.zip loader_home\lib\
wcs_home\lib\loader\WCALogger.zip loader_home\lib\
wcs_home\lib\loader\PropGen.zip loader_home\lib\
wcs_home\lib\loader\SAFServ.zip loader_home\lib\
wcs_home\lib\loader\WCMCommon.zip loader_home\lib\
wcs_homes\lib\loader\WCSTasks.zip loader_home\lib\
wcs_home\lib\loader\wcmxmlp.jar loader_home\lib\
wcs_home\lib\loader\wcmxslt.jar loader_home\lib\
wcs_homeh\lib\loader\jgl2.0.0.jar loader_home\lib\
wcs_home\lib\jlog.jar loader_home\lib\
wcs_home\lib\loader\db2\dbconnect.zip loader_home\lib\db2\
wcs_home\lib\loader\oracle\dbconnect.zi
p
loader_home\lib\oracle\
wcs_home\xml\loader\WCALoggerCofig.
xml
loader_home\xml\
wcs_home\xml\loader\MassLoaderCuso
mized.properties
loader_home\xml\
wcs_home\xml\loader\wcaLogger.dtd loader_home\xml\
wcs_home\xml\sar\DBLoadMacros.dtd loader_home\

544
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
set
CP1=%lib%\DTDGenerator.zip;%lib%\IdResGen.zip;%lib%\Logger.zip;%lib%\MassLoader
.zip
set
CP2=%lib%\SAFServ.zip;%lib%\WCALogger.zip;%lib%\WCMCommon.zip;%lib%\WCSTasks.zi
p
set
CP3=%lib%\jgl2.0.0.jar;%lib%\wcmxmlp.jar;%lib%\wcmxslt.jar;%lib%\db2\dbconnect.
zip
set CP4=%lib%\jlog.jar;%LOADER_HOME%\xml\
set CP="%CP1%;%CP2%;%CP3%;%CP4%;%CLASSPATH%"
set GenerateDTD=com.ibm.wca.DTDGenerator.GenerateDTD
set args=
:loop
if '%1'=='' goto run
set args=%args% %1
shift
goto loop
:run
java -classpath %CP% %GenerateDTD% %args%
endlocal
Example: B-2 IDResolve.bat
@echo off
setlocal
set lib=%LOADER_HOME%\lib
set
CP1=%lib%\DTDGenerator.zip;%lib%\IdResGen.zip;%lib%\Logger.zip;%lib%\MassLoader
.zip
set
CP2=%lib%\SAFServ.zip;%lib%\WCALogger.zip;%lib%\WCMCommon.zip;%lib%\WCSTasks.zi
p
set
CP3=%lib%\jgl2.0.0.jar;%lib%\wcmxmlp.jar;%lib%\wcmxslt.jar;%lib%\db2\dbconnect.
zip
set CP4=%lib%\jlog.jar;%LOADER_HOME%\xml\
set CP="%CP1%;%CP2%;%CP3%;%CP4%;%CLASSPATH%"
set IdResolve=com.ibm.wca.IdResGen.IdResolve
set args=
:loop
if '%1'=='' goto run

Appendix B. Loader package
545
set args=%args% %1
shift
goto loop
:run
java -classpath %CP% %IdResolve% %args%
endlocal
Example: B-3 MassLoad.bat
@echo off
setlocal
set lib=%LOADER_HOME%\lib
set
CP1=%lib%\DTDGenerator.zip;%lib%\IdResGen.zip;%lib%\Logger.zip;%lib%\MassLoader
.zip
set
CP2=%lib%\SAFServ.zip;%lib%\WCALogger.zip;%lib%\WCMCommon.zip;%lib%\WCSTasks.zi
p
set
CP3=%lib%\jgl2.0.0.jar;%lib%\wcmxmlp.jar;%lib%\wcmxslt.jar;%lib%\db2\dbconnect.
zip
set CP4=%lib%\jlog.jar;%LOADER_HOME%\xml\;%LOADER_HOME%\properties
set CP="%CP1%;%CP2%;%CP3%;%CP4%;%CLASSPATH%"
set MassLoad=com.ibm.wca.MassLoader.MassLoad
set args=
:loop
if '%1'=='' goto run
set args=%args% %1
shift
goto loop
:run
java -classpath %CP% %MassLoad% %args%
endlocal
4.Add the LOADER_HOME directory to your system path. For example:
set LOADER_HOME=c:\Loader on Windows NT
5.Ensure that the IBM JDK 1.2.2 is in the CLASSPATH.

546
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
B.4 Sample data load
As was described before, the data load using the Loader package consists of a
set of well-defined steps. In this section we go step by step through this process.
The data zip file referred to in Appendix D, “Additional material” on page 583
contain the files used in our examples.
1.Create the tablenames.txt file, this file will list all the tables that you intend
loading data into. The content of the tablesnames.txt can be seen below. The
table names should be separated by a carriage return.
Here is a list of tables:
STOREENT
FFMCENTER
STORE
TRADEPOSCN
CATALOG
CATENTRY
CATENTREL
CATENTDESC
ATTRIBUTE
ATTRVALUE
OFFER
OFFERPRICE
LISTPRICE
CATGPENREL
STORECENT
INVENTORY
2.Create the Document Type Definition (DTD) for the tables listed in the
tablenames.txt file by running GenerateDTD batch file from an MS-DOS
command prompt.
GenerateDTD -dbname stagprop -dbuser db2inst1 -dbpwd db2inst1 -outfile
catalog.dtd -infile tablenames.txt
The GenerateDTD batch file executes the
com.ibm.wca.DTDGenerator.GenerateDTD command with syntax described
in Figure B-2.

Appendix B. Loader package
547
Figure B-2 DTD Generate syntax
Table B-2 describes the parameter values for DTD Generator.
Table B-2 DTD Generator parameters
The DTD generated for the tablename.txt file created in the last step is shown
Example B-4.
Example: B-4 A fragment of catalog.dtd file
<!ELEMENT stagprop (( storeent | ffmcenter | store | tradeposcn | catalog |
catgroup | catentry | catentrel | catentdesc | attribute |
attrvalue | offer | offerprice | listprice | catgpenrel |
storecent | inventory)*)>
<!ELEMENT storeent EMPTY>
<!ATTLIST storeent
storeent_id CDATA#REQUIRED
member_id CDATA#REQUIRED
Parameter Description
dbname The name of the target database.
dbuser The name of the user connecting to the database.
dbpwd The password for the user connecting to the database.
outfile The name of the output DTD file.
infile The name of an input file containing a database table name on
each line.
tablenames The names of tables, separated by commas.
xmlTableDesc The file path of the schema file to be created.

548
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
type CDATA#REQUIRED
identifier CDATA#REQUIRED
<!ELEMENT tradeposcn EMPTY>
<!ATTLIST tradeposcn
tradeposcn_id CDATA#REQUIRED
member_id CDATA#REQUIRED
description CDATA#IMPLIED
name CDATA#IMPLIED
flags CDATA#REQUIRED
>
<!ELEMENT catalog EMPTY>
<!ATTLIST catalog
catalog_id CDATA#REQUIRED
member_id CDATA#REQUIRED
identifier CDATA#REQUIRED
description CDATA#IMPLIED
>
3.Create the XML data input file that conforms to the DTDs that were
generated.
– When you create an XML datafile for the loader, you can use symbols in
the XML file instead of database-unique IDs so that the data can be
loaded into different stores without overwriting existing records. For
example, you could use @storeent_id_1 to represent the store entity ID.
The ID resolver will query the database to replace these symbols with the
correct ID number (either a new value if new data is being loaded or the
value for an existing record if data is being updated).
– You can use the XML macros that begin with & and end with ; (for example
member_id=”&MEMBER_ID;” in Example B-5). Some default macros are
provided in file DBLoadMacros.dtd for the default member ID and
language IDs configured in Commerce Suite. You can define additional
macros if you wish.
– Include the catalog.dtd file at the beginning of the XML as can be seen in
Example B-5.
Note: Add the following lines on the bottom of catalog.dtd
<!ENTITY % DBLoadMacros SYSTEM "DBLoadMacros.dtd">
%DBLoadMacros;
This will automatically include the XML macros from file DBLoadMacros.dtd
whenever this DTD file is processed.

Appendix B. Loader package
549
For guidelines to create XML data input files refer to IBM WebSphere
Commerce Suite V5.1 online documentation, or click Topics -> Tasks ->
Create an online catalog -> Create catalog assets.
Example B-5 shows an example of an XML data input file.
Example: B-5 Fragment of the XML data imput file
<?xml version="1.0"?>
<!DOCTYPE stagprop SYSTEM "catalog.dtd">
<stagprop>
<!-- Entities referencing existing store data -->
<!-- May need to be edited if names are changed -->
<storeent
storeent_id="@storeent_id_1"
identifier="&STORE_NAME;"
type="S"
member_id="&MEMBER_ID;"
/>
<!-- Trading position container -->
<tradeposcn
tradeposcn_id="@tradeposcn_id_101"
member_id="&MEMBER_ID;"
description="-"
name="-"
flags="0"
/>
<!-- Catalog -->
<catalog
catalog_id="@catalog_id_1"
member_id="&MEMBER_ID;"
identifier="InFashions"
description="In Fashions Catalog"
/>
4.Create an ID resolved version of the XML data input file by running
IDresolve.bat batch file from an MS-DOS command prompt:
IDResolve -dbname stagprop -dbuser db2inst1 -dbpwd db2inst1 -infile
catalog.xml -outfile catalogResolved.xml -method mixed
The IDresolve batch file executes the com.ibm.wca.IDResGen.IdResolve
command with syntax described in Figure B-3.

550
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure B-3 ID Resolve syntax
Table B-2 describes the parameter values for ID Resolve.

Appendix B. Loader package
551
Table B-3 Parameter values
Example B-6 shows an example of an ID-resolved XML data input file.
Example: B-6 Resolved XML file
<?xml version="1.0"encoding="UTF-8"?>
<!-- name: catalogres.xml
Description: This file contain data generated by IBM utility.
-->
<stagprop>
<storeent
STOREENT_ID="10101"
IDENTIFIER="ITSOFashion"
TYPE="S"
MEMBER_ID="-2000"
/>
Parameter Description
dbname The name of the target database.
dbuser The name of the user connecting to the database.
dbpwd The password for the user connecting to the database.
outfile The name of the output XML file to be produced. This file may be
used as input to the Loader utility.
infile The name of the input XML document containing table record
descriptors.
method The method to be used in processing the input file. The command
either treats the input file as though the records do not exist in the
database (load), or as if there are already identifiers for the input
objects (update). Use mixed mode when some records do not exist
in the database and some do. The default method is load.
propfile The text file containing Java properties in the form of name=value
pairs. This file is used to define the lookaside column names for
foreign key identifier lookup and the select predicate for main table
(such as Category and Product) queries. The default file is
IdResolveKeys.properties. You may omit entries in this file for
tables in the KEYS table that have a unique index defined that does
not include the identifier. Do not use the .properties extension
when specifying the value.
customizer The .properties file with the database connection information. This
parameter is optional. If not specified, the command uses DB2
connection information.

552
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
<tradeposcn
TRADEPOSCN_ID="10001"
MEMBER_ID="-2000"
DESCRIPTION="-"
NAME="-"
FLAGS="0"
/>
<catalog
CATALOG_ID="10001"
MEMBER_ID="-2000"
IDENTIFIER="InFashions"
DESCRIPTION="In Fashions Catalog"
/>
5.Invoke the Load command to load the ID resolved XML input file. The Load
command can be invoked by the MassLoad.bat batch file, which executes the
com.ibm.wsa.MassLoader.MassLoad command with the syntax described in
Figure B-4.
massload -dbname stagprop -dbuser db2inst1 -dbpwd db2inst1 -infile
catalogResolved.xml -method sqlimport -noprimary insert
Figure B-4 Load syntax
Table B-4 explains the parameter values for the Load command.

Appendix B. Loader package
553
Table B-4 Parameter values for the Load command
Parameter Description
dbname The name of the target database.
dbuser The name of the user connecting to the database.
dbpwd The password for the user connecting to the database.
infile The name of the input XML file.
method The mode of operation for the Loader to use when inserting data
into the database. The load option uses the native loader from the
database vendor. DB2 and Oracle are supported. Note that the
load option may be used only for local databases. The sqlimport
option uses the import or update option if it is available from the
database vendor. If the import or update option is not available,
SQL statements using JDBC are used to update the database. The
sqlimport option may be used with both local and remote
databases. The cadelete option processes delete.data files from
WebSphere Catalog Manager clients. The default method is
import.
nonprimary The action the Loader must take when the primary key is missing
for a record in the input file. The error option indicates that it should
report the missing primary key as an error and terminate. The skip
option skips the records in the input file that do not have a primary
key. The insert option tries to insert the data. Error is the default
option.
commitcount The number of records processed before the database commit
occurs, when using the SQL update mode of operation.
errorcount The number of errors after which the Loader will terminate in the
SQL update mode of operation.
delete Deletes records specified by the element.

554
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
B.5 Loader usage considerations
There are many issues to consider in using and determining the best way to use
MassLoader. Some things to consider, in determining how, when and where to
run MassLoader from, are as follows:
Size of the data load
Length of required downtime
Network traffic
Sensitivity of data
If large amounts of data are to be loaded, it will obviously take more time, which
impacts the downtime. The load on the network and the sensitivity of data might
require that the MassLoader be run from the databases machine.
Note:
If you execute MassLoader from a remote machine, the load option is not
applicable for the method parameter in the MassLoader commands.
If you are loading data to the table without a primary key, you cannot use
the load and import method.
Tables that include referential or check constraints are placed in check
pending state. Summary tables that are defined with REFRESH
IMMEDIATE, and that are dependent on tables being loaded, are also
placed in check pending state. Issue the SET INTEGRITY statement to
take the tables out of check pending state.

© Copyright IBM Corp. 2001
555
Appendix C.
WebSphere Commerce
Analyzer
WebSphere Commerce Analyzer V5.1 provides predefined business reports for
the marketing and shopping activities of a WebSphere Commerce Suite V5.1
store. This appendix describes how to install, configure, and use WebSphere
Commerce Analyzer with WebSphere Commerce Suite V5.1.
This appendix is organized into the following sections:
Pre-installation requirements
Installing WebSphere Commerce Analyzer
Configuring WebSphere Commerce Analyzer
Post configuration
Saving copies of the business reports
C

556
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
C.1 Pre-installation requirements
Before installing WebSphere Commerce Analyzer server, be sure that you have
met the hardware and software requirements, as well as gathered the necessary
information needed during the installation and configuration.
This section includes the following pre-installation requirements:
Creating the required Commerce Suite shared folders
Commerce Suite HTML relative report path
Information required during installation
Controlling access to the business reports
Default printer on the Commerce Analyzer server
C.1.1 Creating the required Commerce Suite shared folders
WebSphere Commerce Analyzer requires shared folder access to the
Commerce Suite server root installation folder and the root of the HTTP Server
docs folder. This allows the WebSphere Commerce Analyzer system access to
read configuration data and have a location to write reports accessible by the
Commerce Suite Accelerator.
This section documents the necessary tasks to create and map the shared
folders from a remote Commerce Analyzer system to a Commerce Suite server
as follows:
1.Create a Windows user on the Commerce Analyzer system with administrator
privileges. For example, we created an administrator called admin, who is the
logged-in user for our example.
2.Share the root installation directory of Commerce Suite and the root directory
of the HTTP Server documents directory. In our example, we created the
Note:
WebSphere Commerce Analyzer runs only on Windows NT 4.0 with
Service Pack 6a or Windows 2000.
WebSphere Commerce Analyzer provides information about one store and
supports one language, one locale, and multiple currencies.
The reports cannot be customized.

Appendix C. WebSphere Commerce Analyzer
557
shares and set the access permissions on Commerce Suite server as seen in
Table C-1.
Table C-1 Shared folders on the Commerce Suite server for Commerce Analyzer
3.On the Commerce Analyzer system, map network drives to the shares
created on the Commerce Suite server listed in Table C-1.
For example, we mapped the following network drives on the Commerce
Analyzer to the Commerce Suite server:
– net use z: \\<commerce_server>\wcs
– net use h: \\<commerce_http_server>\htdocs
C.1.2 Commerce Suite HTML relative report path
By default, the reports generated by the Commerce Analyzer information will be
stored in the <HTTP_Server_install_path>\htdocsWCA\reports directory.
C.1.3 Information required during installation
Before you install WebSphere Commerce Analyzer, we recommend that you
gather the following information required during the installation and configuration
of WebSphere Commerce Analyzer.
WebSphere Commerce Suite information:
– Host name of the WebSphere Commerce Suite database server (for
example, m23caaax)
– Port number of the WebSphere Commerce Suite database server (for
example, 50000)
Share
name Directory Description
Access
permission
wcs c:\ibm\wcs Root directory of the
Commerce Suite installation.
Read
htdocs c:\ibm\http\htdocs Root directory of the HTTP
Server Web documents
directory.
Full control
Note: If you modified the default settings for the
<HTTP_Server_install_path>\htdocs directory for the Commerce Suite
instance (Configuration Manager), you must provide the new subdirectory
name.

558
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
– Database name of the WebSphere Commerce Suite server database (for
example, wcsdb)
– Database alias of the WebSphere Commerce Suite server database (for
example, wcsdb)
– User ID used to access the WebSphere Commerce Suite server database
(for example, banik)
– Password used to access the WebSphere Commerce Suite server
database (for example, banik)
– Store Name and ID for the store for which you want to generate business
reports (for example, Web Fashion (10201))
– Locale of the WebSphere Commerce Suite server with the store for which
you want to generate business reports (for example, en_US)
– Currency of the WebSphere Commerce Suite server with the store with
which you want to generate business reports (for example, USD)
WebSphere Commerce Analyzer information:
– ODBC name of the WebSphere Commerce Suite database (for example,
wcsdb)
– User ID for the WebSphere Commerce Analyzer datamart and Control
databases (for example, admin)
– Password for the WebSphere Commerce Analyzer datamart and Control
databases (for example, admin)
– ODBC name for the DB2 Warehouse Center Control Database in
WebSphere Commerce Analyzer server (for example, itsowccd)
C.1.4 Controlling access to the business reports
The business reports contain sensitive business data. Data describing the levels
of sales volume and values, numbers of products sold, and results of campaigns
might be valuable to competitors and should be protected. Because the reports
are read-only, there is nothing in the reports that could be changed to alter the
operation of the site or to change the quality of the data. Each system
administrator must plan and set up the configuration of the WebSphere
Commerce Analyzer server and the HTTP Server that provide access to the
reports, as well as other facilities, so that all of the sensitive data is protected.
The specific configuration will depend on the overall security needs of the
business and the network environment in which the servers are installed and
accessed. Generally, you must protect access to the business reports as you
would any other internal sensitive Web information.

Appendix C. WebSphere Commerce Analyzer
559
For example, configure the servers as follows:
The reports are accessible only within the intranet of the business.
The sensitive data is protected behind a firewall that isolates the enterprise
from the external Internet.
Normally, the files that contain the report information are protected on the Web
server so that they can be accessed only by authorized people. Often these are
the same individuals as those accessing the WebSphere Commerce Suite
Accelerator, but others might have business needs to access the reports.
Configuration of the HTTP Server to provide this access control involves
well-known authentication and access control techniques. The HTTP Server
configuration file contains directives that isolate the report directory from general
access. A sample fragment of an Apache Server configuration file that illustrates
this isolation and sets up the authentication and access control files follows:
<Directory “c:/ibm/http/htdocs/WCA/reports”>
AuthType Basic
AuthName “proprietary”
AuthUserFile “c:/ibm/http/ReportUserAuthorization”
AuthGroupFile “c:/ibm/http/ReportGroupAuthorization”
require valid-user
<Directory>
This configuration file defines <HTTP_Server_install_path>\htdocs\WCA\reports
as the protected directory. It also does the following:
Indicates that the type of authentication to be used is basic
Specifies proprietary as the name of a realm for the reports
Specifies the location of the following files:
– User ID and password file
– Group and members file
You then use the standard HTTP Server tools to set up the user ID and password
file as well as the group and members file. Your configuration is determined by
authorization groups you have already configured for operation of your site or
enterprise business.
Note: Directory names and other information must be changed to the correct
names for your installation.

560
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
C.1.5 Default printer on the Commerce Analyzer server
If you define a network printer as the default printer on the WebSphere
Commerce Analyzer server, the Brio Broadcast Server may lock up for a period
of time. Therefore, do not define as the default printer a network printer shared
over NetBIOS. You can install a NetBIOS shared printer as long as it is not the
default printer. Applications that provide local printer ports do not exhibit this
problem.
C.2 Installing WebSphere Commerce Analyzer
Once the pre-installation tasks have been completed, we are now ready to install
WebSphere Commerce Analyzer, by completing the following steps:
1.On the computer that will be the WebSphere Commerce Analyzer server,
close any programs that are running.
2.Insert the IBM WebSphere Commerce Analyzer CD.
3.From the root directory of the IBM WebSphere Commerce Analyzer CD, run
setup.
4.Read the information on the Setup IBM WebSphere Commerce Analyzer
window, and click Next.
5.If the Select Components window is displayed, select the Brio Broadcast
Server Version 6.2 and click Next.
6.On the Choose Destination Location window, either accept the default folder
in which WebSphere Commerce Analyzer will be installed or click Browse to
specify another folder. (The default directory is C:\Program Files\IBM\IBM
WebSphere Commerce Analyzer.) Click Next.
7.On the Select Program Folder window, accept the folder displayed or select
another folder from the list. The installation program adds WebSphere
Commerce Analyzer Start menu items to the folder that you specify. Click
Next.
8.If the Choose IBM DB2 Installation Media window is displayed, accept the
drive letter of the CD-ROM drive if you are installing DB2 from the CD, or click
Browse to select a drive. For example, if you are installing DB2 from a hard
disk on a server, select or enter the drive and path on the hard disk. Click
Next.
9.If the Choose IBM DB2 Folder window is displayed, either accept the default
destination folder or click Browse to select the location where you want to
install DB2. Click Next.

Appendix C. WebSphere Commerce Analyzer
561
10.If the IBM DB2 User Name and Password window is displayed, type the user
name and password for the DB2 administrator. For the name and password
creation rules, follow Example C-1.
Example: C-1 DB2 user name and password creation rules
Use the following guidelines for the user name and password:
– You can include only the following characters in the user name and
password:
• a – z (For the password, both uppercase and lowercase characters are
permitted. User names on Windows are not case-sensitive.)
• 0 – 9
• @, #, $
– The user name cannot be longer than 8 characters.
– The user name cannot be any of the following, in upper, lower, or mixed
case: USERS, ADMINS, GUESTS, PUBLIC, LOCAL.
– The user name cannot begin with any of the following, in upper, lower, or
mixed case: IBM, SQL, SYS.
– The user name cannot be the same as any Windows service name or the
hostname of the computer.
– The user name must be defined on the local computer and belong to the
Local Administrator’s group.
– The user name must have the Act as part of the operating system
advanced user right.
– The password cannot be longer than 32 characters.
– If the user name is a Windows logon user name that is already defined,
the password must be the password for that user name. The password
must also conform to all the other requirements. If it does not conform,
particularly to the character set limitations, the password for the Windows
user name must be changed.
– Click Next.
Note: To be sure that the user name has the correct access, specify a user
name that is not already defined, and it will be created with the correct
access rights.

562
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
11.On the Choose Brio BCS Installation Media window, accept the drive letter of
the CD-ROM drive if you are installing the Brio Broadcast Server from the CD,
or click Browse to select a drive. For example, if you are installing the Brio
Broadcast Server from a hard disk on a server, select or enter the drive and
path on the hard disk. Click Next.
12.On the Choose Brio BCS Folder window, click Browse to select the location
where you want to install the Brio Broadcast Server. Click Next.
13.On the Start Copying Files window, click Next if all information is correct.
14.The installation program prompts for any CDs that it needs during installation.
A progress indicator is displayed while the installation program copies files.
15.When installation is complete, the README file is displayed. Read or print
the information and close the window.
16.The Setup Complete window is displayed. Select Yes, I want to restart my
computer now, and then click Finish.
C.3 Configuring WebSphere Commerce Analyzer
After installation, the Commerce Analyzer Configuration Manager creates
databases on the Commerce Analyzer server and sets parameters that enable
the Commerce Analyzer server to communicate with the Commerce Suite
database server. You can also use the Commerce Analyzer Configuration
Manager to change the configuration of the Commerce Analyzer server. The first
time you run the Commerce Analyzer Configuration Manager, it creates the
following databases:
DB2 Warehouse Center Control Database
WebSphere Commerce Analyzer datamart
This section includes the following configuration tasks:
Commerce Analyzer Configuration Manager
Required configuration for Commerce Analyzer
Configuring WebSphere Commerce Suite
Creating the datamart
Note: If DB2 is already installed before installing WebSphere Commerce
Analyzer, then steps 8 to 10 will not appear.
Note: Make sure that the DB2 Warehouse server and logger window services
are started.

Appendix C. WebSphere Commerce Analyzer
563
Preparing the datamart
Configuring the Brio Broadcast Server
Configuring the warehouse
Configuring the extraction scripts
Changing the store, language, or currency
C.3.1 Commerce Analyzer Configuration Manager
This section includes instructions for starting the Commerce Analyzer
Configuration Manager, a description of common tasks and the required steps to
configure the Commerce Analyzer.
Starting the Commerce Analyzer Configuration Manager
To start the Configuration Manager, click Start -> Programs -> IBM WebSphere
Commerce Analyzer -> Configuration. The IBM WebSphere Commerce
Analyzer Configuration Manager window should be displayed as seen in
Figure C-1.
Figure C-1 IBM WebSphere Commerce Analyzer Configuration Manager window

564
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Common tasks
The tasks shown in the left-hand pane are as follows:
Configuring for the First Time
Use this task if you have installed WebSphere Commerce Analyzer but have
not yet configured it.
Changing the Commerce Suite Connection
Use this task if you change any of the following parameters on the Commerce
Suite database server:
– ODBC name
– User ID or password of the valid database user
– Host name
– Port number or TNS name
– Database instance or alias
– Database schema
Recreating the Datamart
Use this task if you want to remove old information from the datamart and
create a new datamart.
Changing the Store, Language, and Currency
Use this task if you want to change the store, language, or currency for which
WebSphere Commerce Analyzer generates the business reports.
Exit
Use this selection to exit the Configuration Manager.
C.3.2 Required configuration for Commerce Analyzer
This section describes the required steps for using the Commerce Analyzer
Configuration Manager to configure Commerce Analyzer.
1.If the Configuration Manager has not already started, start it. The IBM
WebSphere Commerce Analyzer Configuration Manager window is
displayed.
2.On the left side of the window, click the task you want.
A new window is displayed. The window contains a numbered series of steps
on tabs at the top of the window. Follow the steps in order. When you have
completed one step, click the tab for the next step at the top of the window, or
click Next to proceed to the next step. The steps that are displayed vary
depending on which task you clicked.

Appendix C. WebSphere Commerce Analyzer
565
3.Configuring for the first time:
a.Create a new DB2 connection (see C.3.3.1, “Create a new DB2
connection” on page 567 for instructions)
b.Configure Commerce Suite (see C.3.3, “Configuring WebSphere
Commerce Suite” on page 566 for instructions)
c.Create Datamart (see C.3.4, “Creating the datamart” on page 568 for
instructions)
d.Prepare Datamart (see C.3.5, “Preparing the datamart” on page 569 for
instructions)
e.Configure Brio (see C.3.6, “Configuring the Brio Broadcast Server” on
page 570 for instructions)
f.Configure Warehouse (see C.3.7, “Configuring the warehouse” on
page 570 for instructions)
g.Configure Extract (see C.3.8, “Configuring the extraction scripts” on
page 571 for instructions)
h.Change Store (see C.3.9, “Changing the store, language, or currency” on
page 573 for instructions)
4.Changing the Commerce Suite Connection:
a.Configure Commerce Suite (see C.3.3, “Configuring WebSphere
Commerce Suite” on page 566 for instructions)
b.Configure Warehouse (see C.3.7, “Configuring the warehouse” on
page 570 for instructions)
c.Configure Extract (see C.3.8, “Configuring the extraction scripts” on
page 571 for instructions)
5.Recreating the Datamart:
a.Prepare Datamart (see C.3.5, “Preparing the datamart” on page 569 for
instructions)
b.Configure Brio (see C.3.6, “Configuring the Brio Broadcast Server” on
page 570 for instructions)
c.Change Store (see C.3.9, “Changing the store, language, or currency” on
page 573 for instructions)
6.Changing the store.
a.Connect to Commerce Suite.
Note: You may start with step b. If it fails then go back to step a and start
from step a.

566
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
b.Change store (see C.3.9, “Changing the store, language, or currency” on
page 573 for instructions)
For the configuring the WebSphere Commerce Analyzer server, use WebSphere
Commerce Analyzer Configuration Manager. To configure WebSphere
Commerce Analyzer for the first time, click Configure for the First Time.
C.3.3 Configuring WebSphere Commerce Suite
When you configure WebSphere Commerce Suite, parameters are set that
enable the WebSphere Commerce Analyzer server to connect to the Commerce
Suite database server. During this configuration step, the Configure WCS tab at
the top of the IBM WebSphere Commerce Analyzer Configuration Manager
window is selected as seen in Figure C-2
Figure C-2 Connect to WebSphere Commerce Suite window
To configure WebSphere Commerce Suite, do the following:
1.Select the 1. Configure WCS tab as seen in Figure C-2, and then select the
Connect to WCS tab.
2.Complete the following fields if they do not contain the correct information:

Appendix C. WebSphere Commerce Analyzer
567
– ODBC Name
– User Name
– Password
3.Click Test WCS Connection to determine whether the WebSphere
Commerce Analyzer server can connect to the Commerce Suite database
server.
4.After the test is complete, do one of the following:
– If the connection to the Commerce Suite database server was successful,
go to C.3.4, “Creating the datamart” on page 568.
– If the connection to the Commerce Suite database server did not exist,
click Create a New DB2 Connection if the Commerce Suite database
type is DB2.
C.3.3.1 Create a new DB2 connection
1.If you clicked Create a New DB2 Connection, do the following:
a.Complete the following fields:
• Hostname
• Port Number
• Database Alias
• Database Name
b.Click Create a DB2 Connection. On successful connection you will see
the command status window.
c.Click the Connect to WCS tab.
d.Click Test WCS Connection again to determine whether the WebSphere
Commerce Analyzer server can connect to the Commerce Suite database
server.
2.You have now completed configuration of Commerce Suite. Click the tab for
the next step at the top of the IBM WebSphere Commerce Analyzer
Configuration Manager window, or click Next to go to the next step.

568
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
C.3.4 Creating the datamart
During this configuration step, you create the datamart on the WebSphere
Commerce Analyzer server. During this configuration step, the Create Datamart
tab at the top of the IBM WebSphere Commerce Analyzer Configuration
Manager window is selected as seen in Figure C-3.
Figure C-3 Create datamart
To create the datamart:
1.Select 2. Create DataMart tab, enter the following and then click Create
Datamart.
– Datamart Name
– Datamart Owner
Note: If you get an error message instead of a successful message, or want
more detailed information, refer to the IBM WebSphere Commerce Analyzer:
Installation and Configuration Guide.

Appendix C. WebSphere Commerce Analyzer
569
– Datamart Drive
The creation of the datamart takes several minutes.
2.After the datamart is created, click Test Datamart to verify that the database
is ready to use.
You have now completed creation of the WebSphere Commerce Analyzer
datamart. Click the tab for the next step at the top of the IBM WebSphere
Commerce Analyzer Configuration Manager window, or click Next to go to the
next step.
C.3.5 Preparing the datamart
During this configuration step, you prepare the datamart on the WebSphere
Commerce Analyzer server to contain new information. Any information currently
in the datamart is removed. During this configuration step, the Prepare Datamart
tab at the top of the IBM WebSphere Commerce Analyzer Configuration
Manager window is selected.
To prepare the datamart to contain new information, do the following:
1.Select the 3. Prepare DataMart tab, enter the following and then click
Prepare the DataMart:
– WCS Product Install Directory
– WCS HTML Document Root
– WCS HTML Relative Report Path:
2.You have now completed preparation of the WebSphere Commerce Analyzer
datamart. Click the tab for the next step at the top of the IBM WebSphere
Commerce Analyzer Configuration Manager window, or click Next to go to
the next step.
Note: The datamart name is restricted to the name BIDM. The owner is the
Windows user ID of the logged in user.
Note: If you get an error message instead of a successful message or need
more detailed information, refer to the IBM WebSphere Commerce Analyzer:
Installation and Configuration Guide.
Note: Only type the mapped letters.

570
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
C.3.6 Configuring the Brio Broadcast Server
During this configuration step, you set up the Brio Broadcast Server to generate
the business reports. During this configuration step, the Configure Brio tab at the
top of the IBM WebSphere Commerce Analyzer Configuration Manager window
is selected.
To configure the Brio Broadcast Server, do the following:
1.Select the 4. Configure Brio tab, and then click Configure Brio.
2.You have now completed configuration of the Brio Broadcast Server. Click the
tab for the next step at the top of the IBM WebSphere Commerce Analyzer
Configuration Manager window, or click Next to go to the next step.
C.3.7 Configuring the warehouse
During this configuration step, you configure the DB2 Warehouse Center Control
Database on the WebSphere Commerce Analyzer server to manage the
extraction and report generation process. During this configuration step, the
Configure Warehouse tab at the top of the IBM WebSphere Commerce Analyzer
Configuration Manager window is selected as seen in Figure C-4.

Appendix C. WebSphere Commerce Analyzer
571
Figure C-4 DB2 Warehouse configuration window
To configure the DB2 Warehouse Center Control Database:
1.Select the 5. Configure Warehouse tab, enter the following and then click
Create Warehouse:
– Warehouse Database Name
– Warehouse Admin User
– Warehouse Admin Password
– Warehouse Schema Name
2.You have now completed creation of the DB2 Warehouse Center Control
Database. Click the tab for the next step at the top of the IBM WebSphere
Commerce Analyzer Configuration Manager window, or click Next to go to
the next step.
C.3.8 Configuring the extraction scripts
During this configuration step, the WebSphere Commerce Analyzer extraction
scripts are configured and stored in the DB2 Warehouse Center Control
database.

572
e-commerce Patterns for Building B2C Web Sites Using IBM WebSphere Commerce Suite V5.1
Figure C-5 Configure WebSphere Commerce Analyzer extraction window
To configure the extraction scripts, do the following:
1.Select the 6. Configure Extract tab, enter the following and then click
Configure Extraction Scripts (see Figure C-5):
– WebSphere Commerce Suite:
• Database
• User
• Schema
– WebSphere Commerce Analyzer:
• Datamart
• Owner
– DB2 Warehouse Center:
• Database
• Administrator
• Password

Appendix C. WebSphere Commerce Analyzer
573
– Extraction period
2.You have now completed configuration of the extraction scripts. If this is not
the last step for the configuration task you are completing, click the tab for the
next step at the top of the IBM WebSphere Commerce Analyzer Configuration
Manager window, or click Next to go to the next step.
C.3.9 Changing the store, language, or currency
During this configuration step, you set or change the name, language, or
currency of the store for which the business reports are generated.
Figure C-6 Change store wind