WebSphere Commerce V5.5 Handbook, Customization and Deployment Guide 9780738499437

Citation preview

---

Front cover

WebSphere Commerce mmerce V5.5 Handbook book Customization and Deployment Guide Runtime architecture, programming model, business and store models overview Team development scenario to create, customize, build, deploy and manage a store Implement advanced multi-tiered runtime configurations Integrate MQ, e-mail, and Commerce Analyzer

John Ganci Hernan Cunico Daniel Dunn Steve Insley Ryan Karchner Emad Muhanna Nicolai Nielsen Abhishek Singh Sean Zhu

ibm.com/redbooks

International Technical Support Organization WebSphere Commerce V5.5 Handbook Customization and Deployment Guide November 2003

SG24-6969-00

Note: Before using this information and the product it supports, read the information in “Notices” on page xxi.

First Edition (November 2003) This edition applies to IBM WebSphere Commerce V5.5, Business Edition on the Microsoft Windows 2000, IBM AIX, Sun Solaris, and IBM OS/400 platforms. In addition, this edition applies to IBM WebSphere Commerce Studio V5.5, Business Developers Edition for Microsoft Windows 2000. © Copyright International Business Machines Corporation 2003. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii The team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxvii Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxvii Part 1. Introduction to WebSphere Commerce V5.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Platform support and product packaging. . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.1 Supported platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.2 IBM WebSphere Commerce V5.5 product editions . . . . . . . . . . . . . . 5 1.1.3 IBM WebSphere Commerce Studio V5.5 product editions . . . . . . . . . 6 1.2 Features and benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.2.1 IBM WebSphere Commerce V5.5, Professional Edition . . . . . . . . . . . 8 1.2.2 IBM WebSphere Commerce V5.5, Business Edition . . . . . . . . . . . . 13 1.3 Target audience of this IBM Redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.3.1 Roles and skills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.3.2 Matching topics in this redbook to roles and skills . . . . . . . . . . . . . . 17 1.4 For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 1.4.1 IBM WebSphere Commerce product documentation . . . . . . . . . . . . 20 1.4.2 Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 1.4.3 IBM Redbooks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Chapter 2. Runtime architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 2.2 WebSphere Commerce software components . . . . . . . . . . . . . . . . . . . . . 30 2.2.1 Web server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 2.2.2 WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 2.2.3 Database Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 2.2.4 WebSphere Commerce Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 2.2.5 WebSphere Commerce Payments Server . . . . . . . . . . . . . . . . . . . . 32 2.2.6 Enablement software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 2.3 WebSphere Commerce Server subsystems . . . . . . . . . . . . . . . . . . . . . . . 34 2.3.1 Member subsystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 2.3.2 Catalog subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 2.3.3 Trading subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

© Copyright IBM Corp. 2003. All rights reserved.

iii

2.3.4 Order subsystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 2.3.5 Merchandising subsystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 2.3.6 Marketing subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 2.3.7 Inventory subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 2.3.8 Messaging subsystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 2.4 Runtime topology selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 2.4.1 Runtime topology selection criteria . . . . . . . . . . . . . . . . . . . . . . . . . . 41 2.4.2 WebSphere Commerce runtime topologies . . . . . . . . . . . . . . . . . . . 47 2.4.3 Topology mapping to implementation details . . . . . . . . . . . . . . . . . . 57 2.5 For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Chapter 3. Business and store models . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 3.1 Business and store models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 3.1.1 Direct sales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 3.1.2 Hosting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 3.1.3 Value chains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 3.2 Business model infrastructure and architecture . . . . . . . . . . . . . . . . . . . . 69 3.2.1 Organization structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 3.2.2 Access control model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 3.2.3 Business policy framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 3.3 Store architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 3.3.1 Store assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 3.3.2 Store architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 3.3.3 Store packaging and models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 3.3.4 Store data assets and architecture . . . . . . . . . . . . . . . . . . . . . . . . . . 86 3.3.5 Catalog data assets and concepts . . . . . . . . . . . . . . . . . . . . . . . . . . 91 3.3.6 Tools and store data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 3.3.7 Customize a store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 3.3.8 Publish a store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 3.4 For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Chapter 4. Programming model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 4.2 WebSphere Commerce Server framework . . . . . . . . . . . . . . . . . . . . . . . 112 4.2.1 Servlet engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 4.2.2 Protocol Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 4.2.3 Adapter manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 4.2.4 Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 4.2.5 Web controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 4.2.6 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 4.2.7 Entity beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 4.2.8 Data beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 4.2.9 Data Bean Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

iv

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

4.2.10 JavaServer Page (JSP) templates . . . . . . . . . . . . . . . . . . . . . . . . 119 4.2.11 WebSphere Commerce .xml configuration file . . . . . . 119 4.3 Application flow of an HTTP request . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 4.4 Design patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 4.4.1 Model-view-controller design pattern . . . . . . . . . . . . . . . . . . . . . . . 122 4.4.2 Command design pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 4.4.3 Display design pattern. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 4.5 Persistent object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 4.6 Access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 4.7 Customizing application assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 4.7.1 Asset types to customize and development tooling . . . . . . . . . . . . 128 4.7.2 Matching skills to customization needs . . . . . . . . . . . . . . . . . . . . . . 130 4.8 For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Chapter 5. Site and store administration . . . . . . . . . . . . . . . . . . . . . . . . . 133 5.1 Administration tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 5.1.1 WebSphere Commerce Configuration Manager . . . . . . . . . . . . . . . 134 5.1.2 WebSphere Commerce Administration Console. . . . . . . . . . . . . . . 139 5.1.3 WebSphere Commerce Accelerator . . . . . . . . . . . . . . . . . . . . . . . . 142 5.1.4 WebSphere Commerce Organization Administration Console . . . . 145 5.1.5 WebSphere Commerce Loader Package . . . . . . . . . . . . . . . . . . . . 147 5.1.6 WebSphere Commerce Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . 148 5.1.7 WebSphere Commerce Payments Console . . . . . . . . . . . . . . . . . . 149 5.1.8 WebSphere Application Server Administration Console . . . . . . . . . 150 5.1.9 DB2 Control Center. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 5.2 Key operational categories to manage . . . . . . . . . . . . . . . . . . . . . . . . . . 152 5.3 IT specialist roles and tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 5.3.1 System administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 5.3.2 Site administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 5.3.3 Store administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 5.3.4 Database administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 5.4 Line-of-business user roles and tools . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 5.4.1 Business relationship roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 5.4.2 Customer service roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 5.4.3 Marketing manager role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 5.4.4 Operational roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 5.4.5 Organizational management roles . . . . . . . . . . . . . . . . . . . . . . . . . 168 5.4.6 Product management and merchandising roles . . . . . . . . . . . . . . . 169 5.5 For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Part 2. Development guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Chapter 6. WebSphere Commerce site development methodology. . . . 173 6.1 Systematic development methodology . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Contents

v

6.2 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 6.2.1 Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 6.2.2 Work products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 6.2.3 Deliverable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 6.2.4 Customer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 6.2.5 Customer IT team . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 6.2.6 Project team . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 6.2.7 Project database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 6.2.8 Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 6.2.9 Strategy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 6.3 Development methodology: phase and life cycle . . . . . . . . . . . . . . . . . . 178 6.3.1 Core development phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 6.4 Using the methodology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 6.4.1 Customizing and adopting the methodology . . . . . . . . . . . . . . . . . . 182 6.4.2 New and transition sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 6.4.3 Project roles and skills requirements . . . . . . . . . . . . . . . . . . . . . . . 183 6.4.4 Structuring information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 6.4.5 Case studies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 6.5 Related methodology concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 6.5.1 IBM Method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 6.5.2 Rational Unified Process® (RUP®). . . . . . . . . . . . . . . . . . . . . . . . . 185 6.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Chapter 7. Development environment and build cycle . . . . . . . . . . . . . . 187 7.1 WebSphere Commerce Studio overview . . . . . . . . . . . . . . . . . . . . . . . . 188 7.1.1 WebSphere Commerce Studio workspace . . . . . . . . . . . . . . . . . . . 188 7.1.2 WebSphere Commerce Studio plug-ins . . . . . . . . . . . . . . . . . . . . . 198 7.1.3 Custom code packaging and incremental deployment . . . . . . . . . . 201 7.2 Team development environment overview . . . . . . . . . . . . . . . . . . . . . . . 202 7.2.1 Optimistic team model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 7.2.2 Ideal work flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 7.2.3 Source control management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 7.2.4 Defect tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 7.3 Build environment overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 7.3.1 Benefits of daily build and smoke tests . . . . . . . . . . . . . . . . . . . . . . 209 7.3.2 Concepts of daily build and smoke tests. . . . . . . . . . . . . . . . . . . . . 210 7.3.3 Build automation for daily builds and smoke tests . . . . . . . . . . . . . 212 7.4 Deployment overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 7.4.1 Development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 7.4.2 Test environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 7.4.3 Staging environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 7.4.4 Production environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 7.4.5 Practice deployment and create backup plan . . . . . . . . . . . . . . . . . 215

vi

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

7.4.6 Production debug vs development debugging . . . . . . . . . . . . . . . . 215 Chapter 8. Globalization guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 8.1 Introduction to globalization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 8.2 Globalization in WebSphere Commerce . . . . . . . . . . . . . . . . . . . . . . . . . 221 8.3 Cultural considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 8.3.1 Date and time formatting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 8.3.2 Currency and number formatting . . . . . . . . . . . . . . . . . . . . . . . . . . 229 8.3.3 Name and address formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 8.4 WebSphere Commerce application model . . . . . . . . . . . . . . . . . . . . . . . 237 8.4.1 Language table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 8.4.2 Introduction to encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 8.4.3 Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 8.4.4 WebSphere Commerce data model: input . . . . . . . . . . . . . . . . . . . 247 8.4.5 WebSphere Commerce data model: output . . . . . . . . . . . . . . . . . . 250 8.5 Globalized catalog content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 8.6 Globalized store design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 8.6.1 Globalized page framework: one template for stores/languages . . 253 8.6.2 Support for bi-directional languages . . . . . . . . . . . . . . . . . . . . . . . . 259 8.6.3 Understanding the localized store assets . . . . . . . . . . . . . . . . . . . . 263 8.6.4 Creating a new display format for WebSphere Commerce . . . . . . . 268 8.6.5 Adding a new currency to WebSphere Commerce . . . . . . . . . . . . . 270 8.6.6 How to add/delete a language/currency for a store archive . . . . . . 271 8.7 Globalized tools framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 8.8 Globalization in the messaging system . . . . . . . . . . . . . . . . . . . . . . . . . . 279 8.9 Globalization tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 8.9.1 Handling apostrophes and special characters . . . . . . . . . . . . . . . . 283 8.9.2 Using locale-dependent Cascading Style Sheets (CSS) . . . . . . . . 285 8.9.3 National language-enabled alert/confirm/prompt boxes . . . . . . . . . 285 8.9.4 Input field validation: UTF-8 Input validation . . . . . . . . . . . . . . . . . . 286 8.9.5 Submit NL command parameters using hidden forms . . . . . . . . . . 287 Part 3. ITSO B2B working example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 Chapter 9. Requirements analysis and solution design . . . . . . . . . . . . . 291 9.1 Business scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 9.2 Requirements analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 9.2.1 ITSO challenges and requirements. . . . . . . . . . . . . . . . . . . . . . . . . 296 9.2.2 Initial context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 9.2.3 System context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 9.2.4 Use case model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 9.3 Solution design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 9.3.1 Systems architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 9.3.2 Component model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Contents

vii

9.3.3 ITSO store navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 9.3.4 ITSO store catalog hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 9.3.5 ITSO store organizational hierarchy . . . . . . . . . . . . . . . . . . . . . . . . 317 Chapter 10. ITSO sample code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 10.1 Description of sample code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 10.2 Prepare DeployTool files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 10.2.1 Copy WebSphere Commerce files . . . . . . . . . . . . . . . . . . . . . . . . 321 10.2.2 Copy WebSphere Application Server files . . . . . . . . . . . . . . . . . . 322 10.2.3 Copy WebSphere Commerce Studio files. . . . . . . . . . . . . . . . . . . 322 Chapter 11. Implement a team development environment . . . . . . . . . . . 323 11.1 Team development environment scenario . . . . . . . . . . . . . . . . . . . . . . 324 11.2 Build and SCM node implementation . . . . . . . . . . . . . . . . . . . . . . . . . . 328 11.2.1 CVS overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 11.2.2 CVSNT Server implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 11.2.3 WebSphere Commerce Studio installation . . . . . . . . . . . . . . . . . . 336 11.2.4 Publish store archive within WebSphere Test Environment . . . . . 336 11.2.5 CVS client configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 11.3 Development node implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 11.3.1 WebSphere Commerce Studio installation . . . . . . . . . . . . . . . . . . 338 11.3.2 CVS client configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 11.4 Development Integration Test node implementation. . . . . . . . . . . . . . . 338 Chapter 12. Create a store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 12.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 12.2 Package and verify store archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 12.2.1 Back up workspace and databases . . . . . . . . . . . . . . . . . . . . . . . 344 12.2.2 Create the Packaging project . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 12.2.3 Package a store archive (SAR) . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 12.2.4 Publish the store archive (SAR) . . . . . . . . . . . . . . . . . . . . . . . . . . 350 12.2.5 Verify the store after publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 12.3 Import store assets into CVS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 12.3.1 Create a CVS module from the project . . . . . . . . . . . . . . . . . . . . . 351 12.3.2 Add the files to CVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 12.4 Required customization of basic store assets . . . . . . . . . . . . . . . . . . . . 354 12.4.1 Store directory and identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 12.4.2 Hardcoded references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 12.4.3 Store address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 12.4.4 Catalog data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 12.4.5 Store front-end assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 12.5 Further customization of basic store assets . . . . . . . . . . . . . . . . . . . . . 367 12.5.1 Default and supported currencies . . . . . . . . . . . . . . . . . . . . . . . . . 367 12.5.2 Default and supported locales. . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

viii

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

12.5.3 Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 12.5.4 Business accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 12.5.5 Contracts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 12.5.6 Taxes, shipping couriers and shipping prices . . . . . . . . . . . . . . . . 384 12.5.7 Payment information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 12.6 Publish the store archive to the workspace. . . . . . . . . . . . . . . . . . . . . . 384 12.6.1 Package the customized store archive . . . . . . . . . . . . . . . . . . . . . 385 12.6.2 Publish the customized store archive to runtime. . . . . . . . . . . . . . 385 12.6.3 Verify the customized store archive . . . . . . . . . . . . . . . . . . . . . . . 385 12.6.4 Publish the store archive to the workspace. . . . . . . . . . . . . . . . . . 385 12.6.5 Verify customized store in the WebSphere Test Environment . . . 387 12.7 Add the store front files to CVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 12.8 Set up additional team development nodes . . . . . . . . . . . . . . . . . . . . . 388 12.8.1 Turn off directory pruning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 12.8.2 Checking out the projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 12.8.3 Package and publish data-only store archive . . . . . . . . . . . . . . . . 392 Chapter 13. Customize a store: Price Watch example . . . . . . . . . . . . . . . 393 13.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 13.2 Solution design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 13.2.1 Use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 13.2.2 Solution overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 13.2.3 Solution limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 13.2.4 Data storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 13.2.5 Data access (entity bean) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 13.2.6 Controller commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 13.2.7 Task commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 13.2.8 Passing data to the JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 13.2.9 Price watch list page JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 13.2.10 E-mail template JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 13.2.11 Access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 13.3 Price Watch example pre-conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . 402 13.4 Configuring the e-mail transport and SMTP server . . . . . . . . . . . . . . . . 403 13.4.1 Setting up the James SMTP server . . . . . . . . . . . . . . . . . . . . . . . 403 13.4.2 Adding the new message type to the database . . . . . . . . . . . . . . 403 13.4.3 Configuring the e-mail transport . . . . . . . . . . . . . . . . . . . . . . . . . . 405 13.4.4 Configuring the e-mail message type . . . . . . . . . . . . . . . . . . . . . . 405 13.5 Creating the new database table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 13.6 Creating the new data access beans . . . . . . . . . . . . . . . . . . . . . . . . . . 408 13.6.1 Create the entity bean. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 13.6.2 Create the EJB/RDB mapping for the entity bean. . . . . . . . . . . . . 425 13.6.3 Create an access bean for the entity bean . . . . . . . . . . . . . . . . . . 428 13.6.4 Generate the deploy code and test the bean . . . . . . . . . . . . . . . . 429

Contents

ix

13.6.5 Update the bean with new FinderHelpers . . . . . . . . . . . . . . . . . . . 434 13.7 Creating the new commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 13.7.1 Create the command interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 13.7.2 Create the command implementation class . . . . . . . . . . . . . . . . . 439 13.7.3 Add the task commands to the workspace . . . . . . . . . . . . . . . . . . 449 13.7.4 Register the new command in the command registry . . . . . . . . . . 449 13.7.5 Create the PriceWatchListDisplayCmd command . . . . . . . . . . . . 450 13.7.6 Create the task commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 13.7.7 Create access control policies for the commands. . . . . . . . . . . . . 461 13.7.8 Enable component tracing in development environment . . . . . . . 463 13.8 Creating the new data bean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 13.8.1 Data bean types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 13.8.2 Further considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466 13.8.3 Creating the price watch data bean . . . . . . . . . . . . . . . . . . . . . . . 467 13.9 Creating the new JavaServer Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . 470 13.9.1 Globalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471 13.9.2 Creating the JSP file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472 13.9.3 Registering a new view for the price watch list page . . . . . . . . . . 480 13.9.4 Using an external editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 13.9.5 Changes to the item display page . . . . . . . . . . . . . . . . . . . . . . . . . 481 13.9.6 Changes to the site header page . . . . . . . . . . . . . . . . . . . . . . . . . 482 13.10 Creating the batch e-mail command . . . . . . . . . . . . . . . . . . . . . . . . . . 482 13.10.1 Create the command interface . . . . . . . . . . . . . . . . . . . . . . . . . . 483 13.10.2 Create the command implementation class . . . . . . . . . . . . . . . . 483 13.10.3 Import the data bean for the e-mail command . . . . . . . . . . . . . . 489 13.10.4 Register the new command in the command registry . . . . . . . . . 490 13.11 Importing the e-mail template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 13.11.1 Adding the JSP to your workspace . . . . . . . . . . . . . . . . . . . . . . . 491 13.11.2 JSP content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 13.11.3 Registering a new view for the e-mail template . . . . . . . . . . . . . 493 13.12 Configuring the scheduler to run the batch job . . . . . . . . . . . . . . . . . . 493 13.12.1 Make the command schedulable . . . . . . . . . . . . . . . . . . . . . . . . 494 13.12.2 Configure the scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 13.13 Testing the Price Watch example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 13.13.1 Testing the new functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 Chapter 14. Build and deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 14.1 Build and deployment overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506 14.2 Build procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507 14.2.1 Check out source from CVS to Build and SCM node . . . . . . . . . . 508 14.2.2 Modify store archive build script and unpack descriptor . . . . . . . . 508 14.2.3 Modify database SQL scripts and XML files . . . . . . . . . . . . . . . . . 510 14.2.4 Build application assets archive (JAR) . . . . . . . . . . . . . . . . . . . . . 514

x

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

14.2.5 Build store archive (SAR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516 14.2.6 Build verification test (BVT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516 14.2.7 Source configuration management (SCM) of build files . . . . . . . . 517 14.3 Deployment procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 14.3.1 Publish the store archive (SAR) . . . . . . . . . . . . . . . . . . . . . . . . . . 520 14.3.2 Deploy application assets archive (JAR). . . . . . . . . . . . . . . . . . . . 522 14.3.3 Load access control policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525 14.3.4 Configure e-mail for Price Watch . . . . . . . . . . . . . . . . . . . . . . . . . 525 14.3.5 Verify the runtime and store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 Chapter 15. Manage the ITSO store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 15.1 Product management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 15.1.1 Add a category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 15.1.2 Add a product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 15.2 Create organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 15.2.1 Organizations in ITSO store archive . . . . . . . . . . . . . . . . . . . . . . . 533 15.2.2 Create seller organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 15.2.3 Create a buyer organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 15.3 Create a business account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 15.3.1 Business accounts in ITSO store archive . . . . . . . . . . . . . . . . . . . 542 15.3.2 Create a business account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 15.4 Create a contract. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 15.4.1 Contracts in ITSO store archive . . . . . . . . . . . . . . . . . . . . . . . . . . 544 15.4.2 Create contract using the Accelerator . . . . . . . . . . . . . . . . . . . . . . 545 15.4.3 Activate contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 15.4.4 Verify the contract is enabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 Part 4. Runtime deployment scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 Chapter 16. Windows: Migrate a single-tier to a multi-tier . . . . . . . . . . . 553 16.1 Scenario overview and planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 16.1.1 Common reasons for migrating to multi-tiers . . . . . . . . . . . . . . . . 554 16.1.2 Migration scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555 16.1.3 Hardware and software perquisites. . . . . . . . . . . . . . . . . . . . . . . . 557 16.1.4 Hardware used in the ITSO runtime environment . . . . . . . . . . . . . 557 16.1.5 Software used in the ITSO runtime environment . . . . . . . . . . . . . 558 16.2 Single-tier implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 16.2.1 Windows installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560 16.2.2 WebSphere Commerce V5.5 installation . . . . . . . . . . . . . . . . . . . 561 16.2.3 DB2 UDB V8.1 Fix Pack 3 installation . . . . . . . . . . . . . . . . . . . . . 562 16.2.4 WebSphere Application Server V5 Fix Pack 1 installation . . . . . . 563 16.2.5 WebSphere Commerce V5.5.0.2 Fix Pack 2 installation . . . . . . . 569 16.2.6 WebSphere Commerce instance creation . . . . . . . . . . . . . . . . . . 571 16.2.7 WebSphere Commerce Payments instance creation . . . . . . . . . . 573

Contents

xi

16.2.8 Database backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 16.2.9 Start servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 16.2.10 Verify the runtime environment and store functionality . . . . . . . . 577 16.3 Add a remote Database Server node . . . . . . . . . . . . . . . . . . . . . . . . . . 582 16.3.1 Windows 2000 installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 16.3.2 Install DB2 V8.1 Enterprise Edition Server . . . . . . . . . . . . . . . . . . 582 16.3.3 DB2 UDB V8.1 Fix Pack 3 installation . . . . . . . . . . . . . . . . . . . . . 584 16.3.4 Backup and restore of databases . . . . . . . . . . . . . . . . . . . . . . . . . 584 16.3.5 Configure DB2 connectivity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 16.3.6 Verify the remote DB2 Server node configuration. . . . . . . . . . . . . 587 16.4 Add remote Web Server node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587 16.4.1 Review preconditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 16.4.2 Install IBM HTTP Server and WebSphere plug-in. . . . . . . . . . . . . 588 16.4.3 WebSphere Application Server V5 Fix Pack 1 installation . . . . . . 589 16.4.4 Configure IBM HTTP Server for SSL . . . . . . . . . . . . . . . . . . . . . . 590 16.4.5 Verify IBM HTTP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 16.4.6 IBM HTTP Administration (optional) . . . . . . . . . . . . . . . . . . . . . . . 594 16.4.7 Modify Web Server host name . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 16.4.8 Configure the Web server static content . . . . . . . . . . . . . . . . . . . . 597 16.4.9 Verify the remote Web Server configuration . . . . . . . . . . . . . . . . . 598 Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599 17.1 Scenario overview and planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 17.1.1 Scenario overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 17.1.2 Hardware and software prerequisites . . . . . . . . . . . . . . . . . . . . . . 601 17.1.3 Software used within the ITSO test environment . . . . . . . . . . . . . 602 17.1.4 Software installation paths and variables . . . . . . . . . . . . . . . . . . . 603 17.1.5 Hardware used within the ITSO test environment. . . . . . . . . . . . . 603 17.1.6 File system planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604 17.2 Solaris installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606 17.2.1 Network information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 17.2.2 Installing Solaris 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 17.2.3 Installing Solaris 8 maintenance update . . . . . . . . . . . . . . . . . . . . 607 17.2.4 Installing Solaris 8 recommended patches . . . . . . . . . . . . . . . . . . 608 17.3 Web Server node implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611 17.3.1 Pre-installation tasks for the iPlanet Web Server . . . . . . . . . . . . . 611 17.3.2 Installing the iPlanet Web Server . . . . . . . . . . . . . . . . . . . . . . . . . 612 17.3.3 Enabling SSL for the iPlanet Web Server . . . . . . . . . . . . . . . . . . . 615 17.3.4 Disabling the iPlanet servlet engine . . . . . . . . . . . . . . . . . . . . . . . 620 17.3.5 Verifying the Sun ONE Web Server installation . . . . . . . . . . . . . . 620 17.3.6 Installing the WebSphere plug-in . . . . . . . . . . . . . . . . . . . . . . . . . 621 17.3.7 Verifying the WebSphere plug-in . . . . . . . . . . . . . . . . . . . . . . . . . 622

xii

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

17.4 Database Server node implementation . . . . . . . . . . . . . . . . . . . . . . . . . 623 17.4.1 Oracle9i installation prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . 623 17.4.2 Installing Oracle9i Enterprise Edition (server installation) . . . . . . . 629 17.4.3 Preparing the database for WebSphere Commerce . . . . . . . . . . . 634 17.5 WebSphere Commerce node implementation . . . . . . . . . . . . . . . . . . . 639 17.5.1 Oracle9i client installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640 17.5.2 WebSphere Commerce installation. . . . . . . . . . . . . . . . . . . . . . . . 645 17.5.3 Create users and groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646 17.5.4 Installing the remaining WebSphere Commerce components . . . 647 17.5.5 WebSphere Commerce instance creation . . . . . . . . . . . . . . . . . . 650 17.5.6 WebSphere Commerce post-instance config . . . . . . . . . . . . . . . . 659 17.5.7 Creating a WebSphere Commerce Payment instance . . . . . . . . . 660 17.5.8 WebSphere Commerce payment post-instance config . . . . . . . . . 664 17.5.9 Start/stop the WebSphere Commerce instance . . . . . . . . . . . . . . 665 17.5.10 Regenerating Web server plug-in configurations . . . . . . . . . . . . 666 17.5.11 iPlanet Web Server configuration for WebSphere Commerce . . 667 17.6 Verify the runtime environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669 17.6.1 Publish a store archive (SAR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669 17.6.2 Configure Web server for static content . . . . . . . . . . . . . . . . . . . . 670 17.6.3 Compile the WebSphere Commerce store JSPs . . . . . . . . . . . . . 671 17.6.4 Launch store from Site Administration Console . . . . . . . . . . . . . . 671 17.6.5 Verify the sample store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672 Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server. . . . . . . . . 675 18.1 Scenario overview and planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676 18.1.1 Scenario overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676 18.1.2 Hardware and software prerequisites . . . . . . . . . . . . . . . . . . . . . . 677 18.1.3 Hardware used in the ITSO runtime environment . . . . . . . . . . . . . 677 18.1.4 Software used in the ITSO runtime environment . . . . . . . . . . . . . 678 18.1.5 Software installation paths and variables . . . . . . . . . . . . . . . . . . . 679 18.1.6 Installation approaches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679 18.2 AIX installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680 18.2.1 Network planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680 18.2.2 AIX installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681 18.2.3 File system planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681 18.2.4 Netscape 7 Web browser (optional) . . . . . . . . . . . . . . . . . . . . . . . 682 18.2.5 AIX software prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682 18.2.6 Disable wsmserver on port 9090. . . . . . . . . . . . . . . . . . . . . . . . . . 684 18.3 Web Server node implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685 18.3.1 AIX installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685 18.3.2 Installing IBM HTTP Server and WebSphere plug-in . . . . . . . . . . 686 18.3.3 Configure the IBM HTTP Server . . . . . . . . . . . . . . . . . . . . . . . . . . 687 18.3.4 Install WebSphere Application Server V5 fixes . . . . . . . . . . . . . . . 691

Contents

xiii

18.4 DB2 Server node implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691 18.4.1 AIX installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691 18.4.2 Install DB2 UDB V8.1 Enterprise Server Edition . . . . . . . . . . . . . . 692 18.4.3 Install DB2 UDB V8.1 Fix Pack 1 . . . . . . . . . . . . . . . . . . . . . . . . . 695 18.4.4 Create a file system for DB2 databases (optional) . . . . . . . . . . . . 696 18.5 WebSphere Commerce Payments node implementation . . . . . . . . . . . 698 18.5.1 AIX installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699 18.5.2 Install DB2 UDB V8.1 Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699 18.5.3 Configure and verify the DB2 client and server. . . . . . . . . . . . . . . 701 18.5.4 Create the non-root user(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702 18.5.5 Install WebSphere Commerce Payments software. . . . . . . . . . . . 704 18.5.6 Verify the WebSphere Commerce Payments installation . . . . . . . 710 18.5.7 Install WebSphere Application Server V5 fixes . . . . . . . . . . . . . . . 710 18.5.8 Verify the WebSphere Application Server . . . . . . . . . . . . . . . . . . . 713 18.5.9 Modify the owner and file permissions of the httpd.conf . . . . . . . . 715 18.5.10 Create the WebSphere Commerce Payments instance . . . . . . . 716 18.5.11 Configure the IBM HTTP Server . . . . . . . . . . . . . . . . . . . . . . . . . 719 18.5.12 Verify WebSphere Commerce Payments instance . . . . . . . . . . . 721 18.6 WebSphere Commerce node implementation . . . . . . . . . . . . . . . . . . . 723 18.6.1 AIX installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724 18.6.2 Install DB2 UDB V8.1 Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724 18.6.3 Configure and verify DB2 client and server. . . . . . . . . . . . . . . . . . 725 18.6.4 Create the non-root user(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725 18.6.5 Install WebSphere Commerce and supporting software . . . . . . . . 726 18.6.6 Verify the WebSphere Commerce installation . . . . . . . . . . . . . . . 731 18.6.7 Install WebSphere Application Server V5 fixes . . . . . . . . . . . . . . . 731 18.6.8 Verify the WebSphere Administration Console . . . . . . . . . . . . . . . 731 18.6.9 Configure Web server WebSphere plug-in (optional) . . . . . . . . . . 731 18.6.10 WebSphere Commerce instance creation . . . . . . . . . . . . . . . . . 733 18.6.11 Verify the WebSphere Commerce instance creation . . . . . . . . . 738 18.6.12 Configure the remote Web server for WebSphere Commerce . . 741 18.6.13 Compile WebSphere Commerce tools JSPs . . . . . . . . . . . . . . . 743 18.6.14 Verify the WebSphere Commerce administration tools . . . . . . . 744 18.6.15 Configure and verify WebSphere Commerce Payments . . . . . . 746 18.7 Verify the runtime environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747 18.7.1 Back up the databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748 18.7.2 Publish a sample store archive (SAR) . . . . . . . . . . . . . . . . . . . . . 749 18.7.3 Configure the Web server static content . . . . . . . . . . . . . . . . . . . . 750 18.7.4 Compiling WebSphere Commerce store JSPs (optional) . . . . . . . 751 18.7.5 Verify WebSphere Commerce administration tools . . . . . . . . . . . 751 18.7.6 Verify functionality of sample store . . . . . . . . . . . . . . . . . . . . . . . . 751 18.7.7 Restore databases (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752 18.7.8 Remove the published sample store (optional) . . . . . . . . . . . . . . . 752

xiv

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

18.8 Additional configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752 Chapter 19. OS/400: Two-tier remote database server . . . . . . . . . . . . . . 755 19.1 Scenario overview and planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756 19.1.1 Skill requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756 19.1.2 Hardware and software requirements . . . . . . . . . . . . . . . . . . . . . . 756 19.1.3 Hardware used in the ITSO runtime environment . . . . . . . . . . . . . 756 19.1.4 Software used in the ITSO runtime environment . . . . . . . . . . . . . 757 19.1.5 Software installation paths and root directories . . . . . . . . . . . . . . 758 19.2 Pre-installation steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758 19.2.1 Verify user profiles required during the installation . . . . . . . . . . . . 759 19.2.2 Create a remote database entry . . . . . . . . . . . . . . . . . . . . . . . . . . 759 19.2.3 Create an instance user profile . . . . . . . . . . . . . . . . . . . . . . . . . . . 759 19.3 WebSphere Commerce installation process . . . . . . . . . . . . . . . . . . . . . 760 19.3.1 Custom installation process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760 19.3.2 Verify a custom installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761 19.3.3 WebSphere Application Server installation log . . . . . . . . . . . . . . . 762 19.3.4 WebSphere Commerce installation log . . . . . . . . . . . . . . . . . . . . . 763 19.4 PTF installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763 19.5 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765 19.5.1 Considerations before creating the instance . . . . . . . . . . . . . . . . . 765 19.5.2 Updating SQL packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766 19.5.3 Installing the Configuration Manager client . . . . . . . . . . . . . . . . . . 768 19.5.4 Starting the Configuration Manager . . . . . . . . . . . . . . . . . . . . . . . 769 19.6 Instance creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771 19.6.1 Instance creation requirements when using a remote database. . 771 19.6.2 Create a WebSphere Commerce instance . . . . . . . . . . . . . . . . . . 772 19.6.3 Verifying the instance creation . . . . . . . . . . . . . . . . . . . . . . . . . . . 773 19.6.4 Completing the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775 19.6.5 Create a WebSphere Commerce Payments instance . . . . . . . . . 775 19.6.6 Completing the configuration for the Payments instance . . . . . . . 776 19.6.7 Verifying the instance creation . . . . . . . . . . . . . . . . . . . . . . . . . . . 777 19.7 Enabling SSL for IBM HTTP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 777 19.8 Start the application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777 19.8.1 Start the WebSphere Commerce Payment instance . . . . . . . . . . 778 19.8.2 Stop the WebSphere Commerce Payments instance . . . . . . . . . . 779 19.8.3 Start the WebSphere Commerce instance . . . . . . . . . . . . . . . . . . 779 19.8.4 Stop the WebSphere Commerce instance . . . . . . . . . . . . . . . . . . 779 19.9 Publish a store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780 19.9.1 Pre-compile the JSPs files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781 19.10 Back up WebSphere Commerce and components . . . . . . . . . . . . . . . 781 19.11 Uninstall WebSphere Commerce . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783 19.11.1 Uninstall WebSphere Commerce . . . . . . . . . . . . . . . . . . . . . . . . 783

Contents

xv

19.11.2 Uninstalling Configuration Manager client. . . . . . . . . . . . . . . . . . 784 19.11.3 Uninstalling WebSphere Application Server . . . . . . . . . . . . . . . . 784 Part 5. Integration and customization scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785 Chapter 20. Commerce analytics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787 20.1 Commerce analytics overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788 20.1.1 Business drivers for commerce analytics . . . . . . . . . . . . . . . . . . . 788 20.1.2 WebSphere Commerce analytical features. . . . . . . . . . . . . . . . . . 789 20.1.3 Reports overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792 20.1.4 Analytics to action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795 20.1.5 WebSphere Commerce Analyzer architecture . . . . . . . . . . . . . . . 798 20.1.6 Where to find more information. . . . . . . . . . . . . . . . . . . . . . . . . . . 800 20.2 WebSphere Commerce Analyzer integration . . . . . . . . . . . . . . . . . . . . 801 20.2.1 WebSphere Commerce Analyzer integration scenario overview . 802 20.2.2 WebSphere Commerce node configuration . . . . . . . . . . . . . . . . . 804 20.2.3 WebSphere Commerce Analyzer node installation. . . . . . . . . . . . 809 20.2.4 WebSphere Commerce Analyzer pre-configuration . . . . . . . . . . . 817 20.2.5 WebSphere Commerce Analyzer database configuration . . . . . . 819 20.2.6 Prepare promote steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837 20.2.7 WebSphere Commerce Analyzer business options configuration 852 20.2.8 Post-configuration steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859 20.2.9 Accessing out-of-box Accelerator reports . . . . . . . . . . . . . . . . . . . 864 20.2.10 Change passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867 20.3 Create customized reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868 20.3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868 20.3.2 Before customizing a new report. . . . . . . . . . . . . . . . . . . . . . . . . . 869 20.3.3 Creating input and output JSP files . . . . . . . . . . . . . . . . . . . . . . . . 871 20.3.4 Defining the report with XML files . . . . . . . . . . . . . . . . . . . . . . . . . 873 20.3.5 Add the XML files to the resources.xml file . . . . . . . . . . . . . . . . . . 875 20.3.6 Add the customized report to a page in Accelerator . . . . . . . . . . . 876 20.3.7 Modifying the .properties files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877 20.3.8 Adding view commands to the database . . . . . . . . . . . . . . . . . . . 879 20.3.9 Modify SQL and test the customized report . . . . . . . . . . . . . . . . . 880 20.3.10 Adding access control to the customized report . . . . . . . . . . . . . 882 Chapter 21. Messaging integration with MQ and e-mail . . . . . . . . . . . . . 883 21.1 Messaging architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884 21.1.1 Leveraging WebSphere Application Server messaging . . . . . . . . 885 21.1.2 Inbound messaging system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889 21.1.3 Outbound messaging system . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900 21.1.4 Predefined inbound and outbound messages. . . . . . . . . . . . . . . . 906 21.2 WebSphere MQ installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911 21.2.1 WebSphere MQ installation scenarios . . . . . . . . . . . . . . . . . . . . . 912

xvi

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

21.2.2 WebSphere MQ installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914 21.2.3 WebSphere MQ verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 21.2.4 WebSphere MQ CSD installation . . . . . . . . . . . . . . . . . . . . . . . . . 916 21.3 WebSphere MQ configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916 21.3.1 Create the MQ queue manager . . . . . . . . . . . . . . . . . . . . . . . . . . 916 21.3.2 Create MQ queues for WebSphere Commerce . . . . . . . . . . . . . . 919 21.4 WebSphere JCA-JMS configuration for MQ . . . . . . . . . . . . . . . . . . . . . 920 21.4.1 Add Windows user ID to mqm group . . . . . . . . . . . . . . . . . . . . . . 921 21.4.2 Configure JCA-JMS: WebSphere Application Server . . . . . . . . . . 921 21.4.3 Verify MQ_INSTALL_Root environment variable . . . . . . . . . . . . . 927 21.4.4 Enable tracing for message components . . . . . . . . . . . . . . . . . . . 927 21.4.5 Verify the WebSphere MQ configuration. . . . . . . . . . . . . . . . . . . . 928 21.4.6 Configure JCA-JMS: WebSphere Studio Application Developer . 929 21.5 WebSphere Commerce configuration for MQ . . . . . . . . . . . . . . . . . . . . 932 21.5.1 WebSphere Commerce configuration for MQ . . . . . . . . . . . . . . . . 933 21.5.2 WebSphere Commerce Studio configuration for MQ . . . . . . . . . . 935 21.6 Scenario: add new inbound message for MQ . . . . . . . . . . . . . . . . . . . . 936 21.6.1 Solution prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937 21.6.2 Prepare UserRegistrationAdd controller command. . . . . . . . . . . . 938 21.6.3 Update the template map file user_template.xml . . . . . . . . . . . . . 938 21.6.4 Create a new DTD file for inbound XML message . . . . . . . . . . . . 942 21.6.5 Update .xml to include new DTD . . . . . . . . . . . . . . . . . 945 21.6.6 Create inbound XML message . . . . . . . . . . . . . . . . . . . . . . . . . . . 946 21.6.7 Verify new inbound XML message . . . . . . . . . . . . . . . . . . . . . . . . 948 21.7 Scenario: e-mail notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950 21.7.1 Java Apache Mail Enterprise Server (James) configuration . . . . . 950 21.7.2 Enable the e-mail transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954 21.7.3 Configure the e-mail transport. . . . . . . . . . . . . . . . . . . . . . . . . . . . 955 21.7.4 Configure the e-mail message type . . . . . . . . . . . . . . . . . . . . . . . 955 21.7.5 Verify e-mail notification for password reset . . . . . . . . . . . . . . . . . 957 Part 6. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959 Appendix A. AIX tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961 Common tasks and commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962 AIX performance monitoring tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965 Starting and stopping TCP/IP daemons . . . . . . . . . . . . . . . . . . . . . . . . . . 966 Shut down AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966 List AIX file systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966 Directory list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966 Adding additional IP addresses to an interface. . . . . . . . . . . . . . . . . . . . . 967 Installing OpenSSH on AIX 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967 Appendix B. Solaris tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969

Contents

xvii

Solaris 8 installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970 Solaris 8 pre-installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970 Solaris 8 installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971 Solaris 8 interactive installation and configuration . . . . . . . . . . . . . . . . . . 973 Installing software on Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974 Solaris 8 post-install configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977 Solaris 8 maintenance update installation. . . . . . . . . . . . . . . . . . . . . . . . . 978 Solaris 8 recommended patches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980 Common Solaris tasks and commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982 Where to find information about Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986 Appendix C. DB2 tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987 DB2 backup and restore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988 Back up a DB2 database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988 Back up DB2 database via Control Center . . . . . . . . . . . . . . . . . . . . . . . . 988 Restore a DB2 database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990 DB2 tasks using smitty on AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990 Create a logical volume. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990 Create an AIX journal file system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991 Allocate storage for a file system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992 Create users and groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992 DB2 commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993 Create a volume group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993 Create a logical volume. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993 Create a journal file system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993 Allocate space to a file system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993 Mount a file system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993 Create a database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994 List databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994 Drop a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994 Catalog a TCP/IP node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994 Attach to a remote node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994 Catalog a remote database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995 Connect to a remote database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995 Disconnect from a remote database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995 Appendix D. Oracle tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997 Oracle9i commands and tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998 Oracle9i server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998 Oracle9i listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999 Oracle utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000 Testing Oracle connectivity using JDBCTEST . . . . . . . . . . . . . . . . . . . . . . . 1001 Oracle backup and restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002

xviii

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Important Oracle files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002 Log files and trace files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002 Oracle configuration files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003 Verifying user creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003 Cleaning database after deleting an instance . . . . . . . . . . . . . . . . . . . . . . . 1004 Where to find more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004 Appendix E. WebSphere Commerce Studio implementation . . . . . . . . 1005 WebSphere Commerce Studio installation. . . . . . . . . . . . . . . . . . . . . . . . . . 1006 Windows 2000 installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007 Install WebSphere Commerce Studio V5.5. . . . . . . . . . . . . . . . . . . . . . . 1008 Install WebSphere Studio Application Developer V5.0.1 PTF . . . . . . . . 1010 Install WebSphere Test Environment V5.0.1 . . . . . . . . . . . . . . . . . . . . . 1012 Install WebSphere Studio Application Developer V5.0.1 Interim Fix 3 . . 1013 Install DB2 UDB V8.1 Fix Pack 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014 Install WebSphere Commerce Studio Toolkit V5.5.0.2 Fix Pack . . . . . . 1016 WebSphere Commerce Studio configuration . . . . . . . . . . . . . . . . . . . . . . . . 1021 Required post-install configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021 Optional post-install configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025 Configure the default Web browser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027 Set default XML editor to optimize performance . . . . . . . . . . . . . . . . . . . 1027 WebSphere Commerce Studio verification . . . . . . . . . . . . . . . . . . . . . . . . . 1028 Start the WebSphere Commerce Payments Server . . . . . . . . . . . . . . . . 1028 Start the WebSphere Commerce Server . . . . . . . . . . . . . . . . . . . . . . . . 1028 Appendix F. Additional material. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029 Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029 Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030 System requirements for downloading the Web material . . . . . . . . . . . . 1030 Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031 IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031 Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032 Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033 How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035

Contents

xix

xx

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces.

© Copyright IBM Corp. 2003. All rights reserved.

xxi

Trademarks The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both: ™ ^™ ibm.com® iSeries™ pSeries™ xSeries® z/OS® zSeries® AIX 5L™ AIX® AS/400® ClearCase® Cloudscape™ Domino™ DB2 Extenders™

DB2 Universal Database™ DB2® Informix® Intelligent Miner™ IBM Payment Server™ IBM® Lotus Notes® Lotus® MQSeries® Net.Data® Notes® OS/400® PowerPC 604™ PowerPC® POWER3™

QuickPlace® Rational Unified Process® Rational® Redbooks™ Redbooks (logo) ™ RS/6000® RUP® S/390® Sametime® Tivoli® TCS® VisualAge® WebSphere® XDE™

The following terms are trademarks of other companies: Intel is a trademark of Intel Corporation in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Other company, product, and service names may be trademarks or service marks of others.

xxii

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Preface This IBM® Redbook is a customization and deployment guide for IBM WebSphere Commerce V5.5. The redbook provides IT architects, IT specialists, and developers with the critical knowledge to design, develop, deploy and manage a WebSphere® Commerce runtime environment and store. Part 1, Introduction to WebSphere Commerce, provides an overview of the WebSphere Commerce runtime architecture, programming model, business and store models, and administration of a site and store. Part 2, Design and development guidelines, provides IT architects and developers with design and development guidelines for an e-commerce development methodology, development environment, build cycle, and globalization. Part 3, ITSO B2B working example, includes business requirements analysis and solution design, team development environment, store creation, store customization, build and deployment, and store administration. Part 4, Runtime deployment scenarios, provides IT specialists procedures for implementing advanced multi-tiered runtime scenarios on Windows, Solaris, AIX® and OS/400®. The scenarios highlight best practices and advanced multi-tier configurations such as remote Web server, database and payment nodes. Part 5, Integration deployment scenarios, provides IT architects, IT specialists and developers with the knowledge required to implement and customize integrated solutions including WebSphere Commerce Analyzer, MQ and e-mail. Part 6, Appendixes, includes tips on AIX, Solaris, DB2®, Oracle and WebSphere Commerce Studio implementation.

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.

© Copyright IBM Corp. 2003. All rights reserved.

xxiii

The IBM Redbook team left to right (Hernan Cunico, Abhishek Singh, Nicolai Nielsen, Sean Zhu, Steve Insley, John Ganci, center - Ryan Karchner)

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, WebSphere Application Server, pervasive computing, Linux and Java™ programming. Hernan Cunico is a Senior I/T Specialist at IBM Global Services in Argentina. He has nine years of experience in system administration and the e-business field. He has worked at IBM for five years. His areas of expertise include networking, Internet security, e-commerce, iSeries™ and cross-platform e-business and e-commerce solutions. He has participated in several residencies producing Redbooks related to WebSphere Commerce.

xxiv

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Daniel Dunn is a WebSphere Commerce Application Development Architect, an I/T Architect, in IBM Software Group, Canada. He has been in the field of software development for e-commerce applications since 1996. He holds a degree in Computer Science and Economics from the University of Toronto, Canada. His areas of expertise include WebSphere application architecture and development, WebSphere Studio team development environment, relational database design and management, multi-platform system integration, and software automation. Steve Insley is a Senior IT Consultant in the United Kingdom. He has six years of experience in the field of application development, system integration and consulting for e-commerce and e-business solutions. He holds a degree in Computer Science from the University of Warwick, England. His areas of expertise include application design, J2EE, WebSphere Application Server, and WebSphere Commerce. He has worked on several major WebSphere Commerce customer engagements in the UK. Steve has recently moved from IBM UK to work for etc (European Technology Consultants Ltd). Ryan Karchner is an undergraduate student at Penn State University. He is currently working toward a BS degree in Information Sciences and Technology and a minor in Business/Liberal Arts. His main area of interest is the integration of information technology with financial investment, business management, and business analytics. He joined the IBM International Technical Support Organization as a Co-op Pre-professional IT Specialist. Emad Muhanna is is the Globalization Architect responsible for the WebSphere Commerce products in IBM Software Group, Toronto Lab. He has five years of experience in the areas of software globalization and e-commerce solutions. He holds a degree in Computer Engineering from McGill University in Montreal, Canada. His areas of expertise include software globalization, Java internationalization and localization, automation of localization testing, J2EE technology, WebSphere Commerce, and WebSphere Application Server. He has presented at several conferences about software globalization development techniques, globalization verification testing, mock translation, and automation of localization and translation verification testing. Nicolai Nielsen is an I/T Specialist with IBM Global Services, Denmark. He has eight years of experience in the field of consulting, application development and systems integration. He holds a Masters degree in Engineering from the Technical University of Denmark. Over the last two years, he has worked on several WebSphere Commerce V5.1 and V5.4 projects. Abhishek Singh is an Advisory IT Specialist in IBM Global Services, Australia. He has five years of experience in the Telecommunications and Government sectors in the areas of e-business and e-commerce solutions, performing application architecture, designing, development, and systems integration. He

Preface

xxv

holds a Bachelor's degree in Computer Systems Engineering from the University of South Australia, and is now a PhD candidate in Computer Systems Engineering from the same university. His areas of expertise include systems integration, application architecture and development, technical team leadership, and in particular WebSphere Commerce, WebSphere Application Server, and WebSphere MQ products Sean Zhu is a Software Engineer in the IBM Software Group. He currently provides support for IBM WebSphere Commerce at the IBM Developer Relations Technical Support Center. He has five years of experience working on e-commerce projects utilizing object-oriented technologies and middleware tools. He is certified in WebSphere Commerce and DB2 and very familiar with e-business solutions design and development using products such as Rational® and WebSphere. He holds an MSc degree in Information Systems and an MBA from Arizona State University. Thanks to the following people for their contributions to this project: Zamil Janmohamed, IBM Canada Sanjoy Banik, Gen-i Limited in New Zealand Valerie Westcott, IBM Canada Keri-Anne Lounsbury, IBM Canada Erin Heximer, IBM Canada Eric Koeck, IBM Canada Kirsten Rutherford, IBM Canada Eric Poulin, IBM Canada Robert Werkama, IBM US Fen Wang, IBM Canada Khalyl Khan, IBM Canada Walfrey Ng, IBM Canada Erik Neathery, IBM Canada Gavin Singh, IBM Canada Ross McKegney, IBM Canada Patrick Yau, IBM Canada Abdul-Kader Farra, IBM Canada Norm Smith, IBM US Juha Nevalainen, IBM Finland Terry Hudson, IBM UK Adrian Warman, IBM UK Brian Lima, IBM Canada David Yuan, IBM Canada Sanjeev Sharma, IBM Canada Scott Ripley, IBM Canada Eugene Lam, IBM Canada Bill Holtshouser, IBM US

xxvi

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Mike Chang, IBM Canada Roke Jung, IBM Canada Jose Ortiz, IBM US Jacob Vandergoot, IBM Canada Kar-Ho Chan, IBM Canada Ibrahim Meru, IBM Canada Mikito Hirota, IBM Japan Donna Sutarno, IBM Canada Ronald van Loon, IBM Netherlands

Become a published author Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You'll team with IBM technical professionals, Business Partners and/or customers. Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you'll develop a network of contacts in IBM development labs, and increase your productivity and marketability. Find out more about the residency program, browse the residency index, and apply online at: ibm.com/redbooks/residencies.html

Comments welcome Your comments are important to us! We want our 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: [email protected]


Mail your comments to: IBM Corporation, International Technical Support Organization Dept. HZ8 Building 662 P.O. Box 12195 Research Triangle Park, NC 27709-2195

Preface

xxvii

xxviii

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Part 1

Part

1

Introduction to WebSphere Commerce V5.5 This part of the redbook provides an overview of the product, describes the WebSphere Commerce runtime architecture, business and store models, programming model, and tools and tasks for managing a site and store.

© Copyright IBM Corp. 2003. All rights reserved.

1

2

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

1

Chapter 1.

Introduction Just for a moment, imagine that you have been asked to implement your company’s e-commerce Web site. You have two fundamental choices: build the commerce system from scratch or buy a pre-packaged e-commerce product. You can wake up now; your nightmare is over. Recognizing the e-commerce needs of small, medium, and large companies, IBM has developed several editions of IBM WebSphere Commerce V5.5, including Express Edition, Professional Edition, and Business Edition. Each of the product editions includes a secure and scalable runtime architecture, a flexible J2EE programming model, and sample stores to speed application development. This chapter includes the following topics:





Platform support and product packaging Features and benefits Target audience of this IBM Redbook For more information

© Copyright IBM Corp. 2003. All rights reserved.

3

1.1 Platform support and product packaging The IBM WebSphere Commerce product is packaged into separate integrated suites of software for runtime deployment (WebSphere Commerce) and development tooling (WebSphere Commerce Studio). IBM WebSphere Commerce V5.5 is available in three editions: Business, Professional and Express. The Business Edition includes all features of the Professional Edition and additional functionality specific to B2B, hosting and value chains involving multiple enterprises or parties. The runtime deployment packages are available on many operating systems, including Microsoft® Windows® 2000, IBM AIX, Sun Solaris, IBM OS/400, Linux on Intel® based systems, and Linux on IBM ^ iSeries, pSeries™, and zSeries®. While writing this redbook, we focused on the Business Edition, since it is a superset of the other editions. Note: The Express Edition was not available at the time of writing. Therefore, this redbook does not include information on this edition. The development tooling product packaging is available in three editions: Business Developer, Professional Developer and Express Developer. The development product editions are only available for Microsoft Windows 2000. While writing this redbook, we focused on the IBM WebSphere Commerce Studio V5.5, Business Developer Edition.

1.1.1 Supported platforms IBM WebSphere Commerce V5.5 is supported on the following platforms:






4

Microsoft Windows 2000 Server + Service Pack 3 or higher IBM AIX 5.1 + Maintenance Level 2 (ML) or higher Sun Solaris 8 + Maintenance Update 7 (MU) + Recommended 7 IBM OS/400 Version 5 Release 2 (V5R2M0) Linux: – Linux on Intel-based systems (x86) • Red Hat Enterprise Linux AS V2.1 • SuSE Linux Enterprise Server V8 – Linux on IBM ^™ iSeries – Linux on IBM ^ pSeries – Linux on IBM ^ zSeries and S/390®

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

1.1.2 IBM WebSphere Commerce V5.5 product editions Table 1-1 provides a summary of the software included with the Business and Professional Editions by platform. For more detailed information on the WebSphere Commerce supported software, refer to the Fundamentals Guide, IBM WebSphere Commerce V5.5 and the product installation guides for the desired platforms. Table 1-1 Software stack summary for IBM WebSphere Commerce V5.5 Software

Windows

AIX

Solaris

OS/400

Linux

IBM WebSphere Commerce * WebSphere Commerce Server * WebSphere Commerce Payments (cassettes for Paymentech, VisaNet, BankServArch, CustomOffline, OfflineCard) * Blaze Rules Server and Innovator runtime 4.5.5 * Recommendations Engine powered by LikeMinds 5.5 Note: The Business Edition includes all features of the Professional Edition plus additional functionality for B2B, hosting, and value chains (supply and demand).

5.5

5.5

5.5

5.5

5.5

IBM WebSphere Application Server

5.0

5.0

5.0

5.0

5.0.2 (FP2)

IBM WebSphere Application Server, Network Deployment Edition

5.0

5.0

5.0

5.0

5.0.2 (FP2)

IBM DB2 Universal Database™, Enterprise Server Edition

8.1 + FP1

8.1 + FP1

8.1 + FP1

Built-in

8.1 + FP2

IBM DB2 Extenders™

8.1 + FP1

8.1 + FP1

8.1 + FP1

N/A

Built-in

IBM DB2 Intelligent Miner™ for Data

8.1

8.1

8.1

8.1

8.1

IBM HTTP Server

1.3.26

1.3.26

1.3.26

Built-in

1.3.26.2

IBM Developer Kit, Java Technology Edition

1.3.1 SR3W

1.3.1 SR3W

N/A

Built-in

1.3.1 SR3W

Java 2 SDK, Enterprise Edition

N/A

N/A

1.3.1 FP5

N/A

N/A

IBM Directory Server

4.1.1

4.1.1

4.1.1

N/A

5.1

IBM WebSphere Commerce Analyzer

5.5

N/A

N/A

N/A

N/A

Chapter 1. Introduction

5

Software

Windows

AIX

Solaris

OS/400

Linux

Lotus® Sametime®

3.0

3.0

3.0

3.0

3.0

Lotus QuickPlace® Note: only included with Business Edition

3.0

3.0

3.0

3.0

3.0

Alternate Web Server The IBM HTTP Server V1.3.26 is included with WebSphere Commerce for all platforms. WebSphere Commerce supports the following alternate Web Servers on the listed platform (not included):
Microsoft Windows 2000: – Microsoft Internet Information Server V5.0 – Sun ONE Web Server, Enterprise Edition V6.0 (formerly iPlanet)
Sun Solaris – Sun ONE Web Server, Enterprise Edition V6.0 (formerly iPlanet)

Alternate databases IBM DB2 Universal Database V8.1, Enterprise Server Edition + Fix Pack 1 (Fix Pack 2 on Linux) is supported and included with WebSphere Commerce on all platforms (built-in database for OS/400). WebSphere Commerce also supports Oracle9i Database Release 2 (9.2.0.1), Enterprise Edition or Standard Edition (not included).

1.1.3 IBM WebSphere Commerce Studio V5.5 product editions IBM WebSphere Commerce Studio V5.5 is available in three editions: Business Developer, Professional Developer, and Express Developer. These correspond to the WebSphere Commerce runtime editions (Business, Professional and Express). WebSphere Commerce Studio consolidates all development tools into a single environment for developing front-end and back-end (business logic) application assets as well as a development test environment with debug support. Table 1-2 on page 7 provides a summary of the software included with IBM WebSphere Commerce Studio V5.5. For more detailed information on the WebSphere Commerce Studio supported software, refer to the Fundamentals Guide, IBM WebSphere Commerce V5.5 and Installation Guide, IBM WebSphere Commerce Studio V5.5 product guides.

6

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Table 1-2 Software stack summary for WebSphere Commerce Studio V5.5 Software

Version

IBM WebSphere Studio Application Developer * WebSphere Test Environment

5.0.0.2

IBM WebSphere Commerce Toolkit for WebSphere Studio

5.5

IBM WebSphere Commerce Configuration Manager plug-in for WebSphere Studio

5.5

IBM WebSphere Commerce Online Help plug-in for WebSphere Studio

5.5

IBM DB2 Universal Database, Enterprise Server Edition

8.1 + FP1

IBM WebSphere Commerce Note:
Professional Developer Edition includes WebSphere Commerce V5.5, Professional Edition
Business Developer Edition includes WebSphere Commerce V5.5, Business Edition

5.5

Note: Oracle9i Database software is also supported by WebSphere Commerce Studio V5.5 (not included).

Java levels supported in WebSphere Commerce Table 1-3 provides a summary of the Java levels supported in IBM WebSphere Commerce V5.5 versus IBM WebSphere Commerce V5.4. Table 1-3 Java level summary for WebSphere Commerce Java technology

WebSphere Commerce V5.5

WebSphere Commerce V5.4

Java 2 Enterprise Edition (J2EE)

1.3

1.2

Enterprise JavaBeans (EJB)

1.1

1.1 (1.0 + VisualAge® for Java wrapper for 1.1)

Java Servlet

2.3

2.2

JavaServer Pages (JSP)

1.2

1.1

JDK

1.3.1

* 1.3.1 for WebSphere Application Server V4 * 1.2.2 for VisualAge for Java

Chapter 1. Introduction

7

1.2 Features and benefits This section provides a listing of features and benefits of IBM WebSphere Commerce V5.5 for the Professional and Business Editions.

1.2.1 IBM WebSphere Commerce V5.5, Professional Edition IBM WebSphere Commerce V5.5, Professional Edition provides enhancements over previous versions and supports the following enterprise capabilities:
Consumer direct store model (B2C) Enhancements include additional promotion rules, sophisticated search capabilities and enhanced store configuration services to improve the online buying experience of customers.
Integration enhancements There are a number of integration solutions that address the enterprise needs through a mix of prepackaged and add-on capabilities. Key enhancements include: – IBM WebSphere Business Integration support: Provide a new transport mechanism used by subsystems to interact with external systems through WebSphere Business Integration collaborations. This is done by sending synchronous messages and taking advantage of the existing WebSphere Commerce messaging system. – Support end-to-end integration with SAP through WebSphere Business Integration Reference Application. – WebSphere Commerce Messaging system: Existing WebSphere Commerce Common Connector Framework (CCF) is enhanced to support Java 2 Enterprise Edition Connector Architecture (J2EE/CA) standard including JavaMail Connector, JMS Connector and File Connector. – MQ Transport Adapter: Upgrades to support J2EE/JCA compliant.
Marketing and merchandising The marketing and merchandising features provided enhanced targeted e-mail campaign, advanced rules-based discounts or promotions and improved tooling for merchandising associations (cross-sells and up-sells). – E-mail support:

8

•

E-mail delivery of news and promotions

•

Manage e-mail activities at store level instead of site level and view statistics on e-mail activities

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

– Marketing campaigns •

Support e-mail as a campaign delivery mechanism

•

Time sharing of multiple initiatives on same spot

– Advanced discounts and promotions •

Rules-based discount supports complex promotion models such as shipping discount and buy one, get one free

•

Supports advanced scheduler for upcoming promotions

– Coupons enhancements •

Allow guest shoppers to capture and redeem eCoupons and manage eCoupons using a coupon wallet

•

Allow merchandiser to create eCoupons promotion, and manage eCoupon promotion and modify eCoupon promotion terms

– Cross-sells and up-sells •

Enhancements in merchandising and campaigns tooling allow target product to be recommended at runtime based on the content of the current page, shopping cart and previous purchases

•

Predefined merchandising associations in catalog


Live Help/Customer Care Collaboration The integrated live help Customer Care function is integrated out-of-the-box and is based on Lotus Sametime instant messaging. This feature allows your partners, suppliers, and customers to have real-time communication with you for decision-making and negotiations. Your business decisions and processes can be streamlined with this collaboration tool, making it easier and faster to do business. Enhancements include: – Support for multiple queues and queue management – Support monitoring of customized customer attributes in a store – Support customer requests to be routed into queues
Catalog Management tooling The Catalog Management tooling simplifies product content management through the following enhancements: – Content Creation and Management tooling: Allows user to perform product and editorial content creation and management task quickly and effectively. – Bulk File Aggregation: Enhanced bulk file management tools provide out-of-the-box support for importing content from trading partners and bulk file import support to the Loader Package.

Chapter 1. Introduction

9


Product Advisor enhancements Product Advisor creates an interactive online product catalog that provides customers with different ways of finding what they want, called shopping metaphors. Enhancements include: – Creating a search space: Two search methods are supported. Separate search space would perform optimized parametric search with focus on categories, and base search space would search the WebSphere Commerce database that is created during instance configuration. – Creating the Product Exploration metaphor: Allows a customer to view products that have matching parameter values within a given category of products. – Creating the Product Comparison metaphor: Allows a customer to view the related products side by side for similarities and differences. – Creating a Guided Sell metaphor: Provides a series of multiple choice questions to guide customers to refine their searches to a smaller list of products.
Analytics and Business Intelligence WebSphere Commerce Analyzer is packaged with WebSphere Commerce. Commerce Analyzer enables WebSphere Commerce customers to analyze information related to their customers' e-commerce activities. WebSphere Commerce customers can improve the effectiveness of their company's marketing campaigns and promotions. WebSphere Commerce Analyzer significantly extends analytical capabilities provided by the Entry version, which was packaged with Version 5.4. In this release, WebSphere Commerce Analyzer provides the following features: – A Business Intelligence (BI) infrastructure integrated with the following IBM Data Management programs: • •

IBM DB2 Universal Database V8.1, Enterprise Server Edition IBM DB2 Intelligent Miner for Data V8.1

– A documented and customizable datamart. – Extraction, transformation, move and load (ETML) functions to extract and transform WebSphere Commerce operational data sources using aggregation and summarizing techniques. This now includes support for coupons, discounts and multiple stores. – Data mining models, which enable the analyzing of complex data characterizations, relationships, and projections with regard to customer segmentation. – End-user Web analytical reporting enablement for the WebSphere Commerce Reporting Framework.

10

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


Operational reports Operational reports, based on WebSphere Commerce Reporting Framework, are generated in real time. These reports can provide useful information about the sales, traffic, and customers from your site. The following types of reports are accessible through the system: – – – – – – – – – – –

Category Product Order Item Detail Order Item Fulfillment Order Status Region Region (all stores) Site Overview Store Activity Store Performance Evaluation Usage


Tivoli® Web Site Analyzer The Tivoli Web Site Analyzer V4.2 helps turn raw Web data into valuable e-business intelligence. It provides you with a clear picture of the overall health and integrity of your e-business infrastructure supporting business impact management. By capturing, analyzing, storing, and reporting on Web site usage, health, integrity and site content, Tivoli Web Site Analyzer provides essential metrics on visitor interactions with the site and the site's overall performance. Its multi-channel data collection consolidates globally distributed Web server logs, including logs generated in a z/OS® environment into a single open data warehouse. In addition, Web page information can be captured dynamically via Tivoli Web Site Analyzer's Web Tracker function providing a more real-time view. Using these functions, Tivoli Web Site Analyzer can create detailed reports and views on Web server activity, visitor statistics, and visitor behavior. Integrating the critical end-user experience dimension provides the benefit of deeper, more complex analysis.
WebSphere Commerce Payments WebSphere Commerce Payments provides a secure electronic payment process for Internet merchants through a single, unified interface. Based on open standards-based technology, WebSphere Commerce Payments works with plug-ins called payment cassettes to support multiple payment protocols. Support for existing cassettes include OfflineCard, CustomOffline VisaNet, and BankServACH cassettes. Enhancements include: – Support for a new cassette for Paymentech including connectivity is added

Chapter 1. Introduction

11

– Add support for SSL connectivity to VirtualNet system via VisaNet cassette – Add support for SSL and leased line connectivity to the FHMS system via the VisaNet cassette – Automatic restart of Commerce Payments without manual intervention to support 24x7 operation and recoverability
System management WebSphere Commerce provides the following enhancements for systems management: – Administration: System management options can be separately installed by way of the WebSphere Commerce custom install. – Organization Administration Console: This tool can be used by an administrator in the customer organization as well as by the site administrator to manage all customers. – Problem Determination: The WebSphere Commerce Problem Determination tool automatically validates the correctness of WebSphere Commerce installation and instance creation and JRAS, the WebSphere Commerce logging infrastructure consolidated with WebSphere Application Server to allow for use of common tooling and to correlate logging data throughout the system. – Performance Monitoring: Integrated use of WebSphere Application Server PMI (Performance Monitoring Interface) enabling WebSphere Commerce data to be viewed through the Tivoli Performance Viewer.
Installation WebSphere Commerce V5.5 improves the ease of installation and configuration to ensure a system is installed correctly and prerequisites are available. Enhancements include: – WebSphere Commerce and all its associated software can now be installed through the WebSphere Commerce InstallShield based on InstallShield for Multiplatform Edition (ISMPE). – Express Install allows you to quickly install WebSphere Commerce and create a WebSphere Commerce instance with minimal user interaction. – Configuration Manger is enhanced to support remote machine configurations, and the Password Manager Tool lets you manage WebSphere Commerce passwords from a single location. – A new Problem Determination (PD) Tool: a Java-based tool that analyzes the up-and-running logs and generates reports for troubleshooting problems.

12

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


Web services You can allow WebSphere Commerce to be the service provider by enabling its business functions as Web services that can be accessed by external systems. You can also allow WebSphere Commerce to be the service requester by enabling it to invoke Web services hosted by external systems.

1.2.2 IBM WebSphere Commerce V5.5, Business Edition IBM WebSphere Commerce V5.5, Business Edition supports all of the enterprise capabilities of IBM WebSphere Commerce V5.5, Professional Edition, plus the following Business-to-Business (B2B) benefits:
Channel Management IBM WebSphere Commerce V5.5, Business Edition provides new channel management capabilities to support integrated value chains for transactions involving multiple parties. This enables enterprises to optimize the flow of products, goods, services, and information through the value chain, while streamlining the management and administrative aspects of orchestrating these relationships. The key capabilities to support both demand and Supply Chains include: – Business relationship management between channel partners and suppliers – Product information management for channel partners and suppliers – Distributed order management – Channel inventory monitoring – Order hand-off and order status tracking – Co-marketing with channel partners and suppliers – Multi-party Request-For-Quote (RFQ) and Request-For-Proposal (RFP) – Private marketplace and partner hosting – Secured sign-on and access control for channel partners and suppliers – Self-provisioning for channel partners and suppliers – Collaboration with channel partners and suppliers
B2B direct store enhancements (ToolTech)
Hosting New to IBM WebSphere Commerce V5.5, Business Edition is the ability to support hosting of business partners in the value chain model. WebSphere Commerce also supports the hosting of merchants or other business by an Internet Service Provider (ISP) or other hosting provider. A hosting hub is a Web site, usually owned by an ISP, where merchants can build a store for shoppers. Merchant stores can have catalogs filtered from a reseller hub catalog, or have their own catalog.

Chapter 1. Introduction

13


Value chains New to IBM WebSphere Commerce V5.5, Business Edition is the ability to support value chains. Value chains support transactions involving multiple enterprises or parties. Products, goods, services, or information are delivered through parties of the value chain from producers to end users. A value chain also has relationship and administrative aspects, which allow for managing the relationship of parties in the value chain. Two new value chains are as follows: – Demand Chains Demand Chains support both indirect sales and direct sales channels. A Demand Chain is composed of the enterprises that sell a business’s goods or services. For example, a Demand Chain may be composed of buyers who initiate the sales transaction, the resellers who sell the manufacturer’s goods, and the manufacturer who creates the goods. – Supply Chains A Supply Chain is composed of the enterprises that provide services to a business. WebSphere Commerce provides the architectural infrastructure to support Supply Chains that take the form of a private marketplace. A private marketplace provides a forum for vendors to offer their wares for sale. Buyers enter this forum and after browsing through the available options, select the appropriate goods or services.
Request-For-Quote (RFQ) Request for Quote (RFQ), only available in the Business Edition, provides the capability for an RFQ to solicit quotes for a specific set of goods and services between buyer and supplier. Enhancements include: – New RFQ closing rules, for example an RFQ will be closed if a specific number of responses are received – Provide targeted RFQ support, attachments to RFQ, made-to-orders items in RFQ, and multi-round RFQ support – Allow creation of RFQ without setting up the interest list, add items from the requisition list, grouping of the products in RFQ, substitution of products in response, and specify a fulfillment center in the response
Online Buyer/Seller Collaboration (Collaborative Workspaces) Available only in Business Edition, it provides a contract draft and proposal discussion template, based on Lotus QuickPlace. This template is integrated into the business-to-business store model included with the software. A seller company's sales or account manager can create a draft contract, share this contract with buyers in the buying organization, and also discuss the contract using a threaded discussion on Lotus Domino™. Additional features also

14

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

allow online buyers and sellers to make decisions about the quantity and content of orders, delivery dates, promotions, and designs of new products.

1.3 Target audience of this IBM Redbook As is the nature of a handbook, this redbook is multi-purpose: it includes architecture, design, development, integration, deployment and administration topics. The target audience of the redbook can be best matched by role to the topic of interest within the redbook.

1.3.1 Roles and skills There are a number of common roles that are needed for a team to execute a WebSphere Commerce project during the development life cycle. In this section, we define the following key roles and skills to be used as a cross-reference with the topics of interest within the redbook:











Project manager IT architect/technical lead WebSphere Commerce site administrator WebSphere Commerce store administrator Database schema owner (creation/migration expert) Database administrator (DBA) Java programmer Web developer Tester Line-of-business (LOB) user

Project manager The project manager is responsible for managing and leading the project team throughout all phases of the project and also acts as a contact point to interact with the customer. The project manager should have a general understanding of the WebSphere Commerce product and be familiar with the product architecture.

IT architect/technical lead The IT architect looks after the overall project technical architecture/design, quality assurance of the solution, knowledge transfer to customers, and mentoring to the project technical team members. The architect should have WebSphere Commerce architecture and design skills. Based upon project scope and complexity, one or more WebSphere Commerce architects can work to create detailed project technical designs. The work effort can be divided based on common WebSphere Commerce subsystems, such as Catalog, Member,

Chapter 1. Introduction

15

Order, and communication with back-end or legacy systems. The technical design will be developed with the assistance of the lead developer.

WebSphere Commerce site administrator The WebSphere Commerce site administrator installs, configures, and maintains WebSphere Commerce 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 (creating and assigning members to the appropriate role), manages the Web site, monitors performance, and manages load balancing tasks. The site administrator may also be responsible for establishing and maintaining several server configurations for different stages of development such as testing, staging, and production. This role also handles critical system backups and resolves performance problems. For very large sites, some of the installation and configuration task may be performed by the system administrator.

WebSphere Commerce store administrator The WebSphere Commerce store administrator manages the store archive publishing, changes to taxes, shipping and managing store operations. The store administrator may be a lead on the store development team, and is the only role on the team with the authority to publish a store archive (except for the site administrator). In larger IT shops, this may be a designated person on the deployment or operations team.

Database schema owner (creation/migration expert) The WebSphere Commerce V5.5 database schema contains over 600 tables with numerous columns. It is critical that someone on the development team be very familiar with the WebSphere Commerce database schema for the development implementation and/or migration. In addition, the database owner is often responsible for managing the WebSphere Commerce XML data files that are used to populate the WebSphere Commerce instance database with catalog data, store and site data.

Database administrator (DBA) The database creation or migration activity role could also be performed by the DBA. The DBA is responsible for the creation and/or migration of the WebSphere Commerce instance database and ongoing database operations.

Java programmer The WebSphere Commerce programmer is responsible for the Java programming of the application assets of the site. The WebSphere Commerce architect/technical lead can also participate in implementing the new or transitioned site. The WebSphere Commerce programmer must have in-depth

16

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

knowledge of the WebSphere Commerce framework, programming and store models. In addition, they must have a strong background in J2EE programming and development tooling. The focus of the Java programmer will be on developing WebSphere Commerce commands (servlets) and EJBs.

Web developer The Web developer will focus on the front-end assets such as JavaServer Pages (JSPs), HTML and management of product images within the display pages. The Web developer is also known as a Web designer.

Tester There are many types of tests, such as unit test, functional verification test (FVT), system verification test (SVT), integration test, and customer acceptance test (CAT). The test lead is responsible for developing and executing a test plan for quality assurance. The members of the test team should be well versed in the product architecture, features of the site, and operational usage to simulate the transactions of a customer and a line-of-business user.

Line-of-business (LOB) user The line-of-business (LOB) users are typically responsible for managing the operations of the site. They can be marketing users where they are responsible for promoting the Web site to customers, managing the data needs for catalog management, and customer service-related tasks. Within WebSphere Commerce, there are many predefined roles that can be assigned to LOB users. The WebSphere Commerce administration tools can be configured to allow access only to specific functions within the tools by user role assigned to the user logged into the tool.

1.3.2 Matching topics in this redbook to roles and skills The topic set in this WebSphere Commerce V5.5 Handbook is diverse. Table 1-4 on page 18 provides a summary of the topics in this redbook, by part and chapter, aligning them with the defined roles and skills.

Chapter 1. Introduction

17

Table 1-4 Matching redbook topics to roles and skills Part

Chapter

Primary

Secondary

Part 1, “Introduction to WebSphere Commerce V5.5” Ch 1, ”Introduction”

All roles

Ch 2, ”Runtime architecture”

All roles

Ch 3, ”Business and store models”

All roles

Ch 4, ”Programming model”

IT architect Java programmer

Web developer Site administrator

Ch 5, ”Site and store administration”

Site administrator Store administrator LOB DBA Tester

Project manager IT architect Java developer Web developer

Ch 6, ”WebSphere Commerce site development methodology”

IT architect Java programmer Web developer

Project manager Site administrator Store administrator

Ch 7, ”Development environment and build cycle”

Java programmer Web developer

IT architect Site administrator Store administrator

Ch 8, ”Globalization guidelines”

IT architect Java programmer Web developer

Site administrator Store administrator

Part 2, “Development guidelines”

18

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Part

Chapter

Primary

Secondary

Ch 9, ”Requirements analysis and solution design”

IT architect

Project manager

Ch 10, ”ITSO sample code”

IT architect Java programmer Web developer Site administrator

Project manager

Ch 11, ”Implement a team development environment”

Java programmer Web developer

Site administrator IT architect

Ch 12, ”Create a store”

Web developer

IT architect Java developer Store administrator

Ch 13, ”Customize a store: Price Watch example”

Java programmer

IT architect Web developer

Ch 14, ”Build and deployment”

Java programmer Site administrator Web developer Store administrator

IT architect Tester

Ch 15, ”Manage the ITSO store”

Site administrator Store administrator LOB

IT architect Web developer Java programmer

Ch 16, ”Windows: Migrate a single-tier to a multi-tier”

Site administrator

IT architect DBA Tester

Ch 17, ”Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server”

Site administrator

IT architect DBA Tester

Ch 18, ”AIX: Three-tier using DB2 and IBM HTTP Server”

Site administrator

IT architect DBA Tester

Ch 19, ”OS/400: Two-tier remote database server”

Site administrator

IT architect DBA Tester

Part 3, “ITSO B2B working example”

Part 4, “Runtime deployment scenarios”

Chapter 1. Introduction

19

Part

Chapter

Primary

Secondary

Ch 20, ”Commerce analytics”

Site administrator Store administrator LOB Web developer

IT architect DBA Schema owner Tester

Ch 21, ”Messaging integration with MQ and e-mail”

Site administrator Java programmer

IT architect Store administrator Tester

Ax A, “AIX tips”

Site administrator

DBA Tester

Ax B, “Solaris tips”

Site administrator

DBA Tester

Ax C, “DB2 tips”

Site administrator DBA Schema owner

Tester

Ax D, “Oracle tips”

Site administrator DBA Schema owner

Tester

Ax E, “WebSphere Commerce Studio implementation”

Java programmer Web developer

Site administrator IT architect

Ax F, “Additional material” (sample code)

Java programmer Web developer

IT architect Tester

Part 5, “Integration and customization scenarios”

Part 6, “Appendixes”

1.4 For more information There is a vast amount of information available on WebSphere Commerce and related topics, such as WebSphere Application Server, WebSphere Studio Application Developer, and DB2. Sometimes the key to solving a problem is knowing where to find the necessary information. This section highlights the key product documentation, Web sites and IBM Redbooks.

1.4.1 IBM WebSphere Commerce product documentation Even if you are a big fan of IBM Redbooks, you should be aware that there is a vast amount of knowledge available only in the product documentation. The

20

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

product documentation PDFs and online help are updated periodically and can be downloaded from the WebSphere Commerce Technical Library found at:
IBM WebSphere Commerce V5.5, Business Edition http://www.ibm.com/software/genservers/commerce/wcbe/library/lit-tech-gener al.html


IBM WebSphere Commerce V5.5, Professional Edition http://www.ibm.com/software/genservers/commerce/wcpe/library/lit-tech-gener al.html

We have categorized the product documentation as follows:
Readme files for WebSphere Commerce and WebSphere Commerce Studio It is very important that you review the contents of the Readme files.
Online information – WebSphere Commerce online information The online information is installable with the WebSphere Commerce runtime or can be downloaded and viewed from a Web browser. It is very useful when looking for information by search topic, role, and task. – WebSphere Commerce Studio online information The online information is installable with the WebSphere Commerce Studio or can be downloaded and accessed from a Web browser. It is very useful when looking for information by search topic.
Overview – What’s New in IBM WebSphere Commerce V5.5 – Fundamentals Guide, IBM WebSphere Commerce V5.5
Runtime environment installation and configuration The runtime environment installation and configuration guides are listed by platform: – Microsoft Windows • •

Quick Beginnings Guide for Windows 2000, IBM WebSphere Commerce V5.5 Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000

– UNIX® (IBM AIX and SUN Solaris) • • •

Quick Beginnings Guide for AIX, IBM WebSphere Commerce V5.5 Quick Beginnings Guide for Solaris, IBM WebSphere Commerce V5.5 Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems

Chapter 1. Introduction

21

– IBM OS/400 • •

Quick Beginnings Guide for OS/400, IBM WebSphere Commerce V5.5 Installation Guide, IBM WebSphere Commerce V5.5 for OS/400

– Linux • •

Quick Beginnings Guide for Linux, IBM WebSphere Commerce V5.5 Installation Guide, IBM WebSphere Commerce V5.5 for Linux

– Additional Software Guide, IBM WebSphere Commerce V5.5 (common for all platforms)
Development environment installation and configuration – Installation Guide, IBM WebSphere Commerce Studio V5.5
Migration guides The migration guides are listed by the version to migrate from and by platform.
Integration – WebSphere Commerce Analyzer •

Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5

•

Datamart Reference, IBM WebSphere Commerce Analyzer V5.5

•

Technical Reference, IBM WebSphere Commerce Analyzer V5.5

– WebSphere Commerce Payments •

Payments Programming Guide and Reference, IBM WebSphere Commerce V5.5

•

Payments Cassette for Paymentech Supplement, IBM WebSphere Commerce V5.5

•

Payments Cassette for BankServACH Supplement, IBM WebSphere Commerce V5.5

•

Payments Cassette for VisaNet Supplement, IBM WebSphere Commerce V5.5

•

Payments Offline Cassette Supplement, IBM WebSphere Commerce V5.5

•

Payments Custom Offline Cassette Supplement, IBM WebSphere Commerce V5.5


Store development and programming – Sample Store Guide, IBM WebSphere Commerce V5.5 – Store Development Guide, IBM WebSphere Commerce V5.5 – Programming Guide and Tutorials, IBM WebSphere Commerce V5.5

22

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

– Web Services Guide, IBM WebSphere Commerce V5.5
Administration – Administration Guide, IBM WebSphere Commerce V5.5 – Security Guide, IBM WebSphere Commerce V5.5

1.4.2 Web sites This section lists Web sites where you can find additional information on WebSphere Commerce and related topics:
IBM WebSphere Commerce V5.5, Business Edition – Home page http://www.ibm.com/software/genservers/commerce/wcbe/index.html

– Technical Library http://www.ibm.com/software/genservers/commerce/wcbe/library/lit-tech-ge neral.html

– Support http://www.ibm.com/software/genservers/commerce/wcbe/support/


IBM WebSphere Commerce V5.5, Professional Edition – Home page http://www.ibm.com/software/genservers/commerce/wcpe/index.html

– Technical Library http://www.ibm.com/software/genservers/commerce/wcpe/library/lit-tech-ge neral.html

– Support http://www.ibm.com/software/genservers/commerce/wcpe/support/


IBM WebSphere Commerce Zone (development information) http://www.software.ibm.com/wsdd/zones/commerce/


IBM Services for IBM WebSphere Commerce Software http://www.ibm.com/software/genservers/commerce/services/


How to Buy IBM WebSphere Commerce http://www.ibm.com/software/swprod/swprod.nsf/(BuildHTBPage)?OpenAgent&DocI D=BMAL-5KSR6N


IBM Redbooks http://www.ibm.com/redbooks

Chapter 1. Introduction

23

1.4.3 IBM Redbooks IBM Redbooks are developed and published by IBM's International Technical Support Organization (ITSO). We develop and deliver skills, technical know-how, and materials to technical professionals of IBM, Business Partners, and customers, and to the marketplace generally. The ITSO teams with IBM Divisions and Business Partners in the process of developing IBM Redbooks, Redpapers, hints & tips, training, and other materials. The ITSO is part of the IBM Global Technical Support organization within IBM Global Sales and Distribution. The ITSO's value-add information products address product, platform, and solution perspectives. They explore integration, implementation, and operation of realistic customer scenarios. IBM Redbooks and Redpapers can be downloaded as PDFs at: http://www.ibm.com/redbooks

If you are interested in participating in creating an IBM Redbook, Redpaper or workshop, click the Residency link on the IBM Redbooks Web site.

WebSphere Commerce Redbooks We recommend the following IBM Redbooks for WebSphere Commerce:
WebSphere Commerce V5.5 Handbook, Customization and Deployment Guide, SG24-6969
WebSphere Commerce V5.5 Capacity Planning, SG24-6304 (expected publish date 12/2003)
WebSphere Digital Media V5.5 Solutions Guide, SG24-6085 (expected publish date 2/2004)
Best Practices and Tooling for Creating IBM WebSphere Commerce Sites, REDP3616
WebSphere Commerce V5.4 Catalog Design and Content Management, SG24-6885
WebSphere Commerce Portal V5.4, Using WebSphere Commerce V5.4 and WebSphere Portal V4.2, SG24-6890

WebSphere Redbooks We recommend the following IBM Redbooks for WebSphere Application Server V5 and WebSphere Studio Application Developer V5:
IBM WebSphere Application Server V5.0 Systems Management and Configuration: WebSphere Handbook Series, SG24-6195

24

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


WebSphere V5.0 Applications: Ensuring High Performance and Scalability, SG24-6198
IBM WebSphere V5.0 Security WebSphere Handbook Series, SG24-6573
WebSphere Studio Application Developer Version 5 Programming Guide, SG24-6957

Other Redbooks The following Redbooks may be useful for specific integration topics with WebSphere Commerce and supporting software:
Enhance Your Business Applications: Simple Integration of Advanced Data Mining Functions, SG24-6879
DB2 UDB/WebSphere Performance Tuning Guide, SG24-6417
Patterns: Custom Designs for Domino & WebSphere Integration, SG24-6903
IBM Certification Study Guide - pSeries AIX System Administration, SG24-6191
IBM HTTP Server (powered by Apache) for iSeries, SG24-6716
Enterprise Business Portals II with IBM Tivoli Access Manager, SG24-6885
Measuring e-business Web Usage, Performance, and Availability, SG24-6931

Chapter 1. Introduction

25

26

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

2

Chapter 2.

Runtime architecture The objective of this chapter is to provide IT architects, IT specialists, developers and project managers with the fundamental knowledge of the WebSphere Commerce V5.5 runtime architecture to make informed decisions when designing or implementing an e-commerce solution. The terms runtime architecture, systems architecture, and runtime environment are synonymous in the context of this redbook. The chapter includes the following topics:






Overview WebSphere Commerce software components WebSphere Commerce Server subsystems Runtime topology selection For more information

© Copyright IBM Corp. 2003. All rights reserved.

27

2.1 Overview This section identifies the key components of the WebSphere Commerce runtime architecture. We have categorized the components for the WebSphere Commerce Server as follows (see Figure 2-1 on page 29):
WebSphere Commerce software components We have listed the primary software components for WebSphere Commerce. There are many additional software components ncluded in the IBM WebSphere Commerce V5.5 product packaging that have not been listed here but that can be integrated with WebSphere Commerce. – – – – – –

Web server WebSphere Application Server Database Server WebSphere Commerce Server WebSphere Commerce Payments Server Enablement software (optional software components)


WebSphere Commerce Server subsystems The subsystems run within the WebSphere Commerce enterprise application on the WebSphere Commerce Server, and provide the infrastructure to support the features used by the administration tooling and stores. – – – – – – – –

Member subsystem Catalog subsystem Trading subsystem Order subsystem Merchandising subsystem Marketing subsystem Inventory subsystem Messaging subsystem


Common server runtime (framework) The common server runtime provides a framework in which the commerce applications are deployed and executed.
Business interaction engine The subsystems and server runtime operate within an interaction engine that provides all of the components with the necessary business context. These are governed by the contextual frameworks such as policies, entitlement, stores, personalization, and globalization.
Administration tools The administration tools are used to configure and manage the WebSphere Commerce site and store operations.

28

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

– – – – –

WebSphere Commerce Configuration Manager WebSphere Commerce Administration Console WebSphere Commerce Accelerator WebSphere Commerce Organization Administration Console WebSphere Commerce Payments Administration Console

Information for each of the listed administration tools can be found in Chapter 5, “Site and store administration” on page 133.

Administration Console Commerce Accelerator Organization Administration Console

WebSphere Application Server WebSphere Commerce Payments Server WebSphere Commerce Server Administration tools Administration Console

Configuration Tools

Policies

Stores

Entitlement

Personalization

Globalization

Common Server Runtime

WebSphere Commerce instance database

Subsystems Member Subsystem

Trading Subsystem

Catalog Subsystem

Marketing Subsystem

Merchandizing Subsystem

Order Subsystem

Inventory Subsystem

File e-mail

ICS

WebSphere Commerce .xml

HTTP

Configuration Manager Server

WebSphere Commerce Payments database

Messaging Subsystem

MQ

Configuration Manager (client)

Accelerator

Business Interaction Engine

Development Tools WebSphere Commerce Studio

Organization Administration Console

Commerce

Database Server

WC Payments Administration Console

WebSphere Commerce node Web Server + WebSphere plug-in

Web Browser Administration Tools

Transport adapters Figure 2-1 WebSphere Commerce Server runtime components

Chapter 2. Runtime architecture

29

2.2 WebSphere Commerce software components As described in 1.1, “Platform support and product packaging” on page 4, there are many software components included with IBM WebSphere Commerce V5.5. In this section, we will limit our discussion to the following software components of the WebSphere Commerce runtime architecture:






Web server WebSphere Application Server Database Server WebSphere Commerce Server WebSphere Commerce Payments Server Note: The WebSphere Commerce node architecture depicted in Figure 2-1 on page 29 shows a single-tier configuration. The software components listed in this section can be distributed on separate nodes for scalability and security reasons. For more detailed information on runtime configurations, refer to 2.4, “Runtime topology selection” on page 41.

2.2.1 Web server The Web server can be installed on the WebSphere Commerce node or a remote node, which can be optionally clustered for load balancing using the WebSphere Application Server V5, Network Deployment Edition Edge components. Regardless of whether the Web server is local or remote, it must be configured to use the WebSphere Application Server plug-in. There are several supported Web server plug-ins. The IBM HTTP Server and plug-in are found on the WebSphere Application Server CD included with WebSphere Commerce. The majority of the WebSphere Commerce tooling and store application assets are J2EE components (JSPs, servlets, EJBs, etc.) that run on the application server located on the WebSphere Commerce node. There are some static HTML pages and images found in the WebSphere Commerce tools and stores that can be served by the Web server. Incoming HTTP requests from Web browser clients are received by the Web server and WebSphere plug-in. The WebSphere plug-in, via the use of the plugin-cfg.xml file, redirects requests to applications on the WebSphere Application Server on the WebSphere Commerce node. In the event that you want to set up a remote Web server, you must manually configure the WebSphere Application Server virtual host aliases and regenerate the WebSphere plugin-cfg.xml file on the WebSphere Commerce node. The updated plugin-cfg.xml file must then be manually copied to the remote Web server. The Web server host name must be updated in the WebSphere

30

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Commerce instance and WebSphere Commerce Payments instance via the Configuration Manager. In addition, static application assets that are to be served by the Web server (HTML, images) must also be manually copied to the remote Web server. Once the remote Web server has reloaded the plugin-cfg.xml file and the WebSphere Application Server has been restarted to reflect the configuration changes, the remote Web server host name can be used by the Web browser client to access the WebSphere Commerce tools and stores. For more information on implementing a remote Web server, refer to 16.4, “Add remote Web Server node” on page 587. For information on alternative supported Web servers by platform, refer to “Alternate Web Server” on page 6.

2.2.2 WebSphere Application Server The WebSphere Commerce Server leverages the J2EE technologies provided by the WebSphere Application Server such as JSPs, servlets (WebSphere Commerce commands), EJBs, XML, Web Services, security, MQ embedded messaging, etc. IBM WebSphere Commerce V5.5 includes the IBM WebSphere Application Server V5 base edition and Network Deployment Edition. The base edition is suitable for single-tier, two-tier and three-tier runtime configurations. When multiple WebSphere Application Servers are needed for scalability, such as horizontal application clustering, then the Network Deployment Edition is needed.

2.2.3 Database Server IBM DB2 Universal Database V8.1, Enterprise Server Edition is included with WebSphere Commerce V5.5. In addition, Oracle9i (9.2.0.1) Enterprise Server and Standard Edition are supported (not included). The Database Server is used for the WebSphere Commerce instance database and the WebSphere Commerce Payments database. The WebSphere Commerce instance database is used for store configuration data such as taxes, shipping, customer profile information, and the product catalog. There are over 600 tables and numerous columns built into the WebSphere Commerce V5.5 schema. The WebSphere Commerce Payments database is used for payment configuration, such as accounts, payment types, cassettes and payment transaction data.

Chapter 2. Runtime architecture

31

The database server software can be installed on the same node as WebSphere Commerce or on a remote Database Server node. For more information on implementing a remote Database Server node, refer to 16.3, “Add a remote Database Server node” on page 582.

2.2.4 WebSphere Commerce Server The WebSphere Commerce Server is a WebSphere enterprise application, which runs on its own application server within the WebSphere Application Server. The WebSphere Commerce application software is installed via the WebSphere Commerce Installer. After installation, WebSphere Commerce must be configured using the Configuration Manager. The Configuration Manager is used to create the WebSphere Commerce instance. During instance creation, an application server for the WebSphere Commerce Server and the enterprise application is deployed. For most runtime topologies, the configuration of the WebSphere Application Server is performed for the user via the WebSphere Commerce Configuration Manager. When adding a remote Web server, remote WebSphere Commerce Payments node, and clustering using the WebSphere Application Server Network Deployment Edition, some manual configuration is needed.

2.2.5 WebSphere Commerce Payments Server The WebSphere Commerce Payments Server is a WebSphere enterprise application that runs on its own application server within the WebSphere Application Server. After installation, the WebSphere Commerce Payments must be created using the Configuration Manager. When creating a WebSphere Commerce Payments instance using the Configuration Manager, the WebSphere Commerce Payments instance application server is created and the WebSphere Commerce Payments enterprise application is deployed. The WebSphere Commerce Payments Server can be installed on the WebSphere Commerce node or on a remote node. For information on implementing a remote WebSphere Commerce Payments node, refer to 18.5, “WebSphere Commerce Payments node implementation” on page 698.

32

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

2.2.6 Enablement software There are several enablement software components included with WebSphere Commerce that can be optionally installed. In addition, we have listed WebSphere enablement software that can be leveraged by WebSphere Commerce.

WebSphere Commerce enablement software This section describes the functionality provided by the following enablement software included with IBM WebSphere Commerce V5.5:
Personalization There are two personalization solutions included with WebSphere Commerce, Blaze Rules and LikeMinds collaborative filtering. The personalization software can be used to improve the customer experience by tailoring the site to a number of criteria, such as customer profile, shopping cart contents, and purchase history.
Commerce analytics WebSphere Commerce V5.5 has improved analytics capability through the use of WebSphere Commerce Analyzer and IBM DB2 Intelligent Miner for Data V8.1, and IBM DB2 UDB V8.1 warehousing features. There are many business intelligence reports included with WebSphere Commerce, which leverage the technology of the WebSphere Commerce Reporting Framework and are accessible from the WebSphere Commerce Accelerator. For more information, refer to Chapter 20, “Commerce analytics” on page 787.
Messaging integration WebSphere Commerce V5.5 includes messaging adapters for HTTP, e-mail, MQ, InterChange Server (ICS), and file. Inbound messaging supports the HTTP and MQ adapters and can be customized to support other protocols. Outbound messaging support includes WebSphere MQ, WebSphere InterChange Server (ICS), e-mail, and file adapters. WebSphere Commerce ships with a sample J2C-based connector that can be customized. For more information, refer to Chapter 21, “Messaging integration with MQ and e-mail” on page 883.
Collaboration Customer Care, which is a Lotus Sametime V3.0 application integrated with WebSphere Commerce, provides live help in real time between customers and customer service representatives (CSRs).

Chapter 2. Runtime architecture

33

Collaborative Workspaces, which is built-upon Lotus QuickPlace V3.0 and only available with the Business Edition, provides an environment where business customers and line-of-business users can interact.
Directory Server (LDAP) IBM Directory Server V4.1.1 is an LDAP directory server included with WebSphere Commerce V5.5. WebSphere Commerce can optionally be configured to use LDAP as the member repository instead of the default WebSphere Commerce instance database. LDAP provides for better integration and single sign-on (SSO) for multiple participating applications sharing the same LDAP directory.

WebSphere enablement software The IBM WebSphere software brand includes many enablement software solutions that can be leveraged by WebSphere Commerce. This section highlights the WebSphere Foundations, Tools and Business Portals.
WebSphere Foundation and Tools The WebSphere Application Server is a J2EE based application server. The WebSphere Commerce Server (application server) is an enterprise application and has its own application server. WebSphere Commerce V5.5 includes the IBM WebSphere Application Server V5 base edition and the Network Deployment Edition. WebSphere Commerce can leverage the technologies provided by the WebSphere Application Server and WebSphere tooling, namely WebSphere Studio Application Developer for the development of Java and related application assets.
WebSphere Business Portals WebSphere Business Portals help extend and personalize the user experience. The integration of WebSphere Commerce V5.5 and WebSphere Portal V5 will be delivered in an upcoming Enhancement Pack.

2.3 WebSphere Commerce Server subsystems The subsystems provide a great deal of functionality for the WebSphere Commerce Server. The subsystems are used to integrate other components and external nodes as well as make it vastly easier for the store developer to customize, deploy, and manage a store.

34

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

2.3.1 Member subsystem The Member subsystem is a component of the WebSphere Commerce Server that provides a framework for managing the following participants of the system:





Organizational entity (for example, IBM) Organizational unit (for example, IBM Software Group) Member group - group of users Members - users, member groups, organizational entity

The member data is stored within either a WebSphere Commerce instance database or an LDAP directory server database. By default, WebSphere Commerce uses the instance database as its registry. The major functions of the Member subsystems are to provide member registration and profile management. Other closely related services of the Member subsystem include authentication, access control, and session management.

User registration methods To facilitate various requirements for e-commerce Web sites, WebSphere Commerce provides several methods for user registration, as seen in Figure 2-2.

1

WebSphere Commerce

Customer

WebSphere Commerce instance database Customer Service Representative

MQ Applications

2 MQ

3a

3

3b LDAP

4

JNDI LDAP API

LDAP Directory Management Tool

3c

Mass Loader

Directory Applications

Legacy DB LDIF

Mass Import Files

Figure 2-2 User registration and update methods

1. WebSphere Commerce online registration This involves the registration of members online for the 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.

Chapter 2. Runtime architecture

35

2. MQ WebSphere Commerce also supports member registration from back-end systems, such as ERP systems using WebSphere MQ. To enable this method, the WebSphere Commerce message transport adapter and MQ need to be configured. WebSphere Commerce 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 integration solution. By default, WebSphere Commerce does not provide outbound services over MQ for the Member subsystem. We demonstrate how to register a new user in 21.6, “Scenario: add new inbound message for MQ” on page 936, using WebSphere MQ. 3. Using LDAP WebSphere Commerce also supports integration with industry-standard LDAP directory for user registration. If LDAP is used as a user registry, then WebSphere Commerce will synchronize with the LDAP directory, based on the mapping parameters defined in the WebSphere Commerce ldapentry.xml file between WebSphere Commerce and LDAP. When the registered user in LDAP logs into the WebSphere Commerce system, the user entry is replicated on the fly to the WebSphere Commerce store database. WebSphere Commerce will synchronize with the LDAP directory to retrieve and update the user registration. 4. Using WebSphere Commerce Loader Package (MassLoad) WebSphere Commerce Loader Package is used for mass database updates. The MassLoad tool can be used for mass registration of users. This method is especially useful in the migration from previous versions, in database management, and in member registration exchange across WebSphere Commerce 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 representativecan update the user profiles.

Member security services The following security services are closely related to the Member subsystem:
Roles The Member subsystem allows its users and organizational entity members to be assigned roles. The roles define the activities that members are allowed to perform. Role assignment is the responsibility of the site administrator.

36

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


Authentication WebSphere Commerce supports two modes of authentication: – Basic authentication (using user ID and password) This mode of authentication is the default and can be used with the WebSphere Commerce store database or an LDAP directory. – Certificate-based authentication (using x.509 certificates) The authentication mode is configured via the WebSphere Commerce Configuration Manager within the Web server tab of the instance properties.
Access control To facilitate database management and ensure security, access to WebSphere Commerce must be restricted to specific individuals and organizations. The process of restricting access is referred to as access control. Access control can be defined as security guidelines that: – Allow or deny a user of a system access to the resources managed by a system. – Specify what actions the user can perform on each resource. Access control is managed through the implementation of access control policies and policy groups. – Access control policies An access control policy authorizes a group of users to perform particular actions on a group of WebSphere Commerce resources. Unless authorized through one or more access control policies, users have no access to any functions. Access control policies grant authorization to a specific group of users to perform particular actions on resources in a specified resource group. An access control policy consists of four parts: •

Access group: The group of users to which the policy applies.

•

Action group: A group of actions.

•

Resource group: The resources controlled by the policy. A resource group may include business objects such as contract or order, or a set of related commands.

•

Relationship (optional): Each resource type can have a set of relationships associated with it. Each resource can have a set of users that fulfill each relationship.

– Policy groups Different organizations in an e-commerce site require different sets of access control policies. For example, a seller organization would require

Chapter 2. Runtime architecture

37

shopping-related policies, while a buyer organization would not need them. In order to accomplish this type of requirement, in WebSphere Commerce, access control policies are partitioned into access control policy groups. In order for an access control policy to be applied in the site, it must belong to an access control policy group. Then, based on their business and access control requirements, organizations subscribe to the appropriate access control policy groups.
Session control WebSphere Commerce is a WebSphere application that is based on the J2EE specification. For this reason, WebSphere Commerce follows the servlet specification for session management. – Session manager: You can configure WebSphere Commerce session manager from the Session Management tab via the Configuration Manager to use either WebSphere Commerce or WebSphere Application Server. The WebSphere Commerce session manager offers better performance, but does not allow extra information to be added to the session and the WebSphere Application Server does. – Session types: WebSphere Commerce 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.

Single sign-on WebSphere Commerce supports single sign-on when configured with an LDAP directory.

38

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

2.3.2 Catalog subsystem The Catalog subsystem provides online catalog navigation, merchandising features, interest lists, and search capabilities. The Catalog subsystem includes all logic and data relevant to a catalog, including categories, products and their attributes, items, and any associations or relationships among them. It interacts with the Member subsystems and the Order subsystems to obtain information about viewing templates and pricing. The following features are provided:
Groupings A generic grouping construct is introduced for categorizations of various products. The owner of a catalog group may not necessarily be the owner of all the catalog entries in the group. This allows portal owners to define the categories of products offered while other suppliers can add their products to the catalog group.
Catalog entries One or more catalog entries can belong to a catalog group. A set of base object types is provided to represent products, stock keeping unit (SKU) items, packages, and bundles in a catalog entry.
Merchandising associations These make it possible to create an association between any two catalog objects, which become cross-sells, up-sells, and promotions.
Globalization support The catalog design addresses the requirement to support multicultural features such as product display and currency format according to the locale.

2.3.3 Trading subsystem The Trading subsystem in WebSphere Commerce provides the logic, function and data relevant for negotiating the price and quantity of a product or set of products between the buyer and seller organization. For the Professional Edition, the trading subsystem includes auctions. For the Business Edition, the trading subsystem includes auctions, contracts, and Request for Quote (RFQ) components that are used to carry out specific transactions between organizations.

Chapter 2. Runtime architecture

39

2.3.4 Order subsystem The Order subsystem is a component of the WebSphere Commerce Server that provides shopping carts, order processing, and order management function support. Related services, such as pricing, taxation, payment, inventory, and fulfillment, are also part of the order subsystem. Order processing capabilities include quick order or buy, scheduled orders, multiple pending orders, reorders, and splitting or back orders.

2.3.5 Merchandising subsystem The Merchandising subsystem is a component of the WebSphere Commerce Server that provides functionality for cross-selling, up-selling, suggested accessories, and merchandising associations between products in the catalog.

2.3.6 Marketing subsystem The Marketing subsystem is a component of the WebSphere Commerce Server, and provides numerous marketing concepts to your site. Components of the marketing subsystem provide functionality to create marketing campaigns including product recommendations, advertisements, and electronic coupons, discounts, customer profiles, and collaboration.

2.3.7 Inventory subsystem The Inventory subsystem provides real-time inventory management. Components of the inventory subsystem provide functionality to record inventory received from vendors and that is returned by customers, adjust inventory quantity, determine the disposition of returned inventory, and ship and receive inventory.

2.3.8 Messaging subsystem The Messaging system provides WebSphere Commerce with the ability to communicate externally. This communication includes sending messages to and receiving messages from back-end systems or external systems, as well as sending notification to customers and administrators that events have occurred within WebSphere Commerce. This is accomplished through two subsystems: an inbound system that manages inbound messages coming from back-end and external systems, and an outbound messaging system that allows you to send notification to users as well as outbound messages to back-end systems and external systems.

40

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

For example, you can set up the messaging system to send e-mail messages notifying your customers that their orders have been shipped. The messaging system provides a mechanism for integrating WebSphere Commerce with back-end systems. You can configure WebSphere Commerce to send an outbound message to a back-end system whenever an order is created at your store. This order information can be used by the back-end system to do necessary order fulfillment processing. The back-end system can later send order status messages back to WebSphere Commerce indicating that order delivery has taken place or an order invoice has been issued. E-mail can also be sent to update the customer.

2.4 Runtime topology selection IBM WebSphere Commerce V5.5 leverages the runtime architecture of the IBM WebSphere Application Server V5 base edition and Network Deployment Edition. The terms runtime architecture, runtime environment and runtime topology are synonymous in this redbook. In this section, we describe the criteria used to select the appropriate topology for your business needs, highlight the benefits of the supported WebSphere Commerce runtime topologies, and provide a mapping to information on implementing the desired runtime topology.

2.4.1 Runtime topology selection criteria A variety of factors come into play when considering the appropriate topology, or configuration, for a WebSphere Commerce deployment. The selection criteria typically include a review of your requirements in the following areas:









Security Performance Throughput Scalability Availability Maintainability Session management Topology selection criteria summary

This section reviews these factors, their availability, and support provided by the IBM WebSphere Application Server base edition and IBM WebSphere Application Server Network Deployment Edition.

Security Security concerns usually require a physical separation of the Web server from the application server processes, typically across one or more firewalls. A

Chapter 2. Runtime architecture

41

common configuration would be the use of two firewalls to create a demilitarized zone (DMZ). Information in the DMZ has some protection based on protocol filtering between the Internet and the DMZ. A Web server intercepts the requests and forwards them on through the next firewall. The sensitive portions of the application and business data reside behind the second firewall, which filters based on IP addresses or domains.

Performance Performance involves minimizing the response time for a given transaction load. Although a number of factors relating to application design can affect performance, one or both of the following techniques are commonly used:
Vertical scaling Involves creating additional application server processes on a single physical machine, providing for software/application server failover as well as load balancing across multiple JVM (application server processes). Vertical scaling allows an administrator to profile an existing application server for bottlenecks in performance, and potentially use additional application servers, on the same machine, to get around these performance issues.
Horizontal scaling Involves creating additional application server processes on multiple physical machines to take advantage of the additional processing power available on each machine. This provides hardware failover support and allows an administrator to spread the cost of an implementation across multiple physical machines.

Throughput Throughput, while related to performance, involves the creation of a number of application server instances to service the same requests. IBM WebSphere Application Server Network Deployment provides clusters, which logically group a number of application servers. The application servers are added through vertical and/or horizontal scaling. .

Note: There is no longer the concept of server groups and clones, as in WebSphere Application Server V4.0. Now each application server cooperates in a cluster, as a cluster member.

42

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Scalability Multiple machines can be configured to add processing power, improve security, maximize availability, and balance workloads. The components that provide functions for configuring scalability include:
WebSphere Application Server cluster support Clusters allow the creation of a logical group of servers that all host and run the same application(s). Members of a cluster can be located on the same machine (vertical scaling) and/or across multiple machines (horizontal scaling). The use of application server clusters can improve the performance of a server, simplify its administration, and enable the use of workload management. However, an administrator will need to assess whether the cost of implementing a clustered configuration (network traffic, performance) outweighs the benefits of a clustered environment. For more details, see IBM WebSphere V5.0 Applications: Ensuring High Performance and Scalability, SG24-6198.
WebSphere workload management (WLM) Incoming processing requests from clients are transparently distributed among the clustered application servers. WLM enables both load balancing and failover, improving the reliability and scalability of WebSphere applications. Note: IBM WebSphere Application Server Network Deployment provides three types of workload management (WLM):
Web server WLM Uses the Load Balancer feature from Edge Components as an IP sprayer to distribute HTTP requests across Web servers.
Web server plug-in WLM Distributes servlet requests across Web containers.
Enterprise Java Services (EJS) WLM Distributes EJB requests across EJB containers.
IP sprayer Transparently redirects incoming HTTP requests from Web clients to a group of Web servers. Although the clients behave as if they are communicating directly with a given Web server, the IP sprayer is actually intercepting all requests and distributing them among all the available Web servers in the group. IP sprayers (such as the Load Balancer component of Edge

Chapter 2. Runtime architecture

43

Components or Cisco Local Director) can provide scalability, load balancing, and failover for Web servers.

Availability To avoid a single point of failure and maximize system availability, the topology must have some degree of process redundancy. High-availability topologies typically involve horizontal scaling across multiple machines. Vertical scaling can improve availability by creating multiple processes, but the machine itself becomes a point of failure. In addition, an IP sprayer can direct client HTTP requests to available Web servers, bypassing any that are offline. Another server can back up the IP sprayer, which eliminates it as a single point of failure. Improved availability is one of the key benefits of scaling up to multiple machines. IBM WebSphere Application Server Network Deployment provides tools that let you manage availability by distributing critical functionality across multiple machines. Applications hosted on multiple machines generally have less down time and are able to service client requests more consistently. The following commonly used techniques can be combined to take advantage of the best features of each and create a highly available system.

Hardware and process redundancy Eliminate the single points of failure in a system by including hardware and process redundancy as follows:
Use horizontal scaling to distribute application servers across multiple physical machines. If a hardware or process failure occurs, cluster application servers are still available to handle client requests. Web servers and IP sprayers can also benefit from horizontal scaling.
Use backup servers for databases, Web servers, IP sprayers, and other important resources. This ensures that they remain available if a hardware or process failure occurs.
Deploy an application in multiple cells. If an entire cell goes offline, the other cells are still available to handle client requests.

44

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Process isolation Provide process isolation so that failing servers do not negatively impact the remaining healthy servers of a configuration. The following configurations provide some degree of process isolation:
Deploy the Web server onto a different machine from the application servers. This ensures that problems with the application servers do not affect the Web server, and vice versa.
Use horizontal scaling, which physically separates application server processes onto different machines.
Deploy an application in multiple cells. Problems are confined to one cell while the other cells remain available.

Load balancing Use load-balancing techniques to make sure that individual servers are not overwhelmed with client requests. These techniques include:
Use of an IP sprayer to distribute requests to the Web servers in the configuration.
Directing requests from high-traffic Web sites to more powerful servers. The Edge Components included with IBM WebSphere Application Server Network Deployment provide these features.

Failover support The application must continue to process client requests when servers are stopped or restarted. Ways to provide failover support include:
Use horizontal scaling with workload management to take advantage of its failover support.
Use the HTTP transport to distribute client requests among application servers.

Hardware-based high availability In most cases there is very little to be gained by configuring WebSphere to work in conjunction with a hardware-based high-availability product, for example HACMP, Sun Cluster, or MC/ServiceGuard. The only case where a hardware-based HA solution would provide value is where WebSphere serves as the coordinator of a distributed (two-phase commit) transaction. In all other cases, the cluster capabilities inherent in Network Deployment should be sufficient to provide high availability of the WebSphere runtime.

Chapter 2. Runtime architecture

45

Maintainability The topology affects the ease with which system hardware and software can be updated. For instance, using multiple WebSphere cells or horizontal scaling can make a system easier to maintain because individual machines can be taken offline without interrupting other machines running the application. Sometimes maintainability conflicts with other topology considerations. For example, limiting the number of application server instances makes the application easier to maintain but can have a negative effect on throughput, availability, and performance. When deciding how much vertical and/or horizontal scaling is to be used in a topology, consideration needs to be made for hardware upgrades, for example, adding or upgrading CPUs and memory.

Session management Unless only a single application server is used, or the application is completely stateless, maintaining session state between HTTP client requests will also be a factor in determining the chosen topology. Network Deployment provides two different functions for the sharing of sessions between multiple application server processes:
Database persistence Session data is persisted to a database shared by the application servers.
Memory-to-memory replication Provides replication of session data between the memories of different application server JVMs. A JMS publish/subscribe mechanism, called WebSphere Internal Messaging, is used to provide assured session replication between the JVM processes, by leveraging the internal JMS provider provided with WebSphere Application Server. This means that a database product is not required for persistence. Memory-to-memory replication is faster, by virtue of the high-performance messaging implementation used by WebSphere V5.0. However, it is only available in the Network Deployment environment. Note: This mechanism is new to IBM WebSphere Application Server Network Deployment V5.0. Prior versions of WebSphere provided persistence of the session to a database only. In addition, the configuration of any IP sprayers (such as provided with the Edge Components) needs to be considered when session state is a factor.

46

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Within WebSphere Commerce, there are two methods of session control for applications, cookie-based and URL rewriting, which are described in “Member security services” on page 36.

Topology selection criteria summary The preceding factors are not mutually exclusive. They can be combined in many different ways. Table 2-1 provides a summary of the topology selection criteria available with IBM WebSphere Application Server Network Deployment. Table 2-1 Topology selection summary Topology

Security

Performance

Throughput

Maintainability

Availability

Session

Vertical scaling

Limited benefit

Limited to resources on a single machine

Easiest to maintain

Process isolation

Required

Horizontal scaling

Best in general

Best in general

Code migration to multiple nodes

Process and hardware redundancy

Required

HTTP separation

Allow for firewalls and DMZs

Usually better than local

Usually better than local

Three tiers

Most options for firewalls

Typically slower than single JVM API

Clustering can improve throughput

One cell

Ease of maintenance

Multiple cells

Harder to maintain than single cell

Process, hardware and software redundancy

2.4.2 WebSphere Commerce runtime topologies This section provides a graphical view of various runtime topologies supported by WebSphere Commerce, and highlights the advantages and disadvantages of each of the following topologies:
Single-tier

Chapter 2. Runtime architecture

47








Two-tier remote Database server node Two-tier remote Web Server redirector node Three-tier Vertical application server cluster Load balanced horizontal Web and application server cluster

Terminology The illustrations used to represent each topology will include boxes that represent logical runtime functions. The terminology used is taken from the Patterns for e-business Web site at: http://www.ibm.com/developerworks/patterns

Note: In the Patterns for e-business, a runtime node represents a logical function. That node may actually be implemented using multiple physical machines. Do not confuse that with the concept of a physical node in WebSphere.
Network zones The runtime environments (topologies) depicted in this section are separated into network zones for security reasons. The network zones are as follows: – Outsize world – Demilitarized zone (DMZ) – Internal network
Domain and protocol firewalls A firewall is a hardware/software system that manages the flow of information between two networks. Firewalls can prevent unauthorized Internet users from accessing private networks connected to the Internet, especially intranets, and can block some virus attacks - as long as those viruses are coming from the Internet.
Load balance node The load balancer node provides horizontal scalability by dispatching HTTP requests among several identically configured Web server or Web server redirector nodes. Using a load balancer may introduce the need to ensure session affinity. In these topologies, the load balancer node is implemented using the Edge Components included with the IBM WebSphere Application Server V5, Network Deployment Edition.
Web server redirector node A Web server redirector node includes the HTTP Server and the WebSphere plug-in. This type of node typically is used to serve static HTML pages and

48

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

images, and to redirect application requests via the WebSphere plug-in to the WebSphere Application Server. In most of the topologies seen in this section, the Web server redirector node will be located in the DMZ.
Directory and security services node The directory and security services node supplies information on the location, capabilities, and attributes (including user ID/password pairs and certificates) of resources and users known to this Web application system. This node can supply information for various security services (authentication and authorization) and can 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 part of the Web server, but this node also authenticates for access to the database server. In these topologies, the directory and security services node is implemented using the IBM Directory Server V4.1.
Database server node The function of this node is to provide a persistent data storage and retrieval in support of the user-to-business transactional interaction. The data stored is relevant to the specific business interaction, for example bank balance, insurance information, and current purchase by the user. 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 single or very few calls. One approach for achieving this is by coding and invoking stored procedure calls on the database. Both IBM DB2 UDB V8.1 Enterprise Server Edition and Oracle9i Standard and Enterprise Edition Release 2 are supported by IBM WebSphere Commerce V5.5.
Deployment Manager In a WebSphere Application Server V5, Network Deployment Edition environment, the Deployment Manager is the focal point for configuration and operation. Though not technically a defined Patterns for e-business runtime node, it is important to this discussion to depict this node in the topologies. For each of the topologies, a decision needs to be made regarding the placement of the Deployment Manager and master cell repository. The Deployment Manager can be located on a dedicated machine or it can co-exist with a WebSphere Application Server installation. We would recommend placing it on a dedicated machine.

Chapter 2. Runtime architecture

49

Single-tier A single-tier (also called 1-tier) configuration consists of all the runtime software components installed on a single physical machine. This is easiest to set up and would be suitable as a development or test environment. It would not, in most cases, satisfy the scalability, security and availability requirements of a production site unless you are using a high-end IBM zSeries or iSeries server. The only way to scale with this type of configuration is to scale vertically by adding memory, disk space, processors to the server, and in the most extreme cases, upgrading the server to a more powerful system. A simple single-tier system is shown in Figure 2-3.

Internal network

I N T E R N E T

HTTP HTTPS

Firewall

Outside world

WebSphere Commerce node

application databases

Figure 2-3 WebSphere Commerce single-tier topology

Two-tier remote Database server node In a two-tier remote database server configuration, the database is installed on a separate database server node, as seen in Figure 2-4 on page 51. Separating the database server from the WebSphere Commerce node provides for greater scalability and security by having the ability to add a firewall between the nodes.

50

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

HTTP HTTPS

Protocol Firewall

I N T E R N E T

WebSphere Com m erce node

Internal netw ork

HTTP HTTPS

Domain Firewall

DMZ

O utside w orld

Database server node

application databases

Figure 2-4 WebSphere Commerce two-tier remote database server runtime environment

Two-tier remote Web Server redirector node In a two-tier (also called 2-tier) remote Web server configuration, the Web server is installed on a separate node from the WebSphere Commerce node, as seen in Figure 2-4. The remote Web Server node provides for greater scalability and security. In the case of the remote Web server two-tier, the application assets of the WebSphere Commerce node are further protected by being behind an additional firewall. Only the Web server is accessible via HTTP or HTTPS through the firewall by Internet users.

Chapter 2. Runtime architecture

51

H TT P H TTP S

Protocol Firewall

I N T E R N E T

W eb serv er red irec to r no de H TT P S erver W eb S p here plu g in

In tern al n e tw o rk

H TT P H TT P S

Domain Firewall

DMZ

O u tsid e w o rld

W eb S p he re W eb C o m m erce S erver n od e

a pplication d atabases

Figure 2-5 WebSphere Commerce two-tier remote Web server redirector topology

The two-tier remote Web server topology includes the HTTP Server and the WebSphere plug-in. HTTP server separation topologies physically separate the HTTP (Web) server from the application servers, typically to place the HTTP server in a DMZ. Using a DMZ provides an additional layer of security for back-end servers and data. The Web server redirector node is used to serve static HTML pages and images, and to redirect application requests to application servers on remote systems using the HTTP or HTTPS protocol.

Three-tier A three-tier topology (also called 3-tier) separates the Web server redirector node, WebSphere Commerce node, and Database server nodes, as shown in Figure 2-6 on page 53. The primary reasons for implementing a three-tier topology are security and scalability.

52

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

HTTP HTTPS

DMZ

Web server redirector node HTTP Server

Internal network

HTTP HTTPS

WebSphere plugin

Domain Firewall

I N T E R N E T

Protocol Firewall

Outside world

WebSphere Web Commerce Server node

Database server node

application databases

Figure 2-6 WebSphere Commerce three-tier topology

Figure 2-7 on page 54 depicts a variation of WebSphere Commerce three-tier topology, where the WebSphere Commerce Payments node is separate from the WebSphere Commerce node.

Chapter 2. Runtime architecture

53

HTTP HTTPS

Protocol Firewall

I N T E R N E T

Internal network

Web server redirector node HTTP Server WebSphere plugin

HTTP HTTPS

Domain Firewall

DMZ

Outside world

WebSphere Commerce node

WebSphere Commerce Payments node

Database server node

application databases

Figure 2-7 WebSphere Commerce three-tier with remote WebSphere Commerce Payments node

Vertical application server cluster Vertical scaling refers to configuring multiple application servers on a single machine, usually by creating a cluster of associated application servers all hosting the same application(s). When a WebSphere Commerce instance is created, a WebSphere Commerce application server is created and the enterprise application is deployed to it. The three-tier vertical application configuration is depicted in Figure 2-8 on page 55.

54

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

DMZ

O u ts id e w o rld

In te rn a l n e tw o r k

HTTP HTTPS

W e b s erve r r e d ir e c to r n o d e HTTP S e rv e r

HTTP H TTPS

W eb S p h ere p lu g -in

W e b S p h e re C o m m e rc e a p p lic a tio n s e rv e r 1

Domain Firewall Domain Firewall

I N T E R N E T

Protocol Firewall

W e b S p h e re C o m m e rc e n o d e

W e b S p h e re C o m m e rc e a p p lic a tio n s e rv e r 2

C lu s te r 1

D a ta b a s e server node

a p p lic a tio n d a ta b a s e s

D e p lo y m e n t M anager

W e b S p h e re C o m m e rc e P a ym e n ts a p p lic a tio n s e rv e r

Figure 2-8 Vertical scaling with clusters

There are a few key points to reference from Figure 2-8. First, there is a one-to-one relationship between a WebSphere Commerce instance or cluster (vertical or horizontal) and the WebSphere Commerce Payments instance (application server). Second, a WebSphere Commerce Payments instance cannot be a member of a cluster. Third, in previous releases of WebSphere Application Server an additional server in a vertical cluster was known as a clone. The IBM WebSphere Application Server V5, Network Deployment Edition, Deployment Manager is used to manage the application servers in the vertical or horizontal cluster.

Advantages Vertical scaling has the following advantages:
Efficient use of machine processing power. An instance of an application server runs in a single Java virtual machine (JVM) process. However, the inherent concurrency limitations of a JVM process prevent it from fully utilizing the processing power of a machine. Creating additional JVM processes provides multiple thread pools, each corresponding to the JVM associated with each application server process. This avoids concurrency limitations and lets the application server use the full processing power of the machine.
Load balancing. Vertical scaling topologies can make use of the WebSphere workload management.

Chapter 2. Runtime architecture

55


Process failover. Vertical scaling can provide failover support among application servers of a cluster. If one application server instance goes offline, the other instances on the machine continue to process client requests.

Disadvantages Single machine vertical scaling topologies have the drawback of introducing the host machine as a single point of failure in the system.

Load balanced horizontal Web and application server cluster Load-balancing products can be used to distribute HTTP requests among application server instances that are running on multiple physical machines. The Network Dispatcher component of Edge Components is an IP sprayer that performs intelligent load balancing among Web servers using server availability, capability, workload, and other criteria. Figure 2-9 depicts a simple load-balanced Web server cluster and application server cluster to distribute requests among application servers on multiple machines. In this example, the Web servers are installed on the same node as the application servers. The Web server (cluster) can be on separate systems from the application servers. Outside world

Internal network

DMZ

HTTP/ HTTPS

Load Balancer node

Backup Load Balancer node

Domain Firewall

I N T E R N E T

Protocol ProtocolFirewall Firewall

HTTP/ HTTPS

WebSphere Commerce node application Web server 1 Server 1 WebSphere plugin

WebSphere Commerce node application server 2

Web Server 2 WebSphere plugin

Directory & Security services LDAP Database server Application data Deployment Manager

Figure 2-9 Simple IP sprayer-based horizontally scaled topology

A backup node for the load balancer node is normally configured in order to eliminate it as a single point of failure.

56

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Note: In an IP sprayer (or similarly configured) topology, each Web server can be configured to perform workload management over all application servers in a specific cluster. In this configuration, session affinity will be preserved, no matter which Web server is passed the request by the IP sprayer. Horizontal scaling exists when the members of an application server cluster are located across multiple physical machines. This lets a single application span several machines, yet still present a single logical image. The Web server plug-in distributes requests to cluster member application servers on the application server nodes. The Network Dispatcher component of Edge Components, which can distribute client HTTP requests, can be combined with clustering to reap the benefits of both types of horizontal scaling.

Advantages Horizontal scaling using clusters has the following advantages:
Provides the increased throughput of vertical scaling topologies but also provides failover support. This topology allows handling of application server process failures and hardware failures without significant interruption to client service.
Optimizes the distribution of client requests through mechanisms such as workload management or remote HTTP transport.

Disadvantages Horizontal scaling using clusters has the following disadvantage:
Increased maintenance effort.

2.4.3 Topology mapping to implementation details Table 2-2 includes a summary of various supported WebSphere Commerce runtime topologies and where to find information to implement the topology. Table 2-2 Topology summary ad map to implementation details Topology

Information

Single-tier

* IBM WebSphere Commerce product installation guides by platform * 16.2, “Single-tier implementation” on page 559 on Windows

Chapter 2. Runtime architecture

57

Topology

Information

Two-tier remote Database server node

* IBM WebSphere Commerce product installation guides by platform * 16.3, “Add a remote Database Server node” on page 582 on Windows * Chapter 19, “OS/400: Two-tier remote database server” on page 755

Two-tier remote Web Server redirector node

* IBM WebSphere Commerce product installation guides by platform * 16.4, “Add remote Web Server node” on page 587 on Windows

Three-tier

* IBM WebSphere Commerce product installation guides by platform * Chapter 16, “Windows: Migrate a single-tier to a multi-tier” on page 553 * Chapter 17, “Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server” on page 599 * Chapter 18, “AIX: Three-tier using DB2 and IBM HTTP Server” on page 675*

Vertical application server cluster

* IBM WebSphere Commerce product installation guides by platform * IBM WebSphere V5 Edge of Network Patterns, SG24-6896 * IBM WebSphere Application Server V5.0 Systems Management and Configuration: WebSphere Handbook Series, SG24-6195 * WebSphere V5.0 Applications: Ensuring High Performance and Scalability, SG24-6198

Load balanced horizontal Web and application server cluster

* IBM WebSphere Commerce product installation guides by platform * IBM WebSphere V5 Edge of Network Patterns, SG24-6896 * IBM WebSphere Application Server V5.0 Systems Management and Configuration: WebSphere Handbook Series, SG24-6195 * WebSphere V5.0 Applications: Ensuring High Performance and Scalability, SG24-6198

2.5 For more information Refer to the following product guides for additional information on the WebSphere Commerce architecture:
Fundamentals Guide, IBM WebSphere Commerce V5.5
WebSphere Commerce V5.5 online documentation
Programming Guide and Tutorials, IBM WebSphere Commerce V5.5
IBM WebSphere Commerce product installation guides: – Microsoft Windows •

Quick Beginnings Guide for Windows 2000, IBM WebSphere Commerce V5.5

•

Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000

– UNIX (IBM AIX and SUN Solaris)

58

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

•

Quick Beginnings Guide for AIX, IBM WebSphere Commerce V5.5

•

Quick Beginnings Guide for Solaris, IBM WebSphere Commerce V5.5

•

Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems

– IBM OS/400 •

Quick Beginnings Guide for OS/400, IBM WebSphere Commerce V5.5

•

Installation Guide, IBM WebSphere Commerce V5.5 for OS/400


IBM WebSphere Application Server V5.0 Systems Management and Configuration: WebSphere Handbook Series, SG24-6195
WebSphere V5.0 Applications: Ensuring High Performance and Scalability, SG24-6198
IBM WebSphere V5 Edge of Network Patterns, SG24-6896

Chapter 2. Runtime architecture

59

60

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

3

Chapter 3.

Business and store models One of the most significant advances in IBM WebSphere Commerce V5.5, Business Edition is the addition of several new business models and supporting infrastructure. The new business models include Hosting, and value chains for the Demand Chain and Supply Chain models, as well as enhancements to the B2B direct and consumer direct models. This chapter describes the business models, the sample store instantiations of the business models, and the infrastructure added to support the new models. In addition, we analyze the components of the sample stores and describe the new options available for store publishing. This chapter is organized into the following topics:





Business and store models Business model infrastructure and architecture Store architecture For more information

© Copyright IBM Corp. 2003. All rights reserved.

61

3.1 Business and store models IBM WebSphere Commerce V5.5, Business Edition includes all the features of the Professional Edition, plus additional support for B2B, including the new business models for hosting, and value chains (demand and supply). Table 3-1 provides a summary of the business models and corresponding sample store model listed by the supported WebSphere Commerce edition. The sample stores are packaged in a store archive file for deployment. In Table 3-1 we have listed the composite store archive name for the sample store. In WebSphere Commerce V5.5, there is a new concept of composite or all contents of the store archive and component store archives containing a subset of functionality of the sample store model. We describe this concept in greater detail throughout the chapter. Table 3-1 Summary of business and store models Business model name

Store model name

Composite store archive name

Professional Edition

Business Edition

Consumer direct (B2C)

FashionFlow

ConsumerDirect.sar

X

X

B2B Direct

ToolTech

B2BDirect.sar

X

Hosting

Hosting

Hosting.sar

X

Demand Chain

Demand Chain

DemandChain.sar

X

Supply Chain

Supply Chain

SupplyChain.sar

X

Note: For more detailed on each of the sample store models, refer to the Sample Store Guide, IBM WebSphere Commerce V5.5 product guide. IBM WebSphere Commerce V5.5 provides the architecture infrastructure to support the business models. The business models are categorized as follows:
Direct sales – Consumer direct – B2B direct
Hosting
Value chains – Demand Chain – Supply Chain

62

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

3.1.1 Direct sales Both the consumer direct and B2B direct are direct sales business models. In this section we describe the distinguishing features of each. Note: The IBM WebSphere Commerce V5.5, Professional Edition only supports the consumer direct business model.

Consumer direct Consumer direct supports commerce transactions involving products, services, or information between businesses and consumers. Consumers typically purchase goods or services directly from a business. Consumer direct is commonly known in the industry as business-to-consumer (B2C) commerce. Figure 3-1 depicts the interaction of consumer-oriented customers (shoppers) with a retail e-commerce site. The consumer direct model is included in the WebSphere Commerce Professional and Business Editions. All other models are only supported by the Business Edition.

Customers

Customers shop at the retailer.

Retailer

Figure 3-1 Consumer direct business model

In a typical consumer direct business, customers buy directly from the business, usually a retailer, as seen in Figure 3-1. The business can be a retailer, a manufacturer that sells its goods directly to consumers through their own retail outlet, or any other business that sells goods or provides services directly to consumers. For example, a business that sells to consumers directly through a catalog would be considered a consumer direct business. Organizations that are not traditionally considered businesses, such as governments, can also be considered consumer direct businesses. Governments may provide goods and services directly to customers.

B2B direct The B2B direct model supports commerce transactions involving products, services, or information between two businesses or parties. Typical B2B direct transactions occur between buyers, suppliers, manufacturers, resellers, distributors, and trading partners. Figure 3-2 on page 64 depicts the interaction of business customers with a business direct e-commerce site.

Chapter 3. Business and store models

63

Business

Buyers from one business purchase goods or services from another.

Business

Figure 3-2 B2B direct business model

In a typical B2B direct business, businesses purchase goods or services directly from another business. The selling business can be a wholesaler, a distributor, a manufacturer, or a retailer who sells to buyers from other businesses. Organizations that are not traditionally considered businesses, such as governments and the media, can also be considered B2B direct businesses. Governments may provide goods and services directly to businesses.

3.1.2 Hosting The hosting model supports hosting of merchants or other businesses by an Internet Service Provider (ISP) or other hosting provider. There are two possible sides to the hosting business:
Hosted stores
Site that allows customers to locate the stores that are hosted by the provider (optional) In order to manage relationships with the hosted stores, hosting models usually include a hub (known in WebSphere Commerce as a hub store). This hub provides self-provisioning tools that allows the merchant to create and administer a store, as well as tools that allow the hosting provider to manage all hosted stores. Hosting providers typically include a store in which customers can find and access the stores hosted by the provider. Figure 3-3 on page 65 depicts both merchants and customers interacting with the hosted stores of an Internet Service Provider (ISP).

64

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Merchant

Customers

Host (Internet Service Provider or other)

Merchant

Host (Internet Service Provider or other)

Figure 3-3 Hosting business model variations

As seen in Figure 3-3, the merchant enters the host’s site and creates a store that will be hosted by the site. Hosting providers often provide merchants with simple self-provisioning tools that allow the merchant to administer a hosted store. When a hosted store is open for e-business, customers can access the store via the host’s site or by entering the hosted store directly. In this example, the customer has the option of entering the hosted store or business directly or browsing the host’s site and then being transferred to the hosted store or business. Hosted stores are very similar to consumer direct stores. For specific differences between the two, as implemented in the WebSphere Commerce sample stores, see the Sample Store Guide, IBM WebSphere Commerce V5.5 product guide.

3.1.3 Value chains New to WebSphere Commerce Version 5.5 is the ability to enable online business transactions involving multiple enterprises. Value chains support transactions involving multiple enterprises or parties. Products, goods, services, or information are delivered through the parties of the value chain from producers to end users. A value chain also has relationship and administrative aspects, that is, you can manage the relationship of the partners or enterprises in your value chain, as well as offer some administrative services to those parties. As a result, value chains must manage the two sides of their businesses: their customers and direct sales, and their channel partners and suppliers. Each of these sides requires its own management channels and practices. In order to manage their relationships with partners or suppliers, value chain business models usually include a hub (in WebSphere Commerce known as a hub store). Value chain administrators can administer the operational aspects of

Chapter 3. Business and store models

65

the value chain in the hub store, including enabling partners or suppliers to participate in the value chain, that is, registering them, setting them up, creating collaborations. Partners and suppliers can also access the hub store to complete administrative tasks such as registering users. In order to sell directly to customers (direct sales), value chains usually include a store front, where customers can purchase their good or services directly. WebSphere Commerce supports the transactions through, and relationship management of the following two types of value chains:
Demand Chain
Supply Chain Figure 3-4 provides an overview of the partners and relationships supported by value chains.

Value chains

Demand chain

Indirect sales (selling through channels)

Consumer direct

Direct sales

B2B direct

Supply chain

Procurement

Strategic sourcing

Sourcing

Private marketplace

Figure 3-4 Value chain business models

Demand Chain A Demand Chain is composed of the enterprises that sell a business’s goods or services. For example, a Demand Chain may be composed of buyers who initiate the sales transaction, the resellers who sell the manufacturer’s goods, and the manufacturer who creates the goods. Alternatively, a Demand Chain may be composed of the resellers who sell a manufacturer’s goods, the manufacturer who makes the goods, and the distributors who supply the manufacturer’s goods

66

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

to the resellers. Demand Chains also support direct sales channels, in which the Demand Chain owner sells directly to customers or partners itself. There are several types of Demand Chains. We have listed the following for reference:
Demand Chain hosting: buyers, resellers, manufacturer
Demand Chain hosting: resellers, manufacturer, distributor
Other Demand Chain scenarios

Demand Chain hosting: buyers, resellers, manufacturer The Demand Chain owner may host stores for its channel partners (for example, resellers or distributors). Figure 3-5 depicts an example of a Demand Chain between buyers, channel partners, and manufacturer. In this example, buyers purchase goods from a manufacturer’s resellers (channel partners). Resellers, in turn, obtain the goods from the manufacturer via the manufacturer’s hub. Note: The resellers may be hosted by the manufacturer or be remote.

Buyers

Channel Partners (Resellers)

Manufacturers or Distributors

Figure 3-5 Demand Chain hosting (hosting for channel partners)

Demand Chain hosting: resellers, manufacturer, distributor In this example, the manufacturer provides a hub for their channel partners including resellers. Resellers and other channel partners may be able to do several functions in this hub, including locating distributors of the manufacturer’s goods. In order to locate suppliers, the reseller may browse a product catalog in the private hub. If the desired products are available from more than one distributor, the reseller can check product availability, distributors’ location, and prices for various distributors. Then, if the reseller chooses, they can split their order between several distributors. The order is then sent to the distributor, who completes the transaction and delivers the goods or services to the reseller. The reseller then sells the goods or services directly to the consumer. The Demand Chain sample store is an example of this reseller, manufacturer and distributor scenario.

Chapter 3. Business and store models

67

Note: The resellers may be hosted by the manufacturer or be remote.

Other Demand Chain scenarios There are many possible Demand Chain scenarios. The scenario details may change depending on the type of business being conducted. For example, if the enterprise is a manufacturer, the purpose of the hub may be to help the manufacturer’s resellers locate the manufacturer’s goods from several distributors. If the enterprise is a distributor, the purpose of the hub may be to help the distributor’s resellers find goods or services from several different suppliers.

Supply Chain business model A Supply Chain is composed of the enterprises that provide services to a business. WebSphere Commerce provides the architectural infrastructure to support Supply Chains that take the form of a private marketplace. A private marketplace provides a forum for vendors to offer their wares for sale. Buyers enter this forum and after browsing through the available options, select the appropriate goods or services. Note: The private marketplace does not support competitive bidding and counter-bidding or other methods of competition. The Supply Chain owner may host a stores for its suppliers.

Buyer

Private marketplace

Supplier

Figure 3-6 Supply Chain business model

Figure 3-6 depicts a Supply Chain where the buyer enters the supplier’s hub to interact and browses the aggregated catalog in which products and offers from multiple suppliers are presented. The buyer can then select the desired offer or request quotes from multiple suppliers. The buyer also has the option of conducting business or procuring from online suppliers directly.

68

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

3.2 Business model infrastructure and architecture This section provides an overview of how the WebSphere Commerce infrastructure and architecture support the business models, including the following topics:
Organization structure
Access control model
Business policy framework Note: The topics found in this section are a summary from the Store Development Guide, IBM WebSphere Commerce V5.5 product guide, which we strongly recommend that you read.

3.2.1 Organization structure The WebSphere Commerce organization structure provides a framework for the actors, or entities in the business scenario. The framework is organized in a hierarchical structure that mimics typical organizational hierarchies with entries for organizations and organizational units and users. The organizations and organizational units in the framework act as owners for the parts of your business. All parts of your business, including customers, administrators, stores, catalogs, and distributors, must be owned by an organization or organizational unit. The organization structure and the access control model, discussed in 3.2.2, “Access control model” on page 72, are closely related, in that the access control model applies access control policies to organizations rather than to individual entities (stores, customers, administrators and so on). The policies that apply to an entity (or resource) are applied to the organizations that own the entity or resource. Figure 3-7 on page 70 outlines the basic WebSphere Commerce organization structure. The basic organization structure is installed during instance creation, regardless of the business model.

Chapter 3. Business and store models

69

o=Root organization

Site Administrators

o=Default organization

Customers

Figure 3-7 WebSphere Commerce organization structure


Root organization The root organization is the top-level organization and is its own parent. All organizations in the WebSphere Commerce organization structure are descendents of the root organization. The site administrators are owned by the root organization.
Default organization The default organization is owned by the root organization. All guest customers and all customers in a consumer direct scenario belong to the default organization. Customers in a B2B direct and value chain scenario can belong to either the default organization or other organizations. One or more other levels of organizational entities can exist beneath the parent organizational entities. You can add as many child organizational entities as necessary to support your business.

B2B direct model and organizational structure We have included a diagram and description of the B2B direct business model to explain how the organization structure supports the business model. For similar information on the other business models (consumer direct, hosting, Demand Chain, and Supply Chain), refer to the Store Development Guide, IBM WebSphere Commerce V5.5 product guide.

70

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

o=Root organization

Site Administrators

o=Default organization

o=Seller organization

Seller Administrators

o=Buyer organization

ou=Business Direct organization

Buyers

Business

Figure 3-8 B2B direct model organization structure

In order to place this business online, the entities in the preceding diagram must be assigned to the following organizations:
Root organization All organizations in the business become descendents of the root organization. The site administrators who maintain the online site are owned by the root. – Default organization Unlike the consumer direct organization structure, the customers are not owned by the default organization. Instead the customers are buyers who are owned by the buyer organization. – Buyer organization Customers, known in B2B direct businesses as buyers, are assigned their own organization in the B2B direct organization structure.

Chapter 3. Business and store models

71

– Seller organization A seller organization is created to own all the organizations that own stores. The administrators who maintain the store’s functions (for example customer service representatives, catalog and product managers) are termed seller administrators and are owned directly by the seller organization. •

A child organizational unit (ou), B2B direct organization, is created under the seller organization to own the store (Business).

3.2.2 Access control model WebSphere Commerce allows you to determine, through access control, which tasks a particular user, be they customers, buyers, administrators, distributors, manufacturers, or suppliers, can perform in relation to your business. Note: For more detailed information on the access control model, refer to the Store Development Guide, IBM WebSphere Commerce V5.5 and Security Guide, IBM WebSphere Commerce V5.5 product guides. Access control in WebSphere Commerce is composed of the following elements: users, actions, resources, and relationships.
Users are the people that use the system. For access control purposes, users must be grouped into relevant access groups. One common attribute that is used to determine membership of an access group is roles. Roles are assigned to users on a per organization basis. Some examples of access groups include registered customers, guest customers, or administrative groups such as customer service representatives.
Actions are the activities that users can perform on the resource. For access control purposes, actions must also be grouped into relevant action groups. For example, a common action used in a store is a view. A view is invoked to display a store page to customers. The views used in your store must be declared as actions and assigned to an action group before they can be accessed.
Resources are the entities that are protected. For example, if the action is a view, the resource to be protected is the command that invoked the view, for example com.ibm.commerce.command.ViewCommand. For access control purposes, resources are grouped into resource groups.
Relationships are the relationship between the user and the resource. Access control policies may require that a relationship between the user and the resource be satisfied. For example, users may only be allowed to display the orders that they have created.

72

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Access control policies Access control policies authorize access groups to perform particular actions on the resources of WebSphere Commerce, as long as the users in the access group satisfy a particular relationship with respect to the resource. WebSphere Commerce provides over 300 default access control policies that are loaded during instance creation. These policies cover a wide range of common business activities, including order creation and processing, and trading, such as request for quotes and contracts (Business Edition). The default policies are documented in the Security Guide, IBM WebSphere Commerce V5.5 product guide.

Access control groups In order for an access control policy to be applied to your store or site, it must belong to an access control policy group and the policy group must be subscribed by the organization that owns the resource. By default, all access control policies provided with WebSphere Commerce are assigned to policy groups. For a list of default policies provided with WebSphere Commerce, see the Security Guide, IBM WebSphere Commerce V5.5 product guide. Although access control policy groups are owned by organizations, they are not automatically applied to the organization. An organization must subscribe to a policy group in order for the access control policies to apply to the organization. If the organization has child organizations, all policy groups the parent subscribes to are automatically applied to the child organizations. However, if the child organization subscribes directly to a policy group, the policy groups subscribed to by the parent organization no longer apply to the child. Note: Refer to the Store Development Guide, IBM WebSphere Commerce V5.5 for a comparison of access control between WebSphere Commerce V5.4 and V5.5.

Basic access control structure The WebSphere Commerce access control structure is flexible enough to support all entities in the supported business models. The diagrams in the following sections demonstrate how access control is applied to a typical example of each business model. The basic access control structure is installed during instance creation, regardless of the business model.

Chapter 3. Business and store models

73

Legend o=Root organization

Owns Subscribes Role

Site administrators have Site Administrator role Site administrators

o=Default organization

Guest shopper management policy group

Management and administration policy group

Common shopping policy group

B2B policy group

B2C policy group

Figure 3-9 Basic access control structure

The root organization owns the following default policy groups:





Management and administration Common shopping B2C B2B

However, the root organization only subscribes to the management and administration policy group. As a result, these policies apply to the site administrators, who are directly under the root. The policies in the management and administration policy group do not apply to the default organization through inheritance, since the default organization subscribes to the guest shopper management policy group. In order for the management and administration policies to apply, the default organization must subscribe to the management and administration policy group explicitly. The default organization owns the guest shopper management policy group. Note: For more detailed information on the default policy groups, see the appendix of the Security Guide, IBM WebSphere Commerce V5.5.

74

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

B2B direct access control structure The Store Development Guide, IBM WebSphere Commerce V5.5 includes diagrams and a description of the access control structure for each of the business models (consumer direct, B2B direct, hosting, Demand Chain, Supply Chain). This section includes a summary of the B2B direct access control structure for example purposes, as seen in Figure 3-10. Legend o=Root organization

Owns

Site administrators have ite Administrator role in the root organization.

Subscribes Role

Site administrators

o=Select organization

o=Default organization

Seller administrators

Guest shopper management access control policy group

Management and administration access control policy group

B2C policy group

Common shopping access contact policy group

B2B policy group

Tooltech policy group

o=Buyer A organization

ou=B2B direct organization

Buyers Store D

Figure 3-10 B2B direct access control structure

Figure 3-10 depicts a basic B2B direct organization structure where the root organization owns and subscribes to the default policy groups as described in “Basic access control structure” on page 73. The B2B direct organization

Chapter 3. Business and store models

75

subscribes directly to the B2B, management and administration, and the common shopping policy groups. The B2B direct organization also owns and subscribes to the ToolTech policy group. The ToolTech policy group contains the following policies:
AllUsersForToolTechExecuteToolTechAllUsersViews
RegisteredCustomersForOrgForToolTechExecuteToolTech RegisteredCustomerViews Buyers are customers that place orders in a B2Bdirect store. All buyers must be owned by a buyer organization. Typically, buyer organizations do not subscribe to any policy groups, since management and administration policies inherited from the root organization are sufficient. Since access control policy groups are subscribed by organizational entities, if you are creating multiple stores in your site, and want to apply different access control policy groups to individual stores, you must create separate organizations to own each store.

3.2.3 Business policy framework Business policies are sets of rules followed by a store or group of stores that define business processes, industry practices, the scope and characteristics of a store or group of stores offerings, and how the store or site interacts with customers and other business partners. For example, your site may have business policies determining when and how customers are allowed to return products to a store, or business policies that determine what payment methods your store accepts. WebSphere Commerce provides a framework that allows you to implement your store’s business policies in your online store or site. The business policy framework consists of the following parts:






Business policies Business accounts Contracts and service agreements Terms and conditions Business accounts

Business policies In most instances, you will have predefined business policies for your business that you need to implement in your online store or site. WebSphere Commerce provides a set of business policies that you can use as is, or change to meet your needs. For more information on the default business policies provided with WebSphere Commerce, see the WebSphere Commerce Production and

76

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Development online help. For information on how to edit these business policies, see the WebSphere Commerce Production and Development online help.

Business accounts Business accounts define the relationship between a customer and your business. Business accounts track contracts and orders for customer organizations and configure how buyers from customer organizations shop in a store.

Contracts and service agreements Before a customer or business partner (for example resellers or distributors) can access your store, you must create a contract or service agreement that defines customer or business partner access to your store. In the WebSphere Commerce business policy framework, you create contracts for customers and service agreements for other types of business partners.
Contracts: A contract with a customer defines what areas of your store the customer can access, what prices the customer will see, and for how long the customer has access to your site and those prices. All stores must contain at least one contract, because without a contract no one but internal administrators can access your store. WebSphere Commerce provides a default contract that applies to all customers shopping at a store. In WebSphere Commerce Professional Edition, the default contract is the only supported contract.
Service agreements: A service agreement with a business partner (business partners may be resellers, distributors, manufacturers, suppliers, or other partners) defines your arrangement with the business partner. For example a service agreement with a reseller may define what access the reseller has to your site, whether they can share your catalog, or whether you host a store for them. A service agreement with a distributor may define how customers to your site can receive quotes from a distributor, or how customers can access the distributor’s site from yours.

Terms and conditions Terms and conditions define how contracts and service agreements are implemented for a particular customer or business partner. For contracts, terms and conditions may define what is being sold under the contract, the price of the items being sold, how the items are shipped to the customer, and how the customer pays for the order. For service agreements with business partners, terms and conditions may restrict the products the business partner is allowed to sell. Terms and conditions usually reference business policies, since most aspects of a site or stores operations are defined by business policies. Terms and conditions

Chapter 3. Business and store models

77

provide standard parameters for the business polices they reference. Providing parameters to the business policies allows you to modify the behavior of business policies for each contract.

3.3 Store architecture As IT architects and IT specialists, it is great to build a scalable and secure runtime, but if you do not have an online store that customers are happy with, the rest is pointless. After all, e-commerce is focused around selling goods and services from the online store. In this section, we explore store architecture, including the assets of a store, sample store models and packaging, store data assets, customizing a store, and options for publishing a store to the runtime environment. Note: For more detailed information on the WebSphere Commerce store architecture, understanding the contents of a store, and developing a store, we strongly recommend that you refer to the Store Development Guide, IBM WebSphere Commerce V5.5 product guide. This section includes the following topics on the WebSphere Commerce store:









Store assets Store architecture Store packaging and models Store data assets and architecture Catalog data assets and concepts Tools and store data Customize a store Publish a store

3.3.1 Store assets At the highest level, the store assets can be categorized as follows:
Store front assets These are the store pages displayed to a customer. The store front content includes HTML pages, JSPs, images, and multimedia files. The majority of the store pages use JavaServer Page technology (JSP). Each JSP contains HTML static content for headings, descriptions, etc. In addition, the JSPs contain JavaScript to provide client-side input checking and more sophisticated display features. JSPs also include URLs to invoke WebSphere Commerce commands and other views, as well as JSP tags and Java code

78

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

for generating dynamic content. WebSphere Commerce data beans are included within the JSPs to allow access to information from the store database. The results of the access, such as product price or product attributes, are displayed on the store page (JSP).
Back office assets (business logic) The back office assets contain the business logic for the store that customers do not see directly. These assets include WebSphere Commerce commands and tasks implemented through Java servlets and EJBs.
Store data This includes all of the data related to your store, including product catalog data, tax and shipping information, payment methods, etc. In addition, this includes some configuration data used to manage your store.

3.3.2 Store architecture This section describes the store architecture for the WebSphere Commerce Server instance, WebSphere Commerce Server, and store configuration scenarios.

WebSphere Commerce Server instance WebSphere Commerce Server instance is used to host a WebSphere Commerce store or multiple stores. All stores within a WebSphere Commerce instance share the same WebSphere Commerce instance database and may share some types of data such as the catalog and fulfillment methods. All stores within the instance also share the same EJB container. When a WebSphere Commerce instance is created, the Configuration Manager creates an application server within the WebSphere Application Server for the instance. In addition, during instance creation an instance directory and subdirectories are created for instance configuration files and log files.

WebSphere Commerce Server The WebSphere Commerce Server is an enterprise application deployed to its own application server that provides the infrastructure and functionality for the e-commerce solution. The store assets are deployed and hosted by the WebSphere Commerce Server (running as an application server on the WebSphere Application Server).

Chapter 3. Business and store models

79

Store configurations As noted above, a WebSphere Commerce instance can host a single store or multiple stores. We discuss several combinations of configurations for stores:
Single store in an instance
Multiple stores in an instance with non-shared resources
Multiple stores in an instance with sharing resources

Single store in an instance Figure 3-11 depicts a single store published in a WebSphere Commerce instance. The three asset types are noted in Figure 3-11, including store front, back office (business logic), and store data.

Store front

Single store in an instance

Store 1 Web assets

Business logic

Store data

Store 1 logic Store 1catalog Store 1 orders

Store 1 Web assets

Store 1 logic

Store 2 Web assets

Store 2 logic

Multiple stores in an instance

Store 1 catalog and orders Store 2 catalog and orders

Figure 3-11 Single store in an instance, multiple stores in an instance

Multiple stores in an instance with non-shared resources Figure 3-11 also depicts multiple stores published in a WebSphere Commerce instance. In this example, each store has its own store front, business logic, and store data.

Multiple stores in an instance with sharing resources Figure 3-12 on page 81 depicts multiple stores published in a WebSphere Commerce instance with several examples of how resources can be shared. For

80

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

example, stores can share store front assets, business logic, and the product catalog, or any combination of the asset types. Multiple stores can exist in a single stores Web module. If so, the store assets are separated using the following methods:
Store front assets: Store front assets for each store in the stores Web module are stored in a separate store directory (storedir). For example, all store front assets for MyStore are in the MyStore directory.
Business logic: The store ID is used to select the command implementation for each store, as specified in the command registry.

Store front

Store 1 Multiple stores in an instance sharing a store front

Store data

Store 1 logic

Shared store front

Store 2

Store 2 logic

Store 1 Web assets

Store 1 logic

Multiple stores in an instance sharing business logic

Multiple stores in an instance sharing catalog data

Business logic

Shared logic

Store 2 Web assets

Store 2 logic

Store 1 Web assets

Store 1 logic

Store 2 Web assets

Store 2 logic

Store 1 catalog and orders Store 2 catalog and orders

Store 1 catalog and orders Store 2 catalog and orders

Shared catalog data

Shared catalog Store 1 orders Store 2 orders

Figure 3-12 Multiple stores in an instance sharing resources

Chapter 3. Business and store models

81

3.3.3 Store packaging and models A store archive (or SAR) file is a zip file used for the packaging and delivery of WebSphere Commerce sample stores. A store archive can contain the following types of assets:
Store presentation assets (JSP, images, HTML, properties files)
Store data and configuration assets (catalog, tax, shipping, contract, flow configuration, all in XML format)
Descriptors that describe contents and control store publishing A store archive can be deployed or published to the runtime using the Publish Tool available from the WebSphere Commerce Administration Console. In previous releases, this functionality was provided from Store Services (discontinued). The topic of store publishing is further discussed in 3.3.8, “Publish a store” on page 97. In WebSphere Commerce V5.5, there are new types of store archives to allow for a more modular approach to store publishing. The store archive containing all assets, which is similar to previous releases, is known as a composite store archive. In addition to the composite store archives (all assets), there is now the concept of component store archives containing a subset of store function that can be published separately. All of the store archives include globalization support for the locales listed in Table 3-2. By default, the store will use the locale of the WebSphere Commerce instance. Table 3-2 WebSphere Commerce store archive supported locales

82

Locale

Language and Territory

langId

en_US

English US

-1

fr_FR

French France

-2

de_DE

German Germany

-3

it_IT

Italian Italy

-4

es_ES

Spanish Spain

-5

pt_BR

Portuguese Brazil

-6

zh_CN

Simplified Chinese China

-7

zh_TW

Traditional Chinese Taiwan

-8

ko_KR

Korean Korea

-9

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Locale

Language and Territory

langId

ja_JP

Japanese Japan

-10

The following sections describe the store archives included with WebSphere Commerce Business Edition:







Consumer direct store archives Consumer direct basic store archive B2B direct store archives Hosting store archives Demand Chain store archives Supply Chain store archives

Consumer direct store archives Table 3-3 provides a listing of the consumer direct store archive names and a brief description of the contents of the store archive. Table 3-3 Consumer direct store archives Store archive name

Description

ConsumerDirect.sar

A sample composite store archive containing the organization structure, predefined user roles, and necessary access control policies to create consumer direct environment, plus a feature-rich working store.

ConsumerDirectOrganizationStructure.sar

A sample store archive containing the organization structure, predefined user roles, and necessary access control policies to create a consumer direct environment.

ConsumerDirectStore.sar

A sample store archive containing all the necessary assets to create a feature-rich working Consumer Direct store.

Consumer direct basic store archive The consumer direct basic store archive (ConsumerDirectBasicStore.sar) is a scaled-down store archive to be used for the development of a store from scratch. It contains the required elements of a store archive, such as one currency, one supported language, one fulfillment, store default contract, one category, one product, simple store front and shopping flow, which includes shopping cart and checkout. By default, the consumer direct basic store archive is not listed from the WebSphere Commerce Administration Console under the Publish menu where other stores are listed.

B2B direct store archives Table 3-4 on page 84 provides a listing of the B2B direct store archive names and a brief description of the contents of the store archive.

Chapter 3. Business and store models

83

Table 3-4 B2B direct store archives Store archive name

Description

B2BDirect.sar

A sample composite store archive containing the organization structure, predefined user roles, and necessary access control policies to create business direct environment, plus a feature-rich working store.

B2BDirectOrganizationStructure.sar

A sample store archive containing the organization structure, predefined user roles, and necessary access control policies to create a B2B direct environment.

B2BDirectSite.sar

A sample store archive containing all the necessary assets to create a feature-rich working B2B direct store.

When publishing the composite store archive (BusinessDirect.sar), all displayed items in Figure 3-13, except root organization and default organization, will be published. The root organization and default organization are created in bootstrap data. The items included in each component store archives are noted in the legend.

o=Root Organization

o=Default Organization

o=Seller Organization

o=Buyer A Organization

ou=B2B

BusinessDirectOrganizationStructure.sar BusinessDirectSite.sar B2B Store

Figure 3-13 B2B direct store archives

84

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Hosting store archives Table 3-5 provides a listing of the hosting store archive names and a brief description of the contents of the store archive. Table 3-5 Hosting store archives Store archive name

Description

Hosting.sar

Contains the organization structure, predefined user roles, and necessary access control policies to create a reseller hosting environment, plus the necessary assets to create a hosting solution, including a service provider site, store directory, shared catalog, and seller stores.

CatalogAssetStore.sar

A sample store archive containing all the necessary assets to create a shared catalog.

HostedStoreFrontAssetStore.sar

Contains all the necessary assets to create a store front.

HostingHub.sar

Contains all the necessary assets to create the hub site.

HostingOrganizationStructure.sar

Contains the organization structure, predefined user roles, and necessary access control policies to create a hosted environment.

StoreDirectory.sar

Contains all the necessary assets to create a navigable directory of all stores available in the site.

Demand Chain store archives Table 3-6 provides a listing of the Demand Chain store archive names and a brief description of the contents of the store archive. Table 3-6 Demand Chain store archives Store archive name

Description

DemandChain.sar

A sample composite store archive containing the organization structure, predefined user roles, and necessary access control policies to create a Demand Chain environment, plus the necessary assets to create a Demand Chain solution, including a channel hub site, shared catalog, and reseller and distributor stores.

CatalogAssetStore.sar

A sample store archive containing all the necessary assets to create a shared catalog.

ChannelHub.sar

A sample store archive containing all the necessary assets to create a hub site.

Chapter 3. Business and store models

85

Store archive name

Description

DemandChainOrganizationStructure.sar

A sample store archive containing the organization structure and predefined user roles to create a Demand Chain environment.

DistributorAssetStore.sar

Contains all the necessary assets to support distributor proxy stores.

DistributorProxyOrganizationStructure.sar

A sample store archive containing the organization structure and predefined user roles to create top level organization structure for the distributor proxy stores.

ResellerStorefrontAssetStore.sar

Contains all the necessary assets to create a reseller store front.

Supply Chain store archives Table 3-7 provides a listing of the Supply Chain store archive names and a brief description of the contents of the store archive. Table 3-7 Supply Chain store archives Store archive name

Description

SupplyChain.sar

Contains the organization structure, predefined user roles, and necessary access control policies to create a supply chain environment.

CatalogAssetStore.sar

Contains all the necessary assets to create a shared catalog.

SupplierAssetStore.sar

Contains all the necessary assets to create a supplier store front.

SupplierHub.sar

Contains all the necessary assets to create a supplier hub site.

SupplyChainOrganizationStructure.sar

Contains the organization structure, predefined user roles, and necessary access control policies to create a supply chain environment.

3.3.4 Store data assets and architecture Store data is the information loaded into the WebSphere Commerce instance database thatallows your store to function. In order to operate properly, a store must have the data in place to support all customer activities. For example, in order for a customer to make a purchase, your store must contain a catalog of goods for sale (catalog data), the data associated with processing orders (tax

86

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

and shipping data), and the inventory to fulfill the request (inventory and fulfillment data).

Store data assets Figure 3-14 contains a summary of the store data assets. For more detailed information refer to the Store Development Guide, IBM WebSphere Commerce V5.5 product guide.

Prices

Catalogs

Business Policies

Site Level Information

Contracts and Accounts

Members

URL Registry Entries

Payment

View Registry Entries

Fulfillment

Command Registry Entries

Inventory Stores

Supported Units of Measure

Orders

Supported Languages

Jurisdictions

Supported Currencies

Taxes

Store Relationships

Shipping

Discounts

Coupons

Campaigns

Customer Profiles

Figure 3-14 WebSphere Commerce store data assets

Chapter 3. Business and store models

87

Store data architecture Data in WebSphere Commerce stores conforms to the architecture depicted in Figure 3-15. The store data assets can be categorized as follows:






WebSphere Commerce Server instance data Core data Configuration data Managed data Operational data

Operational data

Managed data

Configuration data

Sample store archive

Core data

WebSphere Commerce Server instance data

Figure 3-15 Store data architecture

WebSphere Commerce Server instance data The WebSphere Commerce Server instance data is identified as site-level information. When an instance is created, the bootstrap files (XML format) are used to populate the database. The following information is available at the site level and can be shared among multiple stores:
Calculation usage types, device types (Web browsers, mobile device, e-mail, etc.) message types, roles and addresses
The default site administrator ID (user defined as instance creation)
The default URLs, commands, and views

88

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide













The default business policies The default groups and access control policies The language and currency supported by the instance The default quantity units and quantity unit conversions The default scheduled jobs and statecodes The default terms and conditions The default organization, which can be used as the store owner The default site organization The default store group The default information for staging

Core data Core data represents the minimum data needed for a store. This type of data is typically packaged within the store archive file and is further categorized by organization and store.
Organization The organization core data creates the minimum data for the business model (root organization and default organization within the bootstrap data). The organization data is found in the composite store archives and the component store archive for the organization structure. – Organizational structure – Predefined user roles – Necessary access control policies
Store The store data is found in the composite store archives and the component store archive for the store data. – The store identifier in the STOREENT table. This creates a store in the database. – The default contract. – The store identifier in the contract database tables. – The member identifier for the organization that owns the store in the contract database tables. – The store directory in the STORE table. The store directory is the directory in which the store’s Web assets are located. – The nickname or identifier for the store’s address in the STADDRESS table. The nickname is unique for each store.

Chapter 3. Business and store models

89

Configuration data The following configuration data can be set at both the site and store level. The configuration data provides the Web Controller with runtime information for the appropriate commands and views to be invoked in response to each possible service request:
URL registry entries, which map URL requests into command invocations.
Command registry entries, which basically provide the command implementation class.
View registry entries, which map the view names returned by commands with view commands and related JSP templates, based both on the store ID and on the requesting device type.

Managed data The following is a list of managed data created by the sellers, with read-only access for customers (note that store-specific assets have been specified):





















Business policies Campaigns Catalogs Contracts Coupons Currencies (store specific) Customers Discounts (store-specific) E-mail activity Fulfillment centers Inventory Jurisdictions (store-specific) Languages (store specific) Members Payment Prices Sellers Taxes (store-specific) Shipping (store-specific) Supported units of measure (store-specific)

Operational data The following data can be created and changed, directly or indirectly, by interacting with the site. Such interactions can be performed both by customers and by sellers (note that, in this last case, operational data resulting from a particular type of interaction can be customers themselves):
Auctions

90

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide










Contracts Customers E-mail activity Fulfillment Inventory (store-specific) Orders (store-specific) Request for quotes (RFQ)

3.3.5 Catalog data assets and concepts The WebSphere Commerce database schema has a rich environment to support a very advanced product catalog. In 3.3.4, “Store data assets and architecture” on page 86, we described the XML representation of data to be imported into the WebSphere Commerce instance database. The primary tools used to manage catalog data in WebSphere Commerce V5.5 are the WebSphere Commerce Accelerator Product Management tool and the Loader Package. This section defines the key catalog concepts for data stored in the WebSphere Commerce instance database. Figure 3-16 depicts the catalog hierarchy of the master catalog, catalog groups, products, and SKUs.

Apparel Master Catalog

Men

Women

Pants

Jeans

Outerwear

Corduroy

Jacket

Topcoat

Sweaters

Turtleneck

Twin set

Skirts

Mid-length

Mini

Master catalog Catalog groups Products SKUs

Figure 3-16 Catalog hierarchy (master catalog, catalog groups, products, SKUs)

Chapter 3. Business and store models

91

Master catalog The catalog object is the root of a catalog for both master catalogs and navigational catalogs. The catalog contains all the hierarchical and navigational information for the catalog. The reference identifier is used in all business objects that define the relationship of catalog groups and catalog entries. The database table for catalog is named CATALOG.

Navigational catalog Navigational catalogs allow for organizing the products differently from the way they are defined in the master catalog in order to catalog data for different types of shoppers.

Catalog group The catalog group object is used to organized the catalog and help shoppers to navigate to the products they wish to view. A catalog group may contain other catalog group,s as seen in Figure 3-16 on page 91. Catalog groups are often referred to as categories. The database table for catalog group is named CATGROUP.

Catalog entry A catalog entry object represents merchandise in the catalog that can be ordered from the catalog. There are four different types of catalog entries, which can be identified by the value of catenttype_id in CATENTRY, including product, SKU (item), bundle, and kit.

Product A product represents a collection of SKUs (items) that have identical attributes but can be distinguished by their attribute values. For example, a catalog may contain a shirt that is available in different sizes (small, medium, large) and colors (red, white, blue).

Attributes (defining and descriptive) A catalog entry can have defining and descriptive attributes. Defining attributes are properties of SKUs such as color or size. Attribute values for a color attribute, for example, are colors such as red, white and blue. Descriptive attributes are simply additional descriptive information, such as cleaning information (dry clean only, etc.). Each unique attribute value combination is used to define the item. Collectively, SKUs can be displayed as a single product with a single price, description, and image as long as a given shopper is given the opportunity to select the size and color values necessary to resolve the selection to a single SKU.

92

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

SKU SKUs and items are synonymous. A SKU represents a tangible unit of merchandise that can be purchased by a shopper. SKUs are products with a unique combination of defining attribute values.

Bundle A bundle is a collection of catalog entries that can be added to the shopping cart with a single selection. It is typically used as a convenient method of packaging items for the shopper to order a collection of items. Bundled items can be sold separately. For example, a bundle may be a computer bundle (system, monitor and printer). The price of the bundle is the collective price of each item.

Pre-built kit A pre-built kit is a collection of catalog entries that cannot be sold separately. For example, the system component of a computer includes a motherboard, hard disk, memory, video adapter, CPU case, CD-ROM, etc. Items such as a motherboard or CPU may not be offered as individual items for purchase. A pre-built kit often has its own price. A pre-built kit can be added to the shopping cart by one selection. Similar to a product, pre-built kits can have defining attributes. Once a pre-built kit is added to the shopping cart, it cannot be modified (it must be removed, attributes reselected, and added again to the cart). In previous releases of WebSphere Commerce, a pre-built kit was known as a package.

Static kit A static kit is a group of products that are ordered as a unit. The information about the products contained in a static kit is predefined and controlled within WebSphere Commerce. The individual components within the order cannot be modified and must be fulfilled together. A static kit will be back-ordered if any of its components are unavailable.

Dynamic kit A dynamic kit is an orderable SKU that consists of one or more SKUs, or components. The definition of the components that make up the kit is not known until the kit is ordered and configured, hence the name dynamic kit.

3.3.6 Tools and store data This section provides a summary of the tools used to manage the store data, including the XML data files before being loaded in the WebSphere Commerce instance, as well as to manage the data once in the instance database.

Chapter 3. Business and store models

93

The primary tools used to manage store data are as follows:






WebSphere Commerce Studio WebSphere Commerce Loader Package WebSphere Commerce Administration Console WebSphere Commerce Organization Administration Console WebSphere Commerce Accelerator

WebSphere Commerce Studio The IBM WebSphere Commerce Studio V5.5 includes IBM WebSphere Studio Application Developer V5. WebSphere Studio Application Developer includes an XML editor that is very useful when modifying the contents of the XML data files packaged as part of the store archive. For more detailed information on modifying the XML data files using the WebSphere Commerce Studio when creating a customized store, refer to Chapter 12, “Create a store” on page 341.

WebSphere Commerce Loader Package The WebSphere Commerce Loader Package is used to aggregate, transform, resolve, and load XML data files into the WebSphere Commerce instance database. The XML data files the Loader Package operates on are packaged with the sample store archives. In addition, the Loader Package utilities can be run via the command line or from a Java API. When a WebSphere Commerce store is published using the WebSphere Commerce Administration Console Publish Tool, the Loader Package utilities are executed in the background to resolve and load the XML data files into the WebSphere Commerce instance database. The Loader Package includes the following utilities:
Text Transformation Tool: Convert CSV into an XML file, and transform XML into a WebSphere Commerce XML file.
XSL Editor: The XSL editor is used to create and develop the XSL style sheets, which are used to transform (map) the XML data.
XML Transformation Tool: This transforms the XML data using the XSL style sheets into WebSphere Commerce XML files.
DTD Generator: This tool uses an input file containing database table names and generates either a DTD or an XML schema to describe the select database tables.
ID Resolver: Resolve IDs within the database with data to be loaded.

94

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


Loader: After ID resolution, the resolved XML data files are imported into the WebSphere Commerce instance database using the Loader, also known as the MassLoad utility.
Extractor: Used to extract data in the WebSphere Commerce instance database to an XML file.

WebSphere Commerce Administration Console The WebSphere Commerce Administration Console allows you to control your site or store by completing administrative operations and configuration tasks. You can also use the Administration Console to create new organizations and users, as well as assign users to roles. The Administration Console also allows you to identify which notification and messaging types will be available in your store. The Administration Console contains the publish utility, which allows you to publish sample business and stores.

WebSphere Commerce Organization Administration Console The Organization Administration Console allows you and the buyer administrators to control the organizations that access your site or store. Tasks that you are authorized to perform in your role are displayed on the Organization Administration Console home page menus. These tasks are based on user roles and authority levels, which are defined in XML files on your WebSphere Commerce system and are assigned by the Site Administrator using the Administration Console.

WebSphere Commerce Accelerator The WebSphere Commerce Accelerator is a workbench of online tools that allow you to create and maintain various store assets. A large portion of store data can be created and managed using the Product Management Tool found in the WebSphere Commerce Accelerator.

Summary of tools used to manage store data Table 3-8 provides a summary of the WebSphere Commerce tools used to manage store data, including XML data files before load and store data found in the WebSphere Commerce instance database. Table 3-8 Tools used for creating store data Tools to manage and customize store data WebSphere Commerce Studio (WebSphere Studio Application Developer)

Core data

Configuration data

Managed data

Operational data

Applicable

Applicable

Applicable

In general, not applicable.

Chapter 3. Business and store models

95

Tools to manage and customize store data

Core data

Configuration data

Managed data

Operational data

WebSphere Commerce Loader Package (data is loaded in the form of an XML file)

Applicable.

Applicable.

Applicable.

In general, not applicable.

WebSphere Commerce Administration Console

Applicable * Publish store

Not applicable.

Not applicable.

Not applicable.

WebSphere Commerce Organization Administration Console (Business Edition)

Not applicable.

Not applicable.

Not applicable.

The organization Administration Console allows you to create and approve buyers.

WebSphere Commerce Accelerator

Not applicable.

Not applicable.

The accelerator allows you to create and edit the following data:
Campaigns
Contracts
Fulfillment
Discounts
Catalog
Prices

The accelerator allows you to create operational data for a customer, such as orders, and to manage the inventory.

3.3.7 Customize a store Chances are that one of the sample stores will provide a head start to customizing a store for your needs. However, you may need to customize and add new Web assets, business logic, and your own store data. This is referred to as customizing a store. The easiest and quickest method for store customization is to start with a sample store archive that best matches your needs. You will need to understand the programming model of WebSphere Commerce V5.5 and how to use the development tools included in WebSphere Commerce Studio V5.5 to customize your store. Note: We strongly recommend that you read the Store Development Guide, IBM WebSphere Commerce V5.5 product guide for detailed information.

96

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

To find more information, refer to the following:
Store development – Chapter 12, “Create a store” on page 341 – Store Development Guide, IBM WebSphere Commerce V5.5 product guide – Sample Store Guide, IBM WebSphere Commerce V5.5 redbook
Overview of the WebSphere Commerce programming model – Chapter 4, “Programming model” on page 109
Detailed description of the WebSphere Commerce programming model – Programmer’s Guide, IBM WebSphere Commerce V5.4 product guide

3.3.8 Publish a store In WebSphere Commerce V5.5, stores are published by selecting the Store Archive -> Publish menu option found in the WebSphere Commerce Administration Console. In previous versions of WebSphere Commerce, store publishing was performed from Store Services, which has been discontinued. In addition, in previous versions the store archive was created from a sample store and then published. The generated store archive needed to be maintained. In WebSphere Commerce V5.5, the store archive is used to publish the store (there is no longer an intermediate step of creating a store archive from the sample store archive and then publishing).

Publish store from a user perspective This section describes the steps taken by a user to publish a store archive. The publish store functionality is found in the WebSphere Commerce Administration Console by selecting Store Archive -> Publish, as seen in Figure 3-17 on page 98.

Chapter 3. Business and store models

97

Figure 3-17 Administration Console: Store Archive -> Publish

The next page to be displayed when publishing a store is a list of the sample store archives. A view pull-down is preset to Default, which lists the composite store archives for the store models (see Figure 3-18 on page 99).

98

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Figure 3-18 Store publish default view (composite store archives)

After you have checked the store archive to publish and clicked Next, you will see a parameters page (see Figure 3-19 on page 100), which is new to WebSphere Commerce V5.5. The store archives can be constructed to allow for parameters to be supplied at the time of publishing. The composite store archive parameters are set to read only (visible but cannot be changed). The component store archives parameters allow for modification. For the purposes of illustration, we checked the ConsumerDirectSite.sar to display the parameters page with fields that can be modified by the user at publish time. Note: We discuss modifying the store parameters in detail in Chapter 12, “Create a store” on page 341. In our example, we provide a working example for adding parameters and changing the existing parameters from read only to a user-driven setting for the ITSO composite store archive.

Chapter 3. Business and store models

99

Figure 3-19 Parameters page for the ConsumerDirectSite.sar

When the user clicks Finish to begin publishing the store archive, the publishing runs as a scheduled job via the WebSphere Commerce scheduler. The status of the job can be monitored by clicking Store Archive -> Publish Status from the WebSphere Commerce Administration Console.

Technical details of store publish There are many new features provided in the store archives and the publishing tools. The ITSO working example for creating a store provides step-by-step examples for many of the features. For details, refer to Chapter 12, “Create a store” on page 341. This section includes the following technical details on store publishing:








100

Register a store archive Publish parameters Unpack store archive during store publish Instantiation during publising Schedule job for store publish Execute publish job Data considerations

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


Troubleshooting store publishing

Register a store archive There are two methods a store archive can be registered and become visible from the WebSphere Commerce Administration Console using the Store Archive -> Publish menu option.
Copy the store archive to the \instances\\sar directory and it will be displayed in the Administration Console.
Update the SARRegistry.xml found in the \xml\tools\devtools directory to include the path of the store archive file, and preview HTML. All sample store archives are found in \samplestores\ directories. Example 3-1 contains a portion of the SARRegistry.xml for the ConsumerDirect.sar for reference. Example 3-1 SARRegistry.xml sample for the ConsumerDirect.sar





Publish parameters The following are a few files that are used for the store publish parameters:
store-refs.xml – Descriptor file contained within the store archive – Allows for customizing publish parameters – Optionally edit when customizing/creating a store archive
ForeignKeys.dtd – Contains the property name-value pairs needed to create a new store based on the store archive
publishNLS.properties – Contains translatable text for the description of the store archive – Contains parameter names and descriptions displayed on the publish parameters page

Chapter 3. Business and store models

101

Figure 3-20 provides samples for the store-refs.xml, ForeignKeys.dtd and publishNLS.properties to highlight the relationship between the files. Sample From Parameter Page WEB-INF/stores/FashionFlow/data/ForeignKeys.dtd

SAR-INF/store-refs.xml

%ForeignKeys.dtd;



store-data-assets.xml



&store.xml; &en_US_store.xml; &catalog.xml; &en_US_catalog.xml;

Figure 3-21 Sample store-data-assets.dtd and store-data-assets.xml

Troubleshooting store publishing This section includes the following key store publishing troubleshooting tips:
Standard logging and tracing facilities used by WebSphere Commerce (WebSphere Application Server logging facilities). – \logs\activity.log is a binary log file, viewed with LogAnalyzer – Trace string for publish: com.ibm.websphere.commerce.WC_DEVTOOLS=all=enabled – Refer to IBM WebSphere Commerce V5.5 online documentation for details and tips on troubleshooting Store Publish.
If an error occurs during the data loading phase of publishing, the error is displayed on the Publish Details page.
Tasks invoked during store publish (for example, IdResolver, ContractImport) may have their own trace.
Refer to the Store Development Guide, IBM WebSphere Commerce V5.5 for more information.

106

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

3.4 For more information For more information on the business models, sample stores and access control refer to the following:





Store Development Guide, IBM WebSphere Commerce V5.5 Sample Store Guide, IBM WebSphere Commerce V5.5 Security Guide, IBM WebSphere Commerce V5.5 WebSphere Commerce V5.5 online documentation

Chapter 3. Business and store models

107

108

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

4

Chapter 4.

Programming model The objective of this chapter is to provide an overview of the WebSphere Commerce programming model. Note: For detailed information on the WebSphere Commerce programming model, we strongly recommend that you refer to the Programming Guide and Tutorials, IBM WebSphere Commerce V5.5 product guide. The chapter includes the following topics:









Overview WebSphere Commerce Server framework Application flow of an HTTP request Design patterns Persistent object model Access control Customizing application assets For more information

© Copyright IBM Corp. 2003. All rights reserved.

109

4.1 Overview This section defines each of the following WebSphere Commerce application architectures layers, as seen in Figure 4-1:







Database Business objects Business components Controls and view Business processes Store models

Store Models

e-Commerce Business Models: e.g. Consumer Direct (B2C), B2B Direct, Hosting, Demand Chain, Supply Chain

Business Processes

SiteFlows/Workflows: e.g. User Registration, Catalog Navigation, Shopping/Purchasing, Order Processing

Control and Views

Business Components

Servlets/JSPs: e.g. ProductDisplay.jsp, ShoppingCart.jsp, LoginForm.jsp Command Beans and Rule Templates: e.g. OrderProcessCmd, DiscountRuleTemplate

Business Objects

Entity Beans, Access Beans, DataBeans: e.g. User, Order, Product

Database

Tables: e.g. USERS, ORDERS, CATENTRY

Figure 4-1 WebSphere Commerce application architecture

Database WebSphere Commerce uses a database schema designed specifically for e-commerce applications and data requirements. The database is known as the WebSphere Commerce instance database. The instance database is created by default via the WebSphere Commerce Configuration Manager when creating the WebSphere Commerce instance. The WebSphere Commerce instance database contains over 600 database tables, which are used to manage the operations of the WebSphere Commerce site and store. For example, information on customer profiles, taxes, orders, shipping and product catalog data are stored within the instance database. Some

110

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

examples of tables found in the WebSphere Commerce instance database are USERS, ORDERS, and INVENTORY.

Business objects Business objects represent entities within the commerce domain and encapsulate the data-centric logic required to extract or interpret information contained within the database. These entities comply with the Enterprise JavaBeans specification. These entity beans act as an interface between the business components and the instance database. In addition, the entity beans are easier to comprehend than complex relationships between columns in database tables.

Business components Business components are units of business logic. They perform coarse-grained procedural business logic. The logic is implemented using the WebSphere Commerce model of controller commands and task commands. An example of this type of component is the OrderProcess controller command. This particular command encapsulates all of the business logic required to process a typical order. The e-commerce application calls the OrderProcess command, which in turn calls several task commands to perform individual units of work. For example, individual task commands ensure that enough inventory is available to meet the requirements of the order, process the payment, update the status of the order and, when the process has completed, decrement the inventory by the appropriate amount.

Controls and view A Web controller determines the appropriate controller command implementation and view to be used. Implementations can be store specific. Views display the results of commands and user actions. They are implemented using JSP templates. Examples of views include ProductDisplayView (returns a product page showing relevant information for the shopper’s selected product) and OrderCancelView.

Business processes Sets of business components and views together create workflow and site flow processes that are known as business processes. Examples of business processes include:
Create an e-mail campaign This business process includes the business components and views related to all steps involved in the process of creating e-mail campaigns.

Chapter 4. Programming model

111


Prepare an online catalog This business process includes the business components and subprocesses related to creating an online catalog. This includes designing the catalog, loading catalog data, creating merchandising associations, and setting pricing information.

Store models When gathered together, the lower layers of the diagram make up e-commerce business models. Each of the business models supported in WebSphere Commerce includes a sample store model. The WebSphere Commerce Business Edition includes the following store models: consumer direct, B2B direct, hosting, Demand Chain, and Supply Chain.

4.2 WebSphere Commerce Server framework This section defines the component architecture of the WebSphere Commerce common server runtime, also known as the WebSphere Commerce Server framework. The WebSphere Commerce common server runtime provides a framework in which the commerce applications are deployed and executed. The framework is based on the Java 2 Enterprise Edition (J2EE) platform architecture. Such a framework provides the capability to handle system and user requests and to perform the corresponding actions in order to fulfill them.

112

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

WebSphere Commerce node WebSphere Application Server WebSphere Commerce Server framework

Thread Thread

Protocol Listeners

HTTP Request servlet

Database Server

Web Server + WebSphere Plugin

Servlet Engine

MQ Listener

.xml

Adapter Manager

Adapter framework

HTTP Browser Adapter

PVC Adapter

Program Adapter

Scheduler Adapter

Registries URL CMD View

Web Controller

JSP Template

Data bean

Task CMD

Controller Command View Command

Data bean commands

Task CMD

Task CMD

Access bean

Data Bean Manager

WebSphere Commerce instance database

Entity bean

Figure 4-2 WebSphere Commerce common server runtime component architecture

Chapter 4. Programming model

113

The major components of the common server runtime or framework are listed as follows and depicted in Figure 4-2 on page 113:












Servlet engine Protocol Listeners Adapter manager Adapters Web controller Commands Entity beans Data beans Data Bean Manager JavaServer Page (JSP) templates WebSphere Commerce .xml configuration file

4.2.1 Servlet engine The servlet engine is the part of the WebSphere Application Server runtime environment that acts as a request dispatcher for HTTP requests. The servlet engine manages a pool of threads to handle requests. Each inbound request is executed on a separate thread. The request is then sent to the appropriate protocol listener, in this case the HTTP request servlet.

4.2.2 Protocol Listeners Protocol listeners receive inbound requests based on the protocols and dispatch them to the adapter manager to find the appropriate adapter for the type of requesting device. WebSphere Commerce includes the HTTP request servlet and MQ listeners.

HTTP request servlet The HTTP request servlet handles incoming HTTP requests. When the HTTP request servlet is initialized, it reads the adapter section within the .xml configuration file to load the adapter settings. When the HTTP request servlet receives a URL request from the servlet engine, it passes the request to the adapter manager.

MQ listener The MQ listener receives requests for inbound XML-based MQ messages from remote programs and then sends the request to the MQ adapter to be processed.

114

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Request device types and sources WebSphere Commerce commands can be invoked as the result of requests from various device types, such as the following:






Web browser client Mobile device with a Web browser (mobile phone, PDA, etc.) B2B application sending XML messages using MQ Procurement system sending requests using XML over HTTP WebSphere Commerce scheduler executing a background job

4.2.3 Adapter manager The adapter manager analyzes the contents of the HTTP header for the User Agent to determine the appropriate adapter to send the request.

4.2.4 Adapters Adapters are device-specific components that enable WebSphere Commerce to perform processing functions before passing on the request to the Web controller. Adapter are responsible for the following tasks:
Instruct the Web controller to process the request in a manner specific to the type of device.
Translate the message from the device-specific format into a WebSphere Commerce common format (that is, a CommandProperty object).
Provide device-specific session persistence. Adapters provided by WebSphere Commerce are as follows:





HTTP browser adapter HTTP PVC adapter Program adapter Scheduler adapter

HTTP browser adapter The HTTP browser adapter provides support for requests to invoke WebSphere Commerce commands received from Web browser clients (HTTP).

HTTP PVC adapter The HTTP PVC adapter is an abstract adapter class that can be used to develop specific PVC adapters, such as a WAP PVC adapter or Portal adapter.

Chapter 4. Programming model

115

Program adapter The program adapter provides support for remote programs to invoke WebSphere Commerce commands. The program adapter receives requests and uses a message mapper to convert the request into a CommandProperty object. After conversion, the program adapter uses the CommandProperty object and executes the request.

Scheduler adapter The scheduler adapter provides support for WebSphere Commerce commands that are run as background jobs. Note: If required, the adapter framework can be extended to create new PVC adapters or to create new adapters that connect to new protocol listeners.

4.2.5 Web controller The WebSphere Commerce Web controller is an application container that follows a design pattern similar to that of an EJB container. This container 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 also plays a role in enforcing the programming model for the commerce application. For example, the programming model defines the types of commands that an application should write. Each type of command serves a specific purpose. Business logic must be implemented in controller commands and view logic must be implemented in view commands. The Web controller expects the controller command to return a view name. If a view name is not returned, an exception is thrown. For HTTP requests, the Web controller performs the following tasks:
Begins the transaction using the UserTransaction interface from the javax.transaction package.
Gets session data from the adapter.
Determines whether the user must be logged on before invoking the command. If required, it redirects the user’s browser to a logon URL.
Checks if secure HTTPS is required for the URL. If it is required but the current request is not using HTTPS, it redirects the Web browser to an HTTPS URL.
Invokes the controller command and passes it the command context and input properties objects.

116

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


If a transaction rollback exception occurs and the controller command can be retried, it retries the controller command.
A controller command normally returns a view name when there is a view command to be sent back to the client. The Web controller invokes the view command for the corresponding view. There are a number of ways to form a response view. These include redirecting to a different URL, forwarding to a JSP template, or writing an HTML document to the response object.
Saves the session data.
Commits the session data.
Commits the current transaction if it is successful.
Rolls back the current transaction in case of failure (depending upon circumstances).

4.2.6 Commands WebSphere Commerce commands are beans that contain the programming logic associated with handling a particular request. There are four main types of WebSphere Commerce commands:





Controller command Task command Data bean command View command

Controller command A controller command encapsulates the logic related to a particular business process. Examples of controller commands include the OrderProcessCmd command for order processing and the LogonCmd that allows users to log on. 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 command and executes the view command.

Task command 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 4. Programming model

117

Data bean command A data bean command is invoked by the data bean manager when a data bean is instantiated. The primary function of a data bean command is to populate the data bean with data.

View command A view command composes a view as a response to a client request. There are three types of view commands:
Redirect view command: This view command sends the view using a redirect protocol, such as the URL redirect. A controller command should return a view command in this view type to return a view using a redirect protocol. When a redirect protocol is used, it changes the URL stacks in the browser. When a reload key is entered, the redirected URL executes instead of the original URL.
Direct view command: This view command sends the response view directly to the client.
Forward view command: This view command forwards the view request to another Web component, such as a JSP template. There are three ways in which a view command can be invoked:
A controller command specifies a view command name when the request has successfully completed.
A client requests a view directly.
A command detects an error and an error task must be executed to process the error. The command throws an exception with a view command name. When the exception propagates to the Web controller, it executes the error view command and returns the response to the client.

4.2.7 Entity beans Entity beans are the persistent, transactional commerce objects provided by WebSphere Commerce. If you are familiar with the commerce domain, entity beans represent WebSphere Commerce data in an intuitive way. That is, rather than having to understand the whole database schema, you can access data from an entity bean that more closely models concepts and objects in the commerce domain. You can extend existing entity beans. In addition, for your own application-specific business requirements, you can deploy entirely new entity beans. Entity beans are implemented according to the Enterprise JavaBeans (EJB) component model.

118

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

4.2.8 Data beans Data beans are Java beans that are primarily used by Web designers. Most commonly, they provide access to a WebSphere Commerce entity. A Web designer can place these beans on a JSP template, allowing dynamic information to be populated on the page at display time. The Web designer need only understand what data the bean can provide and what data the bean requires as input. Consistent with the theme of separating display from business logic, there is no need for the Web designer to understand how the bean works.

4.2.9 Data Bean Manager WebSphere Commerce data beans inserted into JSP templates allow for the inclusion of dynamic content in the page. The data bean manager activates the data bean so that its values are populated when the following line of code is inserted into the page: com.ibm.commerce.beans.DataBeanManager.activate(data_bean, request)

Where data_bean is the data bean to be activated and request is an HTTPServletRequest object.

4.2.10 JavaServer Page (JSP) templates JSP templates are specialized servlets that are typically used for display purposes. Upon completion of a URL request, the Web controller invokes a view command that invokes a JSP template. A client can also invoke a JSP template directly from the browser without an associated command. In this case, the URL for the JSP template must include the request servlet in its path, so that all of the data beans required by a JSP template can be activated within a single transaction. The request servlet can forward a URL request to a JSP template and execute the JSP template within a single transaction. The data bean manager rejects any URL for a JSP template that does not include the request servlet in its path.

4.2.11 WebSphere Commerce .xml configuration file The WebSphere Commerce .xml configuration file contains the configuration settings for the WebSphere Commerce instance, and is read when the HTTP request servlet is initialized.

Chapter 4. Programming model

119

4.3 Application flow of an HTTP request This section contains a description of the application flow of an HTTP request from a Web browser client to the WebSphere Commerce node to explain how the components interact. The following information corresponds to the detailed flow of an HTTP request from a Web browser client product category display, as seen in Figure 4-3 on page 121: 1. The request is directed to the servlet engine by the WebSphere Application Server plug-in. 2. The request is executed in its own thread. The servlet engine dispatches the request to the HTTP request servlet protocol listener. 3. The HTTP request servlet protocol listener passes the request to the adapter manager. 4. The adapter manager determines which adapter is capable of handling the request and then forwards the request to the appropriate adapter. For example, if the request came from a Web browser, the adapter manager forwards the request to the HTTP browser adapter. 5. The adapter passes the request to the Web controller. 6. The Web controller determines which command to invoke, by querying the command registry. 7. Assuming that the request requires the use of a controller command, the Web controller invokes the appropriate controller command. 8. Once a controller command begins execution, there are two possible paths: – The controller command can access the database using an access bean and its corresponding entity bean. – The controller command can invoke one or more task commands. Then task commands can access the database, using access beans and their corresponding entity beans. 9. Upon completion, the controller command returns a view name to the Web controller. 10.The Web controller looks up the view name in the VIEWREG table. It invokes the view command implementation that is registered for the device type of the requester. 11.The view command forwards the request to a JSP template. 12.Within the JSP template, a data bean is required to retrieve dynamic information from the database. The data bean manager activates the data bean.

120

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

WebSphere Commerce node WebSphere Application Server

15

Protocol Listeners

Servlet Engine

2

Thread

HTTP Request servlet

Thread

Database Server

1

WebSphere Commerce Server framework

Web Server + WebSphere Plugin

Web browser client request

MQ Listener

3 .xml

Adapter Manager

Adapter framework

4 HTTP Browser Adapter

PVC Adapter

Program Adapter

Scheduler Adapter

6

Registries

URL CMD View

Web Controller

9

JSP Template

7

10 8b

Access bean

11

extends

Data bean

View Command

Data bean commands

12

Controller Command

8a

Task CMD Task CMD

Task CMD

8c Access bean

13 Data Bean Manager

14

WebSphere Commerce instance database

Entity bean

Figure 4-3 Application flow of an HTTP request

13.The data bean manager invokes a data bean command, if required. 14.The access bean from which the data bean is extended accesses the database using its corresponding entity bean.

Chapter 4. Programming model

121

15.The JSP writes a response, which is returned to the Web server. The Web server in turn relays that response to the Web browser client for the display of the category display page.

4.4 Design patterns This section includes design patterns for model-view-controller, commands, and display pages.

4.4.1 Model-view-controller design pattern One of the most important requirements for enterprise applications in general, and for online stores in particular, is the ability to fulfill service requests coming from different kinds of devices, each one characterized by a different type of user interface:
HTML pages for standard Web browser
WML or cHTML for mobile computing (PvC) devices
XML messages for business suppliers The Model-View-Controller design pattern provides J2EE applications with the possibility to always use the same functions and data, independently of the final user interface, by keeping separate the business and presentation logic. This separation, invented by Smalltalk and adopted by J2EE, makes supporting multiple types of clients much easier to implement, test, and maintain. In particular, the Model-View-Controller components are:
Model It contains all the business data and functions, but does not have any knowledge about the clients requesting them. The architecture is frequently improved by implementing a further subdivision of the model into: – The domain model, consisting only of the business data and of the logic to access it. In J2EE applications, the domain model is usually implemented by Enterprise JavaBeans and data beans. – The application model, consisting of the business processes that manipulate such data. Note that the application model knows what views must be invoked by the controller in order to display the results of its processes, but it doesn’t know anything about the type of the requesting device. In J2EE applications, the application model is usually implemented by Java beans that follow the command pattern.

122

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


Views They render data obtained by the model in a way more suitable to the requesting devices. In J2EE applications, views are often implemented as JavaServer Pages templates producing output in HTML, WML, or XML format.
Controllers They handle the application workflow by mapping service requests coming from user interfaces into actions to be performed by the model. When the results are available, they invoke the appropriate view in order to display them. In J2EE applications, controllers are usually implemented as servlets. Figure 4-4 illustrates how the Model-View-Controller design pattern is implemented by the WebSphere Commerce architecture. Model Task Command Controller Command

Invokes

Task Command

Invokes

Data Retrieval & Update

Task Command

Data Retrieval & Update

Controller Entities URL

Web Controller

Data Retrieval & Update Database

View

Data Retrieval

Invokes View Command

Data Bean

Forwards

JSP Template

Figure 4-4 WebSphere Commerce implementation of the MVC design pattern

Chapter 4. Programming model

123

4.4.2 Command design pattern Service requests coming from different types of devices are translated by adapters into a common format that can be understood and processed by WebSphere Commerce commands. Moreover, the Web controller translates a service request into an actual command invocation, based on the type of the requesting device and on the addressed store ID. Commands are objects that follow the Java bean naming conventions. They perform some piece of business logic by leveraging the WebSphere Application Server command framework, which is an implementation of the standard command design pattern characterized by:
Having both an interface and an implementation class for each command.
Using a command factory in order to map the interface with the correct implementation class to be invoked, based both on the default command class name of the interface and on the database command registries.
Allowing clients to invoke commands only by using their interface and through the following sequence of invocation steps: – Set the command’s input properties – Invoke an execute() method – Retrieving output properties. WebSphere Commerce supports four different types of commands:
Controller commands. These encapsulate all the logic necessary to accomplish a single service request, such as OrderProcess for an order processing request. They invoke task commands to perform single units of work, such as payment processing in the previous example, and control the application logic flow in order to fulfill the whole request. Upon completion of the flow, they return a view name to the Web controller, which is in charge of determining the view implementation class for the particular store and requesting device. Controller commands are targetable, which means that they can be executed on a different container, but only the local target is supported.
Task commands. Each task command performs a single unit of work, and usually access a single business data entity using an access bean wrapper that hides the complexity of interacting with Enterprise JavaBeans. Task commands are not targetable, which means that they must be executed on the same container as the invoking controller command.
Data bean commands. They are invoked by JSP templates through the data bean manager in order to populate data beans. They’re targetable, but are only supported on the local targets.

124

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


View commands. These can be invoked either by a controller command returning their interface name to the Web controller, or directly by a client. They are of three different types: – Redirect view command, which sends the view using a redirect protocol. – Direct view command, which sends the view directly to the client. – Forward view command, which forwards the view request to another Web controller, usually a JavaServer Page template. They’re targetable, but supported only on the local target. The level of indirection in commands invocation that is provided by the WebSphere Application Server command framework has the following advantages:
The possibility of implementing an access control policy based on the requesting user at command level.
The flexibility to execute different command implementations for different stores.
The flexibility to execute different command implementations for different types of requesting devices.

4.4.3 Display design pattern According to the display design patterns, view commands are implemented as JavaServer Pages templates, that is they are developed in a JavaScript language that provides an easy mechanism to access and display data without the necessity of a particular programming skill. At runtime, JavaServer Pages templates are compiled into servlets after the first invocation. They could be implemented directly as servlets, but this way is not recommended because their implementation would require a much higher level of programming skill. Moreover, view commands should be invoked only by using their view name. As usual, this level of indirection affords the possibility to invoke at runtime the appropriate implementation. For example, different view implementations can be invoked based on the locale, the type of the requesting device, or any other property into the request context. JavaServer Pages templates use data beans, which are access bean extensions that allow them to retrieve business data in a very simple way. In fact, they can create and populate data beans by means of the data bean manager with a single line of code, such as the following: com.ibm.commerce.beans.DataBeanManager.activate(DataBean,HTTPServletRequest)

Chapter 4. Programming model

125

Note that the above line of code is automatically created by WebSphere Studio Page Designer and WebSphere Studio Application Developer whenever a new data bean is inserted in a JavaServer Page template. After activation, JavaServer Page templates can simply retrieve any property they need from the data bean, and even get the property names in all the languages supported by the WebSphere Commerce instance in case of multicultural stores. Data beans can retrieve data in two different ways:
Smart data beans retrieve associated data only when they are actually requested (lazy fetch). They provide better performance but they are more complicated to develop.
Command data beans rely on a command in order to retrieve all their data at once. They are easier to implement but they can have higher performance costs.

4.5 Persistent object model WebSphere Commerce implements its persistent object model with entity beans compliant with the Enterprise JavaBeans specifications, V1.1. Note: For more detailed information, refer to the Programming Guide and Tutorials, IBM WebSphere Commerce V5.5 product guide. Enterprise JavaBeans (EJBs) are standard wrappers of business data that are provided by the EJB container with the following services:
Persistency, in case of either entity EJBs or of stateful session EJBs.
Distribution. They can be executed remotely by means of the Remote interface. Moreover, they can be created and discovered by network applications by means of their Home interface and their primary keys.
Transaction management.
Security implementation by means of access control mechanisms. The main types of EJBs are:
Entity EJBs, which persist until they are explicitly removed from the container by either the client or the server. Based on the type of persistence management, they can be: – Container Managed Persistence (CMP), if they rely on the container for their persistency.

126

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

– Bean Managed Persistence (BMP), if they implement their own persistency.
Session EJBs, which persist only as long as either client or server maintains a reference to them. They can be: – Stateless, when a single instance can handle requests from multiple clients, receiving all the necessary input parameters with each requests. This is the most scalable solution. – Stateful, when an EJB instance maintains a state between invocations. Note that this solution impacts the scalability of the whole system, because it requires that a client is always connected to the server that hosts the EJB that it references. For more information about Enterprise JavaBeans, refer to the following:
Programming Guide and Tutorials, IBM WebSphere Commerce V5.5 product guide
Chapter 13, “Customize a store: Price Watch example” on page 393
“EJB Tutorial”, downloadable at the following Web site: http://www.ejbtut.com


Article titled “What are Enterprise JavaBeans components?“, downloadable from the following Web site: http://www-106.ibm.com/developerworks/library/what-are-ejbs/part1/inde.html

This article describes the goals of the EJB architecture, the programming model, and how to deploy and use EJBs.

4.6 Access control The access control model of a WebSphere Commerce application has three primary concepts: users, actions and resources. Users are the people who use the system. Resources are the entities that are maintained in or by the application. For example, resources may be products, documents, or orders. User profiles that represent people are also resources. Actions are the activities that users can perform on the resources. Access control is the component of the e-commerce application that determines whether a given user can perform a given action on a given resource. In a WebSphere Commerce application, there are two main levels of access control. The first level of access control is performed by the WebSphere Application Server. In this respect, WebSphere Commerce uses WebSphere Application Server to protect enterprise beans and servlets. The second level of

Chapter 4. Programming model

127

access control is the fine-grained access control system of WebSphere Commerce. The WebSphere Commerce access control framework uses access control policies to determine if a given user is permitted to perform a given action on a given resource. This access control framework provides fine-grained access control. It works in conjunction with, but does not replace the access control provided by the WebSphere Application Server. The following WebSphere Commerce resources are protected under access control by WebSphere Application Server:
Entity beans These beans model objects in an e-commerce application. They are distributed objects that can be accessed by remote clients.
JSP templates WebSphere Commerce uses JSP templates for display pages. Each JSP template can contain one or more data beans that retrieve data from entity beans. Clients can request JSP pages by composing a URL request.
Controller and view commands Clients can request controller and view commands by composing URL requests. In addition, one display page may contain a link to another by using the JSP file name or the view name, as registered in the VIEWREG table. For detailed information on access controls, refer to the following:
Programming Guide and Tutorials, IBM WebSphere Commerce V5.5
Security Guide, IBM WebSphere Commerce V5.5
IBM WebSphere Commerce V5.5 online documentation

4.7 Customizing application assets Each of the IBM WebSphere Commerce V5.5 editions and corresponding IBM WebSphere Commerce Studio V5.5 editions include sample stores to speed application development. This section describes the types of application assets that you may need to customize using WebSphere Commerce Studio and indicates the appropriate skill level needed for the customization.

4.7.1 Asset types to customize and development tooling In combination with the rich WebSphere Commerce framework described in 4.2, “WebSphere Commerce Server framework” on page 112 and the extremely

128

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

powerful WebSphere Commerce Studio development tooling, virtually any application customization is possible. We have categorized the application assets into the following categories:
Store front assets
Back office assets (business logic)
Data files

Store front assets Store front asset customization (new or modified) is primarily done for the look and feel of the store pages. For example, if you started with the B2B direct sample store (ToolTech), you would most definitely change the store logo and headings on the store pages. This type of development is commonly performed by a Web developer (Web designer). Store front asset types include the following:





Static HTML pages JavaServer Pages (JSPs) Images JavaScript

Within WebSphere Commerce, these assets types are contained within the sample store archives.

Back office assets (business logic) Back office assets (new or modified) contain the business logic. Examples of back-office assets types include:
Commands
Data access beans
Data beans Beans enable the store front JSPs (containing data beans) to interact with the instance database to allow for the storage, retrieval, and manipulation of data.

Data files The sample store archives contain many XML data files. Some of the data files are used for site and store configuration for such things are taxes and shipping. There are also many XML data files used to populate the WebSphere Commerce catalog. The sample store includes sample product catalog data that must be updated or removed for your customized store.

Chapter 4. Programming model

129

We describe this topic in more detail in Chapter 3, “Business and store models” on page 61. In addition, Chapter 12, “Create a store” on page 341 provides a working example on how to customize the XML data files for a store.

Customization information and examples There are several places that you can find customization examples:
Chapter 12, “Create a store” on page 341 This chapter provides an in-depth working example, starting with the B2B Direct sample store (ToolTech), on how to create and customize a store. Some highlights include team development, source control, customizing store assets, and packaging a store archive.
Chapter 13, “Customize a store: Price Watch example” on page 393 This chapter includes Java application development working examples of virtually all kinds, including database schema extension, data access bean, commands, data beans, JSPs, e-mail integration (commands, JSP templates), and use of the scheduler for batch jobs.
Programming Guide and Tutorials, IBM WebSphere Commerce V5.5 product guide
Sample Store Guide, IBM WebSphere Commerce V5.5 product guide
Store Development Guide, IBM WebSphere Commerce V5.5 product guide

4.7.2 Matching skills to customization needs A commerce store can have varying levels of customization. The skills required depend on this level of customization. The level of customization affects both the development time and skills needed to develop a store. We have categorized the customization requirements into three levels: basic, intermediate, and advanced. For each level we describe the tasks involved and list the I/T specialist roles to complete the tasks.

Basic customization Basic store customization normally involves the following:
Catalog creation This involves creating a catalog and dividing the catalog into logical catalog groups or categories. The store’s products are then assigned to catalog groups (categories).

130

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


Web page design Web page design involves the creation of graphics, static HTML pages, and JSPs for a customized look and feel for the store using the existing WebSphere Commerce commands. The roles include site administrator and Web developer.

Intermediate customization Intermediate store customization includes the elements of a basic customization plus the following tasks:
Custom command development Custom commands, which are Java classes, are used for flow control and implement business logic. They may extend existing commands or be created as new commands. WebSphere Commerce commands are developed in WebSphere Commerce Studio (WebSphere Studio Application Developer).
Custom data bean development The development of data beans is required to represent dynamic content to be displayed in JSPs. The dynamic content is populated at runtime most often from the database. Data beans are developed in WebSphere Commerce Studio (WebSphere Studio Application Developer). The roles include site administrator, Web developer, and Java programmer.

Advanced customization Advanced store customization includes the elements of an intermediate customization plus the following tasks:
Database customization Alteration of the existing database schema may be needed to meet the specialized needs of a business.
EJB development EJBs are used as persistent Java objects to represent data in the database. For example, if you need to add a table to the database, you will need to create an EJB to query and update that table. EJBs are developed in WebSphere Commerce Studio (WebSphere Studio Application Developer).
Data access bean development The data access bean is developed in Java and uses EJBs to access data from the database. Data access beans are developed in WebSphere Commerce Studio (WebSphere Studio Application Developer).

Chapter 4. Programming model

131

The roles include site administrator, Web developer, Java programmer, database schema owner and database administrator.

4.8 For more information Refer to the following for additional information on the WebSphere Commerce programming model:







132

Programming Guide and Tutorials, IBM WebSphere Commerce V5.5 Installation Guide, IBM WebSphere Commerce Studio V5.5 Store Development Guide, IBM WebSphere Commerce V5.5 Fundamentals Guide, IBM WebSphere Commerce V5.5 WebSphere Commerce V5.5 online documentation Chapter 13, “Customize a store: Price Watch example” on page 393

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

5

Chapter 5.

Site and store administration This chapter provides an overview of the administration tools used to configure and manage a WebSphere Commerce site and store. First we provide a description of each administration tool, including WebSphere Commerce specific tools and supporting software administration tools. Next, we define the key operational areas that need to be managed. In closing, we provide a summary of the tools and tasks by user role (IT specialist and line-of-business). This chapter is organized into the following topics:






Administration tools Key operational categories to manage IT specialist roles and tools Line-of-business user roles and tools For more information

© Copyright IBM Corp. 2003. All rights reserved.

133

5.1 Administration tools WebSphere Commerce V5.5 and supporting software include many administration tools that make managing the WebSphere Commerce site and store easier for IT specialists and line-of-business (LOB) users. All of the administration tools listed in this section are included with the IBM WebSphere Commerce V5.5 product packaging (Business and Professional Edition). We have included some of the administration tools provided with supporting software that are key to the operations of the site and store. There are many other supporting software administration tools that we have not listed. The section describes the following administration tools:










WebSphere Commerce Administration Console WebSphere Commerce Administration Console WebSphere Commerce Accelerator WebSphere Commerce Organization Administration Console WebSphere Commerce Loader Package WebSphere Commerce Scheduler WebSphere Commerce Payments Console WebSphere Application Server Administration Console DB2 Control Center

5.1.1 WebSphere Commerce Configuration Manager After installing WebSphere Commerce, the WebSphere Commerce node must be configured. The WebSphere Commerce Configuration Manager is used to create, modify and delete various components of a WebSphere Commerce instance and the WebSphere Commerce Payments instance, which is new to this release of WebSphere Commerce. Some of the key tasks performed when creating a WebSphere Commerce instance include the following:
Create the WebSphere Commerce application server
Deploy the WebSphere Commerce enterprise application
Update the WebSphere Commerce .xml file with the settings specified during instance creation
Create the WebSphere Commerce instance database and populate the database with the WebSphere Commerce schema
Configure the Web server configuration file with virtual hosts, aliases and directives

134

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

The Configuration Manager provides a GUI interface to the WebSphere Commerce .xml configuration file. Note: Whenever possible, components should be enabled through the Configuration Manager rather than by modifying the WebSphere Commerce .xml configuration file. The Configuration Manager consists of a Java application based server and client. The Configuration Manager Server must be started first. This is accomplished slightly differently on Windows, AIX, and Solaris platforms, as documented in Part 4, “Runtime deployment scenarios” on page 551 of this redbook. On Windows, the Configuration Manager Server started as a Windows services (IBM WC Configuration Manager). When the Configuration Manager (client) is started from the WebSphere Commerce application folder, the user is prompted for a password. By default, the user ID is webadmin, and the password is webibm. During the first logon, you will be prompted to enter a new password. After a WebSphere Commerce instance is created, you will see something like Figure 5-1 on page 136.

Chapter 5. Site and store administration

135

Figure 5-1 WebSphere Commerce Configuration Manager

Tip: New to WebSphere Commerce V5.5 is the ability to create your own user-defined site administrator ID during instance creation from the Configuration Manager. In previous releases, the site administrator was predefined as wcsadmin.

WebSphere Commerce instance properties When creating an instance, the Configuration Manager will guide you through entering the required entries for the instance properties. Once the instance is created, you can access the instance properties directly from the Configuration Manager, as seen in Figure 5-2 on page 137.

136

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Figure 5-2 WebSphere Commerce instance properties

WebSphere Commerce instance components After creating an instance, you will see a listing of instance components, as shown in Figure 5-3 on page 138.

Chapter 5. Site and store administration

137

Figure 5-3 WebSphere Commerce instance components

Each of the instance components listed in Figure 5-3 can be enabled/disabled by selecting the component and then clicking the Enable check box. In addition, the components can be further configured using the Configuration Manager. For more information on the Configuration Manager, refer to the following:
IBM WebSphere Commerce V5.5 online documentation
Product installation guides: – – – –

138

Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000 Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems Installation Guide, IBM WebSphere Commerce V5.5 for OS/400 Additional Software Guide, IBM WebSphere Commerce V5.5

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


Runtime deployment scenarios in this redbook for creating and updating an instance: – Chapter 16, “Windows: Migrate a single-tier to a multi-tier” on page 553 – Chapter 17, “Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server” on page 599 – Chapter 18, “AIX: Three-tier using DB2 and IBM HTTP Server” on page 675 – Chapter 19, “OS/400: Two-tier remote database server” on page 755

5.1.2 WebSphere Commerce Administration Console The WebSphere Commerce Administration Console allows you to control your site or store by completing administrative operations and configuration tasks. If you are a Site Administrator, you select the store and language with which you want to work when you log on to the Administration Console. 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 group names (roles) and authority levels. The WebSphere Commerce Administration Console is installed by default as part of the WebSphere Commerce installation, but not deployed until the WebSphere Commerce instance has been created. The WebSphere Commerce Administration Console is accessible to Web browser clients (Microsoft Internet Explorer 5.5 or higher) by entering the following: https://:8002/adminconsole

There are two things to be aware of with the Administration Console URL. First, the Administration Console is configured to use SSL and requires the HTTPS protocol. Second, the 8002 port is defined when creating the WebSphere Commerce instance. The port 8002 is added to the Web server configuration file (for example, httpd.conf) under a virtual host for this server, as well as the alias /adminconsole. After logging on to the WebSphere Commerce Administration Console as the site administrator (user-defined during instance creation), you will be prompted to select the site or store to configure. Figure 5-4 on page 140 displays the menu options available from the WebSphere Commerce Administration Console after selecting Site.

Chapter 5. Site and store administration

139

Figure 5-4 WebSphere Commerce Administration Console: site access

The WebSphere Commerce Administration Console from the site menus includes functionality for the following site level options:
Security – – – –

Account Policy Password Policy Account Lockout Policy Security Checker


Configuration – – – – – – – –

Transports (e-mail, WebSphere MQ, WebSphere InterChange Server, file) Message Types Component Configuration Scheduler Registry View Unsent Message View Archived Messages Product Information


Payments – User – Merchant Settings

140

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

– Payment Settings – Cassettes
Store Archives – Publish – Publish Status Note: In previous releases of the WebSphere Commerce (V5.1, 5.4), store archives were published from Store Services. The store publishing functionality has been moved to the Administration Console under the Store Archives menu option. For more detailed information on Store Publishing, refer to 3.3.8, “Publish a store” on page 97. After logging in to the Administration Console, if you selected the Store option, you will see a listing of stores that have been published. Select the desired store to manage and then click Next. You will see the menu options listed in Figure 5-5.

Figure 5-5 WebSphere Commerce Administration Console: store access

Chapter 5. Site and store administration

141

The WebSphere Commerce Administration Console from the store menus includes functionality for the following store level options:
Access Management – Policies
Configuration – – – – – –

Transports Message Types E-mail Activities Scheduler View Unsent Message View Archived Messages


Rules Service – Administration
Payments – Users – Merchant Settings

5.1.3 WebSphere Commerce Accelerator The WebSphere Commerce Accelerator allows you to maintain online stores, hubs, and catalogs by completing various store operations, from managing the look and feel of your store to creating and maintaining orders to tracking store activities. If you are authorized to work with multiple stores, when you log on to the WebSphere Commerce 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 preselected during logon. Additionally, if the store supports more than one language, you can select the language with which you want to work. Finally, if you are assigned a role with fulfillment duties, you can also choose the fulfillment center associated with the store when you log on. If you wish to change your store, language, or fulfillment center selection, click the icon, found in the upper-left corner to display the selection window. Tasks that you are authorized to perform in your role are displayed on the WebSphere Commerce Accelerator home page menus. These tasks are based on user roles, authority levels, and the business model and type of store. If you need to change your access level, contact your site administrator. To return to the WebSphere Commerce Accelerator home page, at any time, click Home near the top of the WebSphere Commerce Accelerator.

142

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

The WebSphere Commerce Accelerator is installed by default as part of the WebSphere Commerce installation, but not deployed until the WebSphere Commerce instance has been created. The WebSphere Commerce Accelerator is accessible to Web browser clients (Microsoft Internet Explorer 5.5 or higher) by entering the following: https://:8000/accelerator

After you log on to the WebSphere Commerce Accelerator, you will see something like Figure 5-6.

Figure 5-6 WebSphere Commerce Accelerator

The WebSphere Commerce Accelerator includes the following menu options:
Store – Open/Close – Change Profile – Change Flow

Chapter 5. Site and store administration

143

– – – – – – – – – – – –

Change Shipping Change Tax Payment Settings Approval Requests Find Approval Requests Approval Submissions Find Approval Submissions Fulfill Centers Return Reasons Report Delivery Status Business Intelligence Reports Collaborative Workspaces


Sales – – – – – – – – – – – – – – – –

Accounts RFQs Personalized Attributes Find Customers Find Orders Find Returns Order Management Reports Operational Reports Auctions Customer Care Customer Care Queue Approve Payment Deposit Payment Settle Payment Find Payment Find Payment Batch


Marketing – – – – – –

Customer Profiles Campaigns Campaign Initiatives E-Marketing Spots E-mail Activities AD Copy


Products – – – – –

144

Product Management Categories Find Catalog Entries Find Categories Find Bundles or Kits

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

– – – – – – – – – – – – – – – –

Find Merchandising Association Expected Inventory Vendors Auctions Find Auctions Auction Styles Bid Rules Coupon Promotions Product Promotions Order Promotions Product Advisor Guided Sell Product Advisor Statistics Product Explorer Statistics Product Comparison Statistics Sales Assistant Statistics


Logistics – – – – – –

Returns Pick Batches Releases Ready to Ship Expected Inventory Find Inventory Inventory Reports

5.1.4 WebSphere Commerce Organization Administration Console The Organization Administration Console allows you and the buyer administrators to control the organizations that access your site or store. Tasks that you are authorized to perform in your role are displayed on the Organization Administration Console home page menus. These tasks are based on user roles and authority levels, which are defined in XML files on your WebSphere Commerce system and are assigned by the site administrator by using the Administration Console. The WebSphere Commerce Organization Administration Console is installed by default as part of the WebSphere Commerce installation, but not deployed until the WebSphere Commerce instance has been created. The WebSphere Commerce Organization Administration Console is accessible to Web browser clients (Microsoft Internet Explorer 5.5 or higher) by entering the following: https://:8004/orgadminconsole

After logging on to the WebSphere Commerce Organization Administration Console, you will see something like Figure 5-7 on page 146.

Chapter 5. Site and store administration

145

The WebSphere Commerce Organization Administration Console includes the following menu options:
Access Management – – – – – – –

Users Organizations Roles Access Groups Policies Resource Groups Action Groups


Approvals – Approval Requests – Find Approval Requests

Figure 5-7 WebSphere Commerce Organization Administration Console

146

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

5.1.5 WebSphere Commerce Loader Package WebSphere Commerce V5.5 has two catalog management tools, Loader Package and the Accelerator Product Management Tool. The Accelerator Product Management Tool is GUI based and very well suited for operations when only a few product entries need to be performed. The WebSphere Commerce Loader Package is a Java-based set of utilities that can be executed via the command line or via Java API and allows for automation and is more appropriate for managing large product catalogs. Note: The Loader Package was known as Catalog Manager in WebSphere Commerce V5.4. The Loader Package provides the following functionality:
Aggregate data from multiple input streams into one aggregated database.
Transform data from ASCII-based CSV to an XML format. The MassExtract tool will extract data, but to an XML format. Converting from XML to CSV is not as easy as converting CSV to XML.
Remap data from one XML format to another.
Import data from multiple input sources in the form of ASCII-based CSV and XML files into WebSphere Commerce. The WebSphere Commerce Loader Package includes the following components:
Text Transformation Tool The Loader Package Text Transformation Tool provides the ability to convert ASCII-file output such as a CSV file into an XML data format that later can be transformed and eventually loaded into the WebSphere Commerce database.
XSL Editor A major benefit of using XML for data representation and structuring is that many tools exist to help with transformation of XML data from one format to another. An important method involves the use of XML style sheets, which are written in the eXtensible Stylesheet Language, or XSL. These style sheets may then be applied to XML documents by a tool that conforms to the XSL Transformation standard, or XSLT. The WebSphere Commerce Catalog Manager XSL Editor is used to develop XSL style sheets.
XML Transformation Tool This Loader Package tool takes XSL style sheets, such as those created using the XSL Editor, and applies the transformation to XML files, such as those created by the Text Transformation Tool. The result is normally another

Chapter 5. Site and store administration

147

XML file, which is structured according to the input data requirements for a target application such as WebSphere Commerce.
DTD Generator The DTD Generator can create a DTD and a schema to use with the Loader Package. The DTD Generator uses an input file containing database-table names, and generates either a DTD or an XML schema to describe the selected database tables.
ID Resolver The ID Resolver tool takes an XML file and compares the contents to data within a specified database. Each element within the XML file is examined in turn, and if it contains attributes that require resolving, the data from other attributes within the element is used to find a match with data already within the database, or which has been previously specified within the XML file.
Loader After ID resolution, the loading of the newly resolved data into the database is performed using the loader, known as the MassLoad tool. An essential prerequisite before attempting to load data into the commerce database is that it must have been successfully and completely resolved.
Extractor To extract data from a database using the Extractor, you must specify the data that you want to extract from the database using an extraction-filter file. The extraction filter that you use depends on the type of data that you want to extract.

5.1.6 WebSphere Commerce Scheduler The WebSphere Commerce scheduler is a background server that schedules and launches jobs both at the site and store levels. From the Configuration menu of the Administration Console, the scheduler allows site administrators to schedule and configure jobs. The scheduler polls the SCHACTIVE table to find jobs scheduled to run. The following list describes the possible entries for the STATE column:
W indicates the job is waiting to be executed if necessary.
I indicates the job is currently inactive.
IF indicates the job has run and failed and the instance will rerun the job. For each entry where the state is W and the preferred start time is less than or equal to the current time, the scheduler gets the job's configuration information from the SCHCONFIG table. If the INTERFACENAME field is defined, the scheduler gets the implementation of the business logic task command and if

148

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

that implementation uses the business logic interface, the scheduler runs the business logic task command. If no exceptions are thrown, the state is changed to I. When the scheduler finds entries in the SCHACTIVE table where the state is I or IF and the preferred start time is equal to or less than the current time, it executes the job. The scheduler is scalable across one or more threads, running on one or more machines. Multiple commerce servers or clones can connect to the same database. When a job is added to the SCHCONFIG table, the job can be scheduled to run on any WebSphere Commerce Server or application server cluster. Note: When using multiple clones or the same database, you must create a specific instance name in the instance_name.xml file for the support of broadcast jobs. For more information on the scheduler, refer to the following:
13.12, “Configuring the scheduler to run the batch job” on page 493
Refer to “Schedule job for store publish” on page 104
IBM WebSphere Commerce V5.5 online documentation

5.1.7 WebSphere Commerce Payments Console In WebSphere Commerce V5.5, payment administration can be performed from the WebSphere Commerce Administration Console (configuration) and the WebSphere Commerce Accelerator (operations). The WebSphere Commerce Payments Console is a legacy component of the WebSphere Commerce Payments available in previous releases. The WebSphere Commerce Payments Console is accessible to Web browser clients (Microsoft Internet Explorer 5.5 or higher) by entering the following: https://:5433/webapp/PaymentManager

Where hostname is the Web server configured for the WebSphere Commerce Payments virtual host. After logging on to the WebSphere Commerce Payments Console, you will see something like Figure 5-8 on page 150. We find the WebSphere Commerce Payments Console useful for verifying that the WebSphere Commerce Payments instance was created properly and for approving the payment of a transaction for testing purposes.

Chapter 5. Site and store administration

149

Figure 5-8 WebSphere Commerce Payments Console

5.1.8 WebSphere Application Server Administration Console When creating a WebSphere Commerce instance using the Configuration Manager for most configurations, the WebSphere Application Server is configured for the user. When implementing more advanced configurations, or if you want to know more about what is going on behind the scenes, you will need to understand the configuration of the WebSphere Commerce application server within the WebSphere Application Server. The WebSphere Application Server Administration Console is a Web browser-accessible application (enterprise application) that allows the administrator to configure the WebSphere Application Server.

150

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

To access the WebSphere Application Server Administration Console, enter the following in a Web browser: http://:9090/admin

After entering a user ID, you will see something like Figure 5-9.

Figure 5-9 WebSphere Application Server Administration Console

In this redbook, we used the WebSphere Application Server Administration Console for the following:
Verifying WebSphere Commerce instance creation
Adding a remote Web server (manually updating virtual host aliases, regenerating a plug-in)

Chapter 5. Site and store administration

151


Configuring WebSphere Application Server security

5.1.9 DB2 Control Center The DB2 Control Center provides a graphical tool to manage the resource of DB2 UDB and databases. We found the DB2 Control Center useful in view database tables, and sample contents within the database tables for the WebSphere Commerce instance database.

5.2 Key operational categories to manage This section provides a summary of other operational categories to be managed for a WebSphere Commerce store. The objective of providing a high-level summary of each of the following operational categories is to make sure users are aware of the functionality offered in the WebSphere Commerce V5.5 product. Note: More detailed information on each of the listed topics can be found in the Fundamentals Guide, IBM WebSphere Commerce V5.5 product guide and the WebSphere Commerce V5.5 online documentation.

Catalog management The term “content” in the context of the Internet refers to any information that is available for retrieval by a Web client, including Web pages, images, music, audio, documents, software downloads, education material, and e-commerce catalog data. The terms “catalog management” and “content management” are often interchanged. In the context of this redbook, we will distinguish content from catalog data. For a WebSphere Commerce site, content is information or editorial content displayed on the Web pages to supplement information about a product, such as a review or marketing promotion. Data or catalog data is used to define a product or item such as a SKU, price, size, and color. Catalog data displayed on the e-commerce Web page is retrieved from the WebSphere Commerce instance database. In some cases, content is used loosely to refer to catalog data. Catalog management includes the processes and tooling used to manage catalog data, including data transform, load, and management of catalog data assets before and after being loaded into the catalog of the WebSphere Commerce instance database. In this section, we define the different types of catalog assets to be managed and the tools included with WebSphere Commerce for catalog management (Accelerator and Loader Package).

152

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

The key catalog data assets to manage are as follows (described in 3.3.5, “Catalog data assets and concepts” on page 91):












Master catalog Navigational catalog Catalog group Catalog entry Product Attributes (defining and descriptive) SKUs Bundle Pre-built kit Static kit Dynamic kit

The primary catalog management tools included in WebSphere Commerce V5.5 to manage catalog data are the WebSphere Commerce Accelerator and the Loader Package.

WebSphere Commerce Accelerator - Product Management The WebSphere Commerce Accelerator Product Management tooling is new to WebSphere Commerce V5.5. Some of the functionality offered in V5.5 was released in the October 2002 Enhancement Pack for WebSphere Commerce V5.4. This Web browser-based tool provides a user-friendly GUI approach to managing the assets described in 3.3.5, “Catalog data assets and concepts” on page 91. Some of the new features offered in the Product Management tool are as follows:








Manage catalog entries such as catalog groups and products Creation and maintenance of kits (prebuilt and dynamic) and bundles Creation and maintenance of merchandising associations Improved tooling for defining attributes New tooling for descriptive attributes Improved author time search Manage merchandising associations

To access the WebSphere Commerce Accelerator Product Management tooling, enter the following to access the Accelerator: https://:8000/accelerator

Once you have logged into the Accelerator, select the Products menu option as seen in Figure 5-10 on page 154. Notice that there are many catalog management related options available in addition to Product Management, such as Categories and Find Catalog Entries.

Chapter 5. Site and store administration

153

Figure 5-10 WebSphere Commerce Accelerator: Product Management

WebSphere Commerce Loader Package The WebSphere Commerce Loader Package can also be used for catalog management. Refer to 5.1.5, “WebSphere Commerce Loader Package” on page 147 for more information. Note: For a detailed explanation and examples of using the Loader Package, refer to the WebSphere Commerce V5.4 Catalog Design and Content Management, SG24-6885 redbook. In WebSphere Commerce V5.4, the Loader Package utilities were referred to as the Catalog Manager.

154

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Merchandising The WebSphere Commerce merchandising subsystem supports merchandising associations and product advisors to enable businesses to better promote product and categories to their customers.

Marketing The WebSphere Commerce marketing subsystem facilitates marketing and personalization. The marketing subsystem includes support for discounts, e-marketing spots, customer profile creation and maintenance, marketing campaigns, and coupon promotions.

Business relationships: organizations and contracts Business accounts are the starting point for managing a store’s relationships with customer organizations. You can use business accounts to track contracts and orders for customer organizations. You can also configure how buyers from customer organizations shop in your store. Contracts enable a customer organization to purchase products from a store or a group of stores at a specified price for a specified period of time. Contracts can be created either by using the WebSphere Commerce Accelerator, or by creating XML files and importing them to populate the database.

Request for quote (RFQ) Request for Quotes (RFQ) is one of the trading mechanisms available in WebSphere Commerce. Buyers can add products to an RFQ by browsing the catalog, or by using a requisition list. Buyers can include any number of products in one RFQ, and define unique specifications for each product. They can also specify the terms and conditions for the transaction. A seller can view and respond to an RFQ when the RFQ is in the Active state. A Buyer can also change or cancel an RFQ. When sellers respond to an RFQ, they have the option of responding to each product, and to each product specification. A Seller can also modify or cancel a response. The Seller can also substitute products in the response. The Seller can evaluate RFQ responses in the Closed state to choose a winner, or multiple winners. When the RFQ response is accepted by the buyer and the seller is notified, the RFQ transaction is completed through one of the following processes:
The buyer places an order that already contains the RFQ information.
A contract already containing the RFQ information is created.
Then the RFQ can go to the next round.

Chapter 5. Site and store administration

155

A record of the RFQ is maintained in the RFQ Request List for a predetermined period, so that they can copy an RFQ that they repeatedly use. Responses are retained for the same period to facilitate a seller’s response to similar requests from the same buyer. Sellers can enable approval flow for the RFQ response process if they want responses to be reviewed prior to transmittal to the buyer. RFQs are available in the B2B direct Supply Chain store models.

Auctions Auctions are an increasingly popular sales model for online transactions. Auctions provide a method for negotiating and dynamically establishing the price and other terms for the sale of products and services. WebSphere Commerce provides tools to help you create and manage auctions for your site. The auctions component provides an ideal environment for implementing small to moderate-scale auctions as part of your e-commerce solution.

Reporting and business intelligence WebSphere Commerce includes a reporting framework, predefined reports for operations, and business intelligence. Refer to Chapter 20, “Commerce analytics” on page 787 and the Fundamentals Guide, IBM WebSphere Commerce V5.5 product guide for more information.

Managing orders A customer service representative, or in a business-to-business site an account representative, can track and manage details about orders, including the customer, recipient, products and quantity, total cost (including tax and shipping charges), shipping specifications, payment method, and any comments. In WebSphere Commerce an order is one or more products, their prices, and the quantity specified, that a customer has selected to purchase or has purchased. A customer service representative can also place an order on behalf of a customer. In addition to products, a customer order includes a billing address, shipping address (not applicable to downloadable purchases, such as software), shipping method, carrier, and service, payment information, tax and shipping charges, and any comments or price adjustments stipulated by the person placing the order.

Managing returns If a customer is not satisfied with their purchase, they can request a refund for the amount of the original purchase, in the form of a credit to their credit card or to a line of credit. In WebSphere Commerce, a return includes a credit for the

156

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

taxes paid on the order, but not necessarily the shipping charges. To refund the customer shipping costs, you can manually add this to the total refund amount. Depending on your business, a return does not always require the customer to physically return the unwanted product. For example, if a customer wants a refund for fresh produce from a grocery store, the store would not likely require the produce to be returned to the store. When a store is created, the store defines return policies, for example, the FashionFlow store defines that all returns are automatically returned if the return is initiated within 30 days of the purchase. The FashionFlow store does not charge for returns. A Return Merchandise Authorization (RMA) is initiated when merchandise is returned to a fulfillment center. Some stores may require customers to contact the store and ask a customer service representative to initiate the RMA; other stores will initiate an RMA when returned merchandise arrives at the fulfillment center. All returns that fall within the store’s return policy are automatically approved by the system. Returns that fall outside of the store’s return policy may be approved by the customer service supervisor.

Customer Care Customer Care is a Lotus Sametime instant messaging application integrated with WebSphere Commerce stores, that provides customers and customer service representatives (CSR) with real-time support. A customer can enter a WebSphere Commerce site, and click the Customer Service link to communicate with a customer service representative. A CSR accesses the Customer Care interface through the WebSphere Commerce Accelerator. In addition, the CSR can view the store page where the customer needs assistance, and retrieve shopping cart and profile information. This interface also allows the CSR to chat with other CSRs. In this release of WebSphere Commerce, the Customer Care feature now supports queues. Key features of Customer Care queues include the following:
Multiple queues and the ability for CSR to route customers waiting for assistance. The Operations Manager can create, change, delete, and assign CSRs to the queues, using the WebSphere Commerce Accelerator. Customer service representatives can select to serve any customer assigned to their queues.
Customer service representatives can monitor customized customer attributes in a store.

Chapter 5. Site and store administration

157

Collaborative workspaces The collaborative workspaces feature is available with WebSphere Commerce Business Edition. Lotus QuickPlace is the self-service Web tool for team collaboration. QuickPlace enables the creation of a secure and central workspace on the Web instantly. Structured for immediate participation, teams use QuickPlace to do the following:
Coordinate people, tasks, plans, and resources.
Collaborate and share ideas and discussion, resolve issues, co-author documents, and exchange files.
Communicate actions and decisions, key findings and lessons, and publish knowledge captured to a broader base of readership.

5.3 IT specialist roles and tools This section provides a summary of the IT specialist tasks and tools used to manage the WebSphere Commerce site and store for the following roles:





System administrator Site administrator Store administrator Database administrator

5.3.1 System administrator This section describes the role of the system administrator, tasks performed, and tools used.

Role description for system administrator The system administrator installs and initially configures all WebSphere Commerce associated software and hardware, and may be responsible for establishing several server configurations for different stages of development, such as testing, staging, and production. The system administrator needs to consider the issues related to national language support, such as operating system and application software globalization support. This system administrator responds to system warnings, alerts, and errors, knows where to find the installation and other relevant logs, and maintains them, diagnoses and resolves system integration problems, and system security problems. The system administrator has a thorough knowledge of the e-commerce solution architecture, including the hardware and software components, externally visible interfaces between them, and the relationship among them.

158

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Typical tasks for the system administrator The following are the typical tasks of a system administrator:
Installs and initially configures all WebSphere Commerce associated software components, as listed: – – – – –

Web servers (IBM HTTP Server, Sun ONE Web Server) Database server (DB2, Oracle) WebSphere Application Server WebSphere Commerce WebSphere Commerce Payments


Additionally, installs and initially configures the following optional software components (may or may not be included, depending on whether you are using WebSphere Commerce Professional, Business, Business Developer edition): – – – – – – – – –

WebSphere Commerce Analyzer IBM DB2 Intelligent Miner for Data WebSphere Commerce Payment casettes IBM Directory Server DB2 Text Extenders Lotus QuickPlace Lotus Sametime Tivoli Web Site Analyzer WebSphere Commerce Studio


Additionally, installs and initially configures the following software: – WebSphere MQ – Lotus Domino
Diagnoses and resolves integrated system problems
Monitors the integrated system performance, and helps with the performance tuning task
Performs security tasks, such as setting and changing passwords, enabling single sign-on (SSL) for production with IBM HTTP Server, and enabling SSL for IBM Directory Server (LDAP).

Tools used by the system administrator The following are typical tools used by the system administrator:






Prerequisites Checker Security Checker JDBCTestTool WebSphere Application Server Administration Console WebSphere Commerce Administration Console

Chapter 5. Site and store administration

159

5.3.2 Site administrator This section describes the role of the WebSphere Commerce site administrator, tasks performed, and tools used.

Role description for the site administrator The site administrator does the following:











Administers and maintains the site Configures and manages users and groups to control access to the site Specifies command security (access control) Configures and manages the payment system Configures and manages the messaging system Monitors performance Establishes and maintains site security Enables and disables cache Enables and disables logging Enables and disables auction

The site administrator typically uses WebSphere Commerce and associated software tools to perform these tasks. The site administrator responds to system warnings, alerts, and errors, knows where to find and review the relevant logs, sets the level of severity for the logging, enables and disables tracing of specific component(s), and diagnoses and resolves applied WebSphere Commerce related software problems, performance problems, and site security problems. The site administrator has advanced configuration skills and a thorough knowledge of the e-commerce solution architecture and the store's business procedures.

Typical tasks by the site administrator The following are the typical tasks of a site administrator:
Performs the advanced configuration, and administers and maintains the site, using WebSphere Commerce and associated software tools.
Creates roles and then assigns roles and access groups to the users, based on their role and position in the organization, such as the following non-inclusive list of the default access groups: – – – – – – – –

160

Business relationship roles (Business Edition only) Customer service roles Marketing roles Operational roles Organizational management roles Product management and merchandising roles Store administrator Web developer and Java programmer

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


Assigns command access levels to access groups and defines who can execute commands and potentially exclude certain users from the command access.
Activates and configures transports and message types for the site, by which administrators, customers, and back-end systems are notified of various events, such as customer orders or system errors, or allows the store administrator to modify these settings, particularly by performing the following tasks: – Adds transports to the site – Activates or deactivates transports for the site – Configures transports for the site (this supplies default configurations that a store administrator can override) – Assigns transports to message types for the site (these assignments can be overridden by store administrators) – Enables error notification to send e-mail messages to administrators – Enables the MQ transport to send messages to the back-end system – Enables order status notification to update customers or administrators on the status of existing orders
Accesses payment processing and administration functions, and completes the setup of WebSphere Commerce Payments: – Views existing users or configures new and existing users – Views existing merchant settings or configures new and existing merchant settings – Views existing WebSphere Commerce Payment settings or configures new and existing WebSphere Commerce Payment settings – Views existing cassette settings or configures new and existing cassette settings – Enables and configures WebSphere Commerce Payments tracing
Enables performance monitoring and monitors site performance.
Leads the performance tuning task.
Schedules jobs to be run for the site.
Configures logging and component tracing for diagnostic purposes and problem resolution.
Handles critical system backups.
Performs security tasks, such as enhancing site security, enabling WebSphere Application Server security, and session management.

Chapter 5. Site and store administration

161


Diagnoses and resolves applied WebSphere Commerce-related software problems, performance problems, and site security problems

Tools used by the site administrator The following are the typical tools used by the site administrator:









WebSphere Application Server Administration Console WebSphere Commerce Configuration Manager WebSphere Commerce Administration Console WebSphere Commerce Accelerator WebSphere Commerce Organization Administration Console WebSphere Commerce Payment Console Performance Monitor WebSphere Commerce Scheduler

5.3.3 Store administrator This section describes the role of the WebSphere Commerce store administrator, tasks performed, and tools used.

Role description for the store administrator Store administrator manages the store archive publishing, changes to taxes, shipping and store information. This role publishes the store from the WebSphere Commerce Administration Console. The store administrator may be a lead on the store development team, and is the only role on the team (except for the site administrator) with the authority to publish a store archive. In larger IT shops, this may be a designated person on the deployment or operations team. This role also configures messaging and manages payments for the store. The store administrator responds to system warnings, alerts, and errors, knows where to find and review the store application logs, and diagnoses and resolves store application problems. This role administers the store data in the store database. The store administrator has a thorough knowledge of the store's business procedures.

Typical tasks of the store administrator The following are the typical tasks of the store administrator:
Publishes the store and manages store tax, shipping, and store information.
Activates and configures transports and message types for the store: – – – –

162

Adds transports to the store Activates or deactivates transports for the store Configures transports for the store Assigns transports to message types for the store

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


Enables and administers Blaze Rules server, manages and maintains rules and rule services, and provides personalized marketing content consisting of advertisements and suggestive selling techniques, which can be summarized into the following two main tasks: – Enable WebSphere Commerce personalized marketing content – Deploy marketing campaigns to a production machine
Accesses payment processing for the store
Schedules jobs to be run for the store, and maintains store data. For example, deletes the following record types using the database cleanup utility: – Members – Guest customers – Temporary customer addresses – Old orders – Messages – 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, Product Advisor statistics, product comparison statistics, and product explorer statistics – Closed or retracted auctions
Maintains store application logs and manages diagnostic store application logging.
Diagnoses and resolves store application problems.

Tools used by the store administrator The following are the typical tools used by the store administrator:





WebSphere Commerce Administration Console WebSphere Commerce Accelerator DB2 Control Center Database Cleanup utility

5.3.4 Database administrator This section describes the role of the database administrator, tasks performed, and tools used.

Chapter 5. Site and store administration

163

Role description of the database administrator The database administrator (DBA) manages and maintains the WebSphere Commerce and associated databases. The DBA has advanced administration skills for DB2 or Oracle database. The DBA responds to system warnings, alerts, and errors, knows where to find database logs and maintains them, and diagnoses and resolves database problems. The DBA typically is involved in advanced customization when database schema modifications are needed, and is involved in the performance tuning task. The DBA has thorough knowledge of the back-end architecture of the e-commerce solution.

Typical tasks of the database administrator The following are the typical tasks of the database administrator:
Schedules database maintenance
Generates access plans
Manages and maintains the WebSphere Commerce and associated databases, by performing the following tasks: – – – –

Manages table space Reorganizes tables Monitors databases use Uses Database Cleanup utility


Maintains database logs and manages diagnostics information logging
Defines disaster recovery strategy
Maintains correct code level
Monitors database performance and is involved in the performance tuning task and database tuning task
Diagnoses and resolves database problems

Tools used by the database administrator The following are the typical tools used by the database administrator:







164

Database administration tools such as the DB2 Control Center SQL Database command line (DB2 commands, Oracle commands) CLI Trace Parser Database Cleanup utility WebSphere Commerce Configuration Manager

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

5.4 Line-of-business user roles and tools This section provides a summary of the line-of-business (LOB) user tasks and tools used to manage the WebSphere Commerce store for the following roles:







Business relationship roles Customer service roles Marketing manager role Operational roles Organizational management roles Product management and merchandising roles

The primary administration tool used by the line-of-business user roles is the WebSphere Commerce Accelerator.

5.4.1 Business relationship roles The business relationship roles are as follows and only apply to the WebSphere Commerce Business Edition:
Account representative
Sales manager
Channel manager

Account representative The account representatives work with individual accounts to build relationships, and manage customer service issues. They may be authorized to change contract pricing, negotiate contracts, profiles, and analyze profitability by account category.

Sales manager The sales managers acquire and retain customers, meet sales forecasts, provide incentives for increased customer business, handle contract management, set pricing terms, and work with the product management team to establish inventory forecasts, and with the marketing manager for promotions. They also manage across accounts, assign accounts, and approve contracts of account representatives.

Channel manager The channel manager manages the channel store, as well as maintains the relationship between distributors and resellers, including creating and importing distributor and reseller contracts. The channel manager is also responsible for acquiring and retaining more resellers and distributors for the marketplace.

Chapter 5. Site and store administration

165

5.4.2 Customer service roles The customer service roles are as follows:
Customer service representative (CSR)
Customer service supervisor

Customer service representative (CSR) The customer service representative provides support for all inquires to customers via Customer Care instant messaging provided by Lotus Sametime, e-mail or phone. The CSR primarily uses the WebSphere Commerce Accelerator and Customer Care to assist customers using the consumer direct and B2B direct store models.

Customer service supervisor The customer service supervisor role has access to all customer service tasks. The customer service supervisor manages customer inquiries (such as customer registration, orders, returns, and auctions) and has authority to complete tasks that cannot be accessed by a customer service representative, such as approving system-denied returns records, and contacting customers regarding payment exceptions (such as credit card authorization failures). The customer service supervisor primarily uses the WebSphere Commerce Accelerator and Customer Care (manage CSR queues) to manage the CSRs and assist customers using the consumer direct and B2B direct store models.

5.4.3 Marketing manager role The marketing manager communicates the market strategy and brand messages to the customers. This role 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. The marketing manager handles e-mail campaign capability and campaign initiatives including suggestive selling and awareness advertising. Campaign event planning can be handled by a team comprising the seller, marketing manager, and merchandising and product development.

5.4.4 Operational roles The operational roles are as follows:






166

Seller Logistics manager Operations manager Receiver Returns administrator

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


Pick packer

Seller The Seller supervises the overall store objectives and management, in addition to tracking store sales. The Seller is also responsible for store-wide functions such as defining shipping charges, and opening and closing the store. The Seller role is equivalent to a merchant in the consumer direct model, a manufacturer in the B2B direct model, and a distributor or other owner in the reseller hub. The seller has access to all WebSphere Commerce Accelerator capabilities to manage the consumer direct, B2B direct, hosting, Supply Chain and Demand Chain store models.

Logistics manager The logistics manager, sometimes called the shipping manager, manages and negotiates bulk freight/shipping from carriers to warehouse, and to individual customers.

Operations manager This role manages order processing, ensuring that orders are properly fulfilled, payment is received, and orders are shipped. The operations manager can search for customer orders, view details, manage order information, and create and edit returns. For the reseller and hosting models, this role is responsible for customer service, and oversees customer service in the other models.

Receiver The receiver receives inventory at the fulfillment center, tracks expected inventory records and ad hoc receipts for ordered products, and receives returned products as a result of customer returns.

Returns administrator The returns administrator manages the disposition of returned products.

Pick packer The pick packer picks products from fulfillment centers and packs the products for shipping to customers. The pick packer also manages pick tickets and packing slips that are used to confirm shipment of products during order fulfillment.

Chapter 5. Site and store administration

167

5.4.5 Organizational management roles WebSphere Commerce provides the following roles in the organizational management area:





Seller administrator Buyer administrator Buyer approver Buyer (buy-side)

Seller administrator The seller administrator manages users in the seller organization as well as manages organizations that the seller organization deals with. The seller administrator can also approve user registrations, customer orders, RFP responses, and contract summaries.

Buyer administrator The buyer administrator is similar to the seller administrator, but the only difference is that this role is for the buyer organization. So, this role manages users in the buyer organizations and manages organizations that the buyer organization deals with. Moreover, the buyer administrator can also approve customer registrations, customer orders, RFP responses, and contract summaries.

Buyer approver The buyer approver role can only approve customer registrations, customer orders, RFP responses, and contract summaries for the buyer organization.

Buyer (buy-side) The buyer in the buyer organization can only order products through the store front of seller organizations. This role has no administrator privileges.

Procurement buyer administrator The procurement buyer administrator registers users as procurement buyers. They create and administer the suborganizations within their buying organization and manage the various users, including approving users as buyers.
Registers users as procurement buyers.
Accesses and executes procurement system integration related commands.

Procurement buyer (buy-side) The procurement buyer is an individual who belongs to a buyer organization that uses a procurement system to connect to WebSphere Commerce. Procurement buyers are registered when a request comes from the procurement system.

168

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Procurement buyers use the account belonging to their buyer organization to make purchases from the seller. After purchasing, the procurement buyer sends their order to the procurement system for approval.

5.4.6 Product management and merchandising roles The product management and merchandising roles are as follows:
Product manager
Category manager
Buyer (seller-side)

Product manager The product manager traces customer purchases, suggests discounts, and determines the best way to display, price, and sell products in the online store.

Category manager The category manager manages the financial success of a category of products. The category manager also manages the category hierarchy by creating, modifying, and deleting categories. The category hierarchy organizes products or services offered by the store. The category manager manages products, expected inventory records, vendor information, inventory, and return reasons.

Buyer (seller-side) The buyer buys merchandise for sale. The buyer handles relations with vendors or suppliers and negotiates to obtain the desired product with favorable terms for such things as delivery and payment options. The buyer may set prices. Inventory is managed by the buyer in order to determine the quantities to buy and ensure that stock is properly replenished.

5.5 For more information For more information on managing a WebSphere Commerce site and store, refer to the following:
Fundamentals Guide, IBM WebSphere Commerce V5.5
Administration Guide, IBM WebSphere Commerce V5.5
IBM WebSphere Commerce V5.5 online documentation

Chapter 5. Site and store administration

169

170

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Part 2

Part

2

Development guidelines This part of the redbook provides IT architects and developers with design and development guidelines for an e-commerce development methodology, development environment, build cycle, and globalization.

© Copyright IBM Corp. 2003. All rights reserved.

171

172

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

6

Chapter 6.

WebSphere Commerce site development methodology In this chapter we introduce a project development methodology that was specifically adapted for the creation of e-commerce sites using the IBM WebSphere Commerce family of software products. After reading this chapter, you should have a clear understanding of the following topics relevant to the development methodology:
Key development phases
Actions and terms
Deployment conditions Note: This chapter is based on the Best Practices and Tooling for Creating IBM WebSphere Commerce Sites, REDP3616 redpaper. We encourage you to read this redpaper for more detailed information.

© Copyright IBM Corp. 2003. All rights reserved.

173

6.1 Systematic development methodology Gone are the days when creating e-commerce sites was considered a fine art requiring highly specialized skills. e-commerce development has become a rather mature field since first introduced in the mid- to late-1990s. Experience proves that using a systematic methodology to develop software applications for e-commerce systems greatly reduces project risk and improves proper alignment of software functionality with customer business requirements, two key influencers of project profitability and customer satisfaction. The key characteristics of a systematic development methodology are:
It uses a systematic software development method.
The method has been validated and refined via empirical experience gained through e-commerce development.
The framework of the methodology is centered around established project management principles to help define work products, deliverables, and timeline (or phases) to deliver software on time and within budget, to meet customer's business needs. The methodology to be outlined in this chapter will be flexible to support the creation or transition of both small- and large-scale e-commerce sites. Prior to introducing the methodology, this chapter will first identify and define relevant terminology that will be used through the remainder of the redbook.

6.2 Definitions The methodology documented in this redbook uses specific terminology with unique connotations. To improve your understanding of the project development methodology, this redbook begins with an overview on the terminology definitions. This section establishes a vocabulary that will:
Be used through the remainder of the redbook
Will enable you use this vocabulary when communicating and sharing knowledge of the methodology with others

6.2.1 Phase The development methodology consists of a set of time- or function-bound phases (for example, the design phase). From a systems view, a phase has very clear input and output work products (for example, the customer requirements document). A phase takes one or more work products and performs a set of activities or tasks to enhance existing work products or create new work

174

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

products. A phase is generally closed before starting the next one in the sequence. A phase can have zero or more subphases. In this redbook the word phase refers to both a phase and a subphase of a project. Note: Other industry methodology standards may use the term activity as a subdivision of a phase.

6.2.2 Work products Work products are tangible pieces of information or artifacts that can be created, shared, and communicated. For example, work products may be:





An education or training roadmap A macro design document Deployment code An e-commerce database with customer information

6.2.3 Deliverable A work product becomes a deliverable when it has been highlighted in a contractual document that has been signed by both the customer and a services provider, such as a Statement of Work (SOW) or a Document of Understanding (DOU).

6.2.4 Customer The customer should be viewed as one who either owns an e-commerce site or who wishes to develop an e-commerce site. In either case, the customer defines and approves the business requirements for the e-commerce site.

6.2.5 Customer IT team A team consisting of one or more members, each assigned by the customer, that is responsible for maintaining the customer e-commerce site and associated computing infrastructure such as the back-end or legacy systems.

6.2.6 Project team Owing to its responsibilities, the project team is prominently positioned with the methodology in this redbook, as the methodology seeks to emphasize the activities of this team. Since a project team may consist of subteams, such as a design team or test team, the appropriate subteam will be identified by name if a methodology task is

Chapter 6. WebSphere Commerce site development methodology

175

its responsibility. In other words, the project team will be the primary reference team used either explicitly or implicitly throughout this book unless specified otherwise. In terms of projects, a project team is sanctioned and supported by the customer during an in-house project. During a consulting engagement, the project team is controlled and supported by outside services organizations, such as ISSW, IGS or IBM Business Partners. No matter what the allegiance of the project team is, all should carefully assess project execution and control requirements whenever team members will be geographically dispersed. The assessment would typically be based upon evaluation of factors such as frequency of communication, the quantity and nature of control information supplied, and the difference between expected and observed progress in project execution. Each project manager or leader will need to understand the working relationships between team members to plan and coordinate project activities appropriately, especially when the teams reside in different locations. This topic is an import part of project management discipline, such as the PMI standard adopted by IBM. However, as further information on implications of dispersal on projects would be available from a project management specialist, we do not discuss the topic further in this redbook.

6.2.7 Project database A database of project-specific information should be established and maintained for all team members to access. This would hold background information, reports, minutes of meetings, results of discussions, and indeed any other kind of information that is relevant to the execution of the project. The project database could be implemented using any available tool, for example a Lotus Notes® database. It may be better to make use of collaborative facilities such as those provided by Lotus QuickPlace, which supports not only team information and resources sharing, but can also support controlled external access by customers using Web browsers.

6.2.8 Task A task is an activity that is performed during one or more phases of the project. A typical project phase generally involves many tasks, and each may be executed either sequentially or in parallel with one another. In addition, depending on their individual requirements, tasks may be completed by individual team members or distinct teams or subteams.

176

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

A task is likely to require input in the form of work products, and once it has been completed, it will produce one or more output work products. For example, when creating a database, you would require a data model for the target database to define and create the database schema. When complete, the target database may then be populated with customer or sample data to create the required database. In this case, the input work products necessary to create a sample database are:
The data model
The database schema
The sample data The output work product of the database task is:
A sample database ready to be used by the project team during the implementation phase The scope of a project task can be contained within a single phase or across multiple ones. An example of multi-phase task is the creation of a WebSphere Commerce design. This task can be completed by one or more team members, using most of the output work products from the Pre-sales phase. The output of the design task would normally be a set of work products that are listed as output from the Micro design phase. Ideally, tasks are completed within their parent phases. However, under some circumstances, often dependent on the task itself, it may be necessary to revisit a task during a later phase. This is particularly the case when later work uncovers an issue that must be revisited, such as modification to a database design. Such situations should be considered exceptions, and treated as such.

6.2.9 Strategy In terms of this redbook, a strategy is a method for executing a task. A project team may execute tasks in a variety of ways to produce desired output work products. Therefore, many strategies may be used to complete specific project tasks and create the associated output work products. Since a strategy is associated with a task, its scope may reside within a single phase or span multiple ones. For example, the Test Phase, which is one of the main phases of the overall methodology, may require tests be completed during each subphase. If so, then the tests would likely include functional verification, system and user-acceptance testing. On the other hand, all testing may be combined under a comprehensive test plan, such as System Verification Test and User-acceptance Testing.

Chapter 6. WebSphere Commerce site development methodology

177

Each strategy possesses factors that influence its selection by the project team as the strategy for a particular project phase or phases. Factors most likely to influence a project team's decision making process are:
Resource skill level
Business requirements
Availability of tooling or aids to streamline tasks Before pursuing any one given strategy, you are strongly encouraged to assess and compare the advantages and disadvantages of potential candidates to select the appropriate ones given your project's requirements.

6.3 Development methodology: phase and life cycle Figure 6-1 on page 179 illustrates the six phases of a typical project development methodology. Within this redbook, we focus on four core phases, which are:





Design Implementation Site testing Deployment

Please note that the four core phases are positioned between pre- and post-project phases normally. In Figure 6-1 on page 179, the pre-project phase is called Pre-sales, while the post-project phase is defined as Site maintenance/enhancements. Note: The Best Practices and Tooling for Creating IBM WebSphere Commerce Sites, REDP3616 includes chapters for each of the phases listed.

178

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Project start (WebSphere Commerce Suite source version)

Project end (WebSphere Commerce target version)

Project duration

Pre-sales

Design

Implementation

Site testing

Deployment/ launch

Site maintenance/ enhancements

Phases Figure 6-1 A phase-based project development methodology

Once the e-commerce site has been launched, any new modifications added to the site after the project ends should be managed as functionality enhancements. During the lifetime of the e-commerce site, one or more of the methodology phases may be repeated as necessary to facilitate enhancements. Typically, repeated implementations of the methodology will be required to incorporate significant enhancements to the site, such as new versions of WebSphere Commerce software or updates, or to accommodate changing business requirements.

6.3.1 Core development phases In Figure 6-2 on page 180, each of the core development phases is positioned along with its likely subphases. Please note that the subphases tend to be iterative, and in some instances, may even overlap each other. It is important to understand that proper assessment of a project will help determine which, if any, of the subphases apply. Also note that subphase relevance and scope will vary from project to project.

Chapter 6. WebSphere Commerce site development methodology

179

Design phase: Solution outline Macro Micro Iterative design

Implementation phase: Iterative coding, unit and use-case level integration testing Sub-system level integration testing Site testing phase: FVT SIT SVT UAT Deployment/ launch phase: Deployment Site launch

Figure 6-2 The main phases of the project development methodology

Pre-sales phase The customer must consider, assess, and plan an e-commerce site carefully. Understanding site requirements, defining the nature and intricacies of the existing site for transition projects, and documenting the required features and functions of the target WebSphere Commerce site are key customer activities that should be completed during this phase. Please note that special attention

180

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

should be paid to adequately define and document business requirements as opposed to technical constraints or implementation details. A common event during this phase is for the customer to request estimates of resources required, time to develop, and other details such as the machine specification required to host the final site. The intention is to use the provided numbers for budgeting or sizing purposes. It may be possible to provide extremely rough estimates, based on similar previous projects. It would be impractical to provide more accurate figures until later in the project.

Design phase The design phase marks the beginning of the WebSphere Commerce project and consists of the following three subphases:
Solution outline
Macro design
Micro design Taken together, these subphases represent incremental and iterative design activities that enable the project team to define the target system details.

Implementation phase During the implementation phase, the project team focuses on coding the design that resulted from design phase activities. This phase also includes continuous and incremental unit testing, and the integration of required software components.

Site testing phase The site testing phase covers several formal subphases, all of which enable the project team to test the newly developed or transitioned e-commerce site assets systematically.

Deployment/launch phase During the deployment/launch phase, the project team assists the customer IT team to bring the e-commerce site to a production-ready state, and as required by the customer, to support and help its IT team to enable the site.

Site maintenance and enhancement phase During this phase no new major design activities are undertaken, as all customer IT team activity centers on maintaining or enhancing current site functionality to satisfy new or changing business requirements. The duration of site maintenance and enhancement can range from a few months to several years, and all activity should center on maintaining and enhancing established site functionality to support new or changing business requirements.

Chapter 6. WebSphere Commerce site development methodology

181

It is possible that one or more significant site improvement projects may be initiated during the enhancement period, perhaps to reflect a new customer branding scheme. Architecturally, however, the site implementation will remain largely unchanged. The lifetime of an e-commerce site stretches beyond the time period for the WebSphere Commerce project itself, shown as the “Project Duration” in Figure 6-1 on page 179. The overall site lifetime can be viewed as a sum of project durations, including transitioned projects and the maintenance and enhancement phases. Not all site transitions are as complex as moving from WebSphere Commerce Suite V4.x or older versions to WebSphere Commerce V5.x or higher versions. For example, moving from WebSphere Commerce V5.1 to WebSphere Commerce V5.4 will require only a fraction of the effort that is required for transitioning WebSphere Commerce Suite V4.x to WebSphere Commerce V5.x. The key reason for the difference between the work efforts is the technology change in the programming models: Version 4.x is built on Net.Data® and C++, while Version 5.x uses JSP and Java/J2EE exclusively.

6.4 Using the methodology Using the methodology effectively involves certain considerations that will be elaborated below. Your understanding the implications and requirements for each of the several considerations outlined here will improve your ability to employ the methodology during any given project. Understanding these considerations is important to help you adapt the methodology presented here to meet specific requirements of the development work for a given project. For example, the methodology presented in this redbook provides guidelines for deciding between the use of all the design subphases (solution outline, macro- and micro design), or combining one or more subphases within a given e-commerce project. Understanding and carefully evaluating these guidelines, and applying the results to an e-commerce project, will increase the chance of the project manager making the best decision for the project, and so increase the probability of success.

6.4.1 Customizing and adopting the methodology It is possible to customize this methodology such that it could be applied to building all types of e-commerce sites using IBM WebSphere Commerce software. This includes different business models (B2B, B2C, hosting, Supply Chain, Demand Chain), which may be small, medium or large in size.

182

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

For each phase, this redbook describes core strategies that aid the project team to complete key tasks. Approaches for customizing the methodology are also provided to enable project teams to tailor it to specific project requirements. All the strategies identified in this redbook are grounded in best practices that ISSW derived from actual WebSphere Commerce projects and engagements.

6.4.2 New and transition sites There are two scenarios for creating a commerce site. The first is where a new site is developed, normally using WebSphere Commerce V5.5 or possibly WebSphere Commerce V5.4. The second scenario focuses on transitioning older sites, typically based on WebSphere Commerce Suite V4.1, V5.1 or V5.4, to newer versions of the product, normally WebSphere Commerce V5.5. The emphasis here will be on transition projects that are migrating e-commerce sites from WebSphere Commerce Suite V4.x or older versions to the Java/J2EE releases of WebSphere Commerce V5.x or higher versions. With regard to the terms migration and transition, each can be used interchangeably to describe the task of updating WebSphere Commerce sites or assets.

6.4.3 Project roles and skills requirements Any given project will have specific role and skill requirements. In terms of this redbook, most of the activities will be described from the perspective of either a project manager or a WebSphere Commerce architect. The purpose of this book is to enable project managers, WebSphere Commerce architects, designers and developers to define, plan and execute WebSphere Commerce projects efficiently by providing appropriate guidance, recommendations and examples. Common roles and skills needed for typical WebSphere Commerce projects are discussed in detail in the redpaper Best Practices and Tooling for Creating IBM WebSphere Commerce Sites, REDP3616.

6.4.4 Structuring information Each section detailing a phase or subphase from the development methodology begins with a table that summarizes phase requirements, inputs and outputs. This table is structured so that the reader may refer to it at any given time to review the phase's core components. Since each phase and subphase is likely to have a corresponding list of tasks requiring completion, each task may have one or more execution strategies. Some tasks and strategies will be discussed in detail, while others will only receive cursory mention. Strategy tables are provided to summarize the elements and rationale for each strategy so as to enable the reader to select an

Chapter 6. WebSphere Commerce site development methodology

183

appropriate one to complete a task. Please note that the development methodology may accommodate many strategies, so the reader is encouraged to develop strategy tables, using the templates provided, when building project plans. Also, the reader is encouraged to assess and review all strategies first, prior to selecting one to proceed with. The following recommendations will aid your developing appropriate project plans:
It is very important that the main phases of the project development methodology should never be ignored or skipped when building a project plan.
In principle, the subphases of this methodology can be combined, overlapped, deleted, replaced with other subphases, or supplemented by new subphases to suit project needs.
The list of tasks and strategies that are specified in this redbook represent a subset of the possible tasks and strategies that could be applicable during a project. We would recommend adding new and relevant tasks and strategies when creating a project plan.
Prior to customizing any subphases, fully assess the associated advantages and disadvantages of the customizations. All the tasks and strategies listed in this redbook are based upon best practices gained from direct experience.

6.4.5 Case studies While describing the various phases and tasks of the development methodology, we provide examples to aid your understanding the phase or task. Many of the examples were inspired by case studies of real projects. The examples will provide concrete scenarios for you to use and adapt during your planning efforts.

6.5 Related methodology concepts This redbook uses specific terminology to describe a WebSphere Commerce development methodology. The terms are in common use within the Toronto-based IBM Software Services commerce team, and originate from IBM Global Services terminology, subsequently adapted for WebSphere Commerce implementation projects. We consider other methodologies used within IBM or as part of engagements where IBM consultants work with customers on implementation projects. The literal terms used in this redbook are less significant than the concepts they embody, with the proviso that all consultants and developers working on a project must have an agreed and common understanding of the terms being used.

184

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Note: It is not possible to provide significant detail for the methodologies within the scope of this redbook. In deciding the methodology and terminology to be used, the starting point should be to assess:
Project team and customer team familiarity with existing methods and terms
The match between the conceptual model that underpins the method and the project requirements For example, a project team that has worked with the customer team on previous projects is likely to have developed their own local interpretation or ”dialect” of terms that have evolved as an optimized amalgamation of standard methods and terms. It would be unwise to discard the procedural and teaming benefits of this localization, as long as the basic rigor of the method is maintained. Similarly, a methodology that focuses on code implementation using an object-oriented model may be inappropriate to use on a project that simply requires re-configuration of standard components rather than development of code using an object-oriented language.

6.5.1 IBM Method Not surprisingly, IBM has a well-established discipline for managing development projects. Within that context, there will be development methodologies that are optimized according to the nature of the project work. For example, the process of designing and developing a system performance assessment tool may have differences when compared with the design and development of an embedded hardware component for a point-of-sale terminal. The intent is to ensure that a balance is found between a process that is insufficiently structured and so allows freedom and flexibility but is hard to measure and document, against a process which is too structured and thus constrains creativity and which may be bureaucratic or slow.

6.5.2 Rational Unified Process® (RUP®) The Rational Unified Process (RUP) is a software engineering process. Its purpose is to provide a disciplined approach to identifying and assigning tasks and responsibilities within a development project. RUP is intended to be configurable according to project circumstances. The complexity of most significant development projects make it unlikely that a simple sequential development model will succeed; rather an iterative process

Chapter 6. WebSphere Commerce site development methodology

185

must be applied where earlier steps will be revisited and refined in the light of subsequent understanding and progress on the problems and tasks. RUP supports iterative development in several ways, for example using frequent test releases of code or assets to allow customer testing, verification, and feedback. RUP identifies four development phases:





Inception Elaboration Construction Transition

Table 6-1 shows how the RUP phases correspond approximately to the phases identified within this redbook. Table 6-1 Comparison between RUP and e-commerce RUP

e-commerce methodology

Inception

Pre-sales

Elaboration

Design phase * Solution outline * Macro design * Micro design

Construction

Implementation and testing * Project implementation * Functional Verification Test * System Integration Test * System Verification Test * User Acceptance Test

Transition

Site deployment and launch

6.6 Summary In this chapter, we defined a project development methodology that can be used to develop new e-commerce sites or to transition existing sites built with earlier versions of WebSphere Commerce software. Having reviewed this chapter, you should be able to:
Describe the core phases of the development methodology
Define key development terms and concepts
Discuss relevant deployment conditions

186

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

7

Chapter 7.

Development environment and build cycle In past releases of WebSphere Commerce, customers had the burden of inventing a development and team environment that worked best for their environment. This can be a very costly and time-consuming process and the skill and knowledge level required to architect such a framework is demanding. Previous versions of WebSphere Commerce Studio (VisualAge for Java and WebSphere Studio “classic”) did not support an integrated and well-defined team environment that was reliable and provided an efficient build environment. The environments for development, build, and team are closely related, thus we will describe them together. With the help of the team environment support in WebSphere Studio Application Developer, it is now possible for team members to do their work in their own workbenches, and merge work into a team repository. The build environment can retrieve the latest changes and produces a driver that can later be used for testing and production. This chapter includes the following sections:





WebSphere Commerce Studio overview Team development environment overview Build environment overview Deployment overview

© Copyright IBM Corp. 2003. All rights reserved.

187

7.1 WebSphere Commerce Studio overview Developing or programming is an activity in which you produce code artifacts (or components) according to various design and coding specifications. A development environment is a programming environment where an integrated development workbench tool, such as WebSphere Studio Application Developer, is used for coding, debugging, and unit testing. The development package for creating customized code to be used with WebSphere Commerce is called WebSphere Commerce Studio. This product package includes all the tools required to create customized code and perform Web development tasks. With this development environment, you can create customized code and test it within the context of the WebSphere Test Environment. There are four main components of WebSphere Commerce Studio:





WebSphere Commerce Studio workspace WebSphere Commerce Studio plug-ins Development environment WebSphere Commerce instance database File system assets

7.1.1 WebSphere Commerce Studio workspace Before getting into the design details of the WebSphere Commerce Studio workspace, let us review what a J2EE application server is. The application server collaborates with the Web server to return customized responses to client requests. Application code including servlets, JavaServer Pages (JSPs), Enterprise JavaBeans (EJB) components, and their supporting classes run in an application server. In keeping with the J2EE component architecture, servlets and JSPs run in a Web container, and enterprise beans run in an EJB container. In WebSphere Application Server, a J2EE application is represented by, and packaged in, an enterprise archive file, called an EAR. Once you have the EAR file created, then you are ready to deploy the application to a J2EE application server. The WebSphere Commerce Server is a J2EE application that has:
Presentation layer: Consists of a number of Web modules, running in the Web container.
Processing layer: Consists of a group of EJB modules, running in the EJB container. WebSphere Studio Application Developer has a similar EAR concept to represent a J2EE application; it is done via the concept of a workspace. Each

188

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

J2EE artifact in the EAR file can be mapped to a corresponding J2EE project in WebSphere Studio Application Developer.

Figure 7-1 WebSphere Commerce Studio EJB, Web modules

The WebSphere Commerce Studio workspace is composed of a number of EJB, WAR, and Java projects (see Figure 7-1). Each business component in WebSphere Commerce Server can be grouped into one or more sets of projects.

Chapter 7. Development environment and build cycle

189

Only for Studio

Presentation Layer

Organization Administration

Commerce Accelerator

Stores

Proxy Proxy

Trading

Proxy

Payment

Member

Merchandising

Marketing

Catalog

Order Management

Site Administration Processing Layer

Proxy

Enablement Figure 7-2 WebSphere Commerce presentation and processing layers

The idea is to have a clear separation between the presentation layer and the processing layer (see Figure 7-2):






Presentation layer that runs in the Web container JSP, HTML, static images, JavaScript Processing layer that runs in the EJB container Data objects - session and CMP entity EJBs Logic code - commands and data beans

Processing layer The WebSphere Commerce Server is composed of the following subsystems:









Catalog Marketing Merchandising Member Order Management Payment Trading Enablement

The Enablement subsystem is the foundation of the product that the other subsystems depend on. Within each subsystem, there are several business components that further partition the subsystem into many related but functionally different models. The WebSphere Commerce Studio workspace provides a logical breakdown of these business components and presents a

190

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

structure inside of WebSphere Studio Application Developer for the purpose of code customization. Each business component in WebSphere Commerce Studio can be grouped into one or more set of projects. Each of these project groups exists in pairs - for each EJB project, there should be a corresponding Java project. All EJB data objects for a particular subcomponent go into an EJB project, and for the rest of its business-related logic non-EJB codes, they go into a Java project. An EJB project and a Java project for customization have been created and configured to run with the WebSphere Commerce Server. All customization code should be placed into one of these two modules, depending on the type of Java code being put in.

Presentation layer There are four Web projects in the WebSphere Commerce Studio workspace:





Commerce Accelerator Organization Administration Site Administration Stores

There is no Java code placed inside of these Web modules; only JSPs are put in here. A special type of Web server alias proxy project is introduced to handle Web server aliases. These special Web alias proxy projects are only needed for the WebSphere Test Environment and cannot be exported along with the EAR file to the WebSphere Application Server runtime environment. The main reason for introducing this type of project is because WebSphere Studio Application Developer WebSphere Application Server lacks the ability to interact with Web servers and therefore static images, JavaScript, and HTML pages used in a Web alias cannot be resolved. A Web alias proxy project is indeed a Web project with the context root set to serve the required Web alias. Within the project is a simple file-serving servlet that is used to handle loading file assets from other Web modules. Only one Web alias can be served per Web alias proxy project.

Workspace elements The WebSphere Commerce Studio workspace is a collection of EJB, Web, and Java projects. Each of these projects consists of a mixture of both binary and source files. Source files are only shipped and packaged into the WebSphere Commerce Studio workspace if they belong to public components, which you can customize or make extensions to. Binary files on the other hand are included, but

Chapter 7. Development environment and build cycle

191

in a separate binary folder, in order to get the product to work properly and for the source code to compile successfully. The following few sections describe the structure of each WebSphere Commerce Studio project type and their contents.

EAR projects The structure of EAR projects is as follows: EAR project META-INF/ application.xml ibm-application-ext.xmi lib/ *.jar properties/ *.properties .project An Enterprise Application project contains the hierarchy of resources that are required to deploy an enterprise (J2EE) application. It can contain a combination of Web modules, EJB modules, JAR files, and application client modules. It includes a deployment descriptor and an IBM extension document as well as files that are common to all J2EE modules that are defined in the deployment descriptor. Enterprise Application projects are exported as EAR (enterprise archive) files that include all files defined in the Enterprise Application project as well as the appropriate module archive file for each J2EE module project defined in the deployment descriptor, such as Web archive (WAR) files and EJB JAR files. The following two files are created in the EAR project:
application.xml Deployment descriptor for the enterprise application, as defined in J2EE 1.3. This file is responsible for associating Web and EJB projects to a specific EAR file. An editor is also provided for this file that is launched either by double-clicking the file in the navigator, or selecting the EAR file in the J2EE view and choosing the Open in Editor item from the context menu.
ibm-application-ext.xml IBM-specific extensions to the enterprise application. Similar to those defined in ibm-web-ext.xml Web module extension file, but with scope across the whole application.

192

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

As the name of the project already indicates, only application level resources can be found here. What goes into the lib directory is the third-party JARs, the application level utility JARs and properties files.

Web project The Web project structure is as follows: Web project Java Source/ *.properties Web Content/ META-INF/ MANIFEST.MF WEB-INF/ classes/ *.properties lib/ ibm-web-bnd.xmi ibm-web-ext.xmi web.xml images/ *.jpg *.jsp *.html .classpath .project A WAR file has a specific hierarchical directory structure. The top-level directory is the document root of the application. The document root is where JSP pages, client-side classes and archives, and static Web resources are stored. The document root contains a subdirectory called WEB-INF, that contains the web.xml deployment descriptor, tag library descriptor files, classes, and lib directories. The Web project uses a J2EE directory structure in organizing the following folders and files:
Java Source The source folder contains the project Java source code for properties files. When resources are added to a Web project, they are automatically compiled and the generated files are added to the Web Content/WEB-INF/classes directory. Contents of the source directory are not packaged in WAR files.
Web Content The webApplication folder contains the contents of the WAR file that will be deployed to the server. It contains all the Web resources, including HTML

Chapter 7. Development environment and build cycle

193

files, JSP files, and graphics needed for the application. Any files not under Web Content are considered development resources, such as .java and .sql files, and will not be deployed when the project is unit tested or published.
Web Content/WEB-INF The Web Content/WEB-INF folder contains the supporting Web resources for a Web application, including the web.xml deployment descriptor file and the classes and lib directories. – Web Content/WEB-INF/classes The Web Content/WEB-INF/classes folder contains the Java compiler output directory. The classes in this directory are used by the application class loader to load the classes. Folders in this directory will map package and class names. The .class files are automatically placed in this directory when the Java compiler compiles the source files from the source directory. Any files placed directly in this directory will be deleted by the Java compiler when it runs. – Web Content/WEB-INF/lib The Web Content/WEB-INF/lib folder supports .jar files that your Web application references. Any classes contained in these .jar files will be available for your Web application. The default directory structure in the Web project adheres to the J2EE specification. This specification defines a project directory structure that specifies the location of Web content files, class files, class paths, deployment descriptors, and supporting metadata. The Web project hierarchy mirrors that of the Web application created from a project. The Web Content folder contains all of your Web resources, including HTML, JSP, graphic files, cascading style sheet, web.xml (deployment descriptor), classes, and lib folders (not served directly to a client). For Web application development, the key files managed in a Web project are:
web.xml Deployment descriptor for the Web module, as defined in J2EE 1.3. This file contains general information about the Web application, including servlet mappings, security information, and the welcome page.
ibm-web-bnd.xml WebSphere bindings for the Web application. This file contains bindings to references used at the Web module level as defined by IBM. J2EE provides a mechanism to use local names for external resource objects. However, the J2EE specification does not define how these objects are referenced at runtime. This implementation is left to vendors to implement in their own way, and this file is IBM's implementation.

194

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


ibm-web-ext.xml IBM-specific extensions to the Web module. This file is used by WebSphere to support additional options beyond the J2EE specification such as reloading intervals, the default error page and if file serving is allowed and servlet invoking are enabled in the Web module.
.classpath Application Developer uses this file to store metadata about the build path for the project when compiling Java classes and executing Java applications.

EJB project The core components of an EJB projects are source and binary folders, XML-based deployment descriptors, and industry standard files as seen in Example 7-1. Example 7-1 EJB project deployment descriptor EJB project ejbModule/ com/ibm/commerce/...../objects/EJBNameHome.java com/ibm/commerce/...../objects/EJBNameHome.class com/ibm/commerce/...../objects/EJBNameRemote.java com/ibm/commerce/...../objects/EJBNameRemote.class com/ibm/commerce/...../objects/EJBNameBean.java com/ibm/commerce/...../objects/EJBNameBean.class com/ibm/commerce/...../objects/EJBNameKey.java com/ibm/commerce/...../objects/EJBNameKey.class com/ibm/commerce/...../objects/EJBNameAccessBean.java com/ibm/commerce/...../objects/EJBNameAccessBean.class com/ibm/commerce/...../objects/EJBNameAccessBeanData.java com/ibm/commerce/...../objects/EJBNameAccessBeanData.class META-INF/ schema/ *.schxmi *.tblxmi ejb-jar.xml ibm-ejb-access-bean.xmi ibm-ejb-jar.bnd.xmi ibm-ejb-ext.xmi map.mapxmi MANIFEST.MF .imported_classes.jar .imported_sources.jar .classpath .project

Chapter 7. Development environment and build cycle

195

EJB projects allow you to organize your enterprise beans logically. As you develop EJB applications in the workbench, by default your source and output files will be kept in the ejbModule folder of the EJB project. As you make changes and generate deployment code, the Java classes are compiled into the ejbModule folder.
.classpath Is the WebSphere Studio Application Developer internally used build time classpath for the EJB project.
.imported_classes.jar Is the binary JAR for the production version of byte code within the EJB project. No source files will be found inside of it. On an EJB JAR export, the contents of the .imported_classes.jar are merged into the resulting EJB JAR. That is, the exported JAR file will be a single archive that contains the merged contents of the Java output folder of the EJB project and the .imported_classes.jar. Here, in the case of name collisions, the project contents take precedence over files inside of the .imported_classes.jar. The following four classes are used to compose a single entity EJB:
EJBNameHome The home interface. This is a factory which is used to create and find instances of the EJB.
EJBNameRemote The remote interface. This class determines which methods can be remotely invoked.
EJBNameBean The bean class. This is where the logic is defined for the methods in the EJB.
EJBNameKey The key class. Optional. When performing top-down persistence with simple keys, this is used to represent the unique key for the entity. Three additional classes are used for the above implementations. However, these files are placed in a separate Java package and will only be shipped as binary format without source code:
EJBNameHomeBase The implementation of the home interface.
EJBNameRemoteBase The implementation of the remote interface.

196

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


EJBNameBeanBase The implementation of the bean class. Each of these classes appear in the Navigator view as .java files in the package folder defined in the mapping wizard. Generated EJB metadata also shows that three additional XMI files are generated by the mapping wizard in our EJB project. These are as follows:
ejb-jar.xml The deployment descriptor for this EJB module
ibm-ejb-jar-bnd.xmi WebSphere bindings for the EJB module
ibm-ejb-jar-ext.xmi WebSphere extensions for the EJB module
map.mapxmi The mapping between the EJB and the database schema

EJB project - multiple database back-end support Before you can successfully run your enterprise beans on either a test or production server, you need to generate deploy code for the enterprise beans. The EJB Deploy tool provides an interface that you can use to generate enterprise bean deploy code. The tool employs a command-line environment that also allows you to run a build process overnight and have the deployment tool automatically invoked to generate your deploy code in batch mode. The EJB Deploy tool supports meet-in-the-middle mapping and EJB single and multiple table inheritance. However, mapping to multiple database back-end is only supported in EJB 2.0. For currently EJB 1.1 implementations, a metadata conversion tool is needed to switch from one database vendor to another. EJB 1.1 project metadata can contain only one vendor schema definition. See the Programmer's Guide for instructions on using this EJB metadata conversion tool.

Java project The Java project structure is as follows: Java project src/*.java META-INF/ MANIFEST.MF .imported_classes.jar .imported_sources.jar .classpath .project

Chapter 7. Development environment and build cycle

197

Utility JARs in the enterprise application are packaged as binary Java projects in the workspace. Because binary projects only exist in the workspace for reference during compilation and build, using binary projects can optimize your WebSphere Commerce Studio development environment. The following rules define a binary project:
Java build path has no source container
Project has exactly one JAR in the project, on the build path, and exported.

Server project A server project stores information about test and deployment servers and their configurations. The application testing and publishing tools feature of WebSphere Studio uses servers and configurations to test your projects. Servers identify where you can test your projects. Server configurations contain setup information. A server project has the following directory structure:
The templates folder contains the source for server templates and configuration templates. Templates contain settings that may be used as a starting point when creating new servers or new configurations.
WebSphere server configurations are created in folders that contain the settings for each particular server configuration.

7.1.2 WebSphere Commerce Studio plug-ins In addition to the WebSphere Commerce workspace that is provided, WebSphere Commerce Studio provides additional tools and plug-ins. The following plug-ins are provided:
WebSphere Commerce Studio Configuration Manager plug-in
WebSphere Commerce Studio online help plug-in
WebSphere Commerce API reference information plug-in

WebSphere Commerce Studio Configuration Manager plug-in The Configuration Manager plug-in that assists with managing your WebSphere Commerce (and WebSphere Commerce Payments) instances (see Figure 7-3 on page 199).

198

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Figure 7-3 WebSphere Commerce Studio Configuration Manager plug-in

WebSphere Commerce Studio online help plug-in The WebSphere Commerce Studio online help plug-in allows you to access the WebSphere Commerce online help from within WebSphere Studio Application Developer. Additionally, with this plug-in, the WebSphere Commerce context-sensitive online help can be launched by pressing F1 when WebSphere Commerce tools (for example, the Administration Console) are running (see Figure 7-4 on page 200).

Chapter 7. Development environment and build cycle

199

Figure 7-4 WebSphere Commerce Studio online help plug-in

WebSphere Commerce API reference information plug-in The WebSphere Commerce API reference information plug-in allows you to access the WebSphere Commerce API reference information from within WebSphere Studio Application Developer (see Figure 7-5 on page 201).

200

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Figure 7-5 WebSphere Commerce API reference information plug-in

7.1.3 Custom code packaging and incremental deployment After you have created customized code in WebSphere Commerce Studio and have tested it within the WebSphere Test Environment, you must deploy it to a WebSphere Commerce instance running outside of the WebSphere Test Environment. This WebSphere Commerce instance can run locally on your development machine, or it can be on another machine (using the same or a different operating system). To help alleviate some of the pain in custom code deployment, a new method of deployment, called incremental deployment, has been introduced.

Custom code packaging Before beginning the deployment topic, you need to understand how WebSphere Commerce has changed its packaging structure to implant the hooks for incremental deployment. An EJB project and a Java project for customization have been created and configured to run with the WebSphere Commerce Server. All customization code should be placed into one of these two modules, depending on the type of Java code being put in.

Chapter 7. Development environment and build cycle

201

Incremental deployment In an incremental deployment, you must already have a WebSphere Commerce enterprise application installed on the target WebSphere Commerce Server. Then in the deployment process, you only deploy those assets (commands, data beans, enterprise beans and more) to the existing enterprise application. The benefits of incremental deployment are as follows:
Fast A small migration window implies less downtime in the target server.
Reliable Since you are only adding new code to the placeholder of the WebSphere Commerce instance, less configuration increases the chances of success of each deployment.
Traceable The isolation between your assets and WebSphere Commerce allows you to keep a change history of your incremental deployment. This helps you to track down specific issues that you have encountered during deployment or runtime and therefore is more service friendly.

7.2 Team development environment overview Application development teams are becoming even more distributed, more diverse, and under more pressure to deliver solutions quickly. It is critical to have a development environment that can support these needs while also addressing personalized requirements. The team development environment for WebSphere Studio Application Developer includes pluggable repositories instead of a proprietary repository, and is able to support an optimistic concurrency team model. The move away from a proprietary repository to a file-based system offers the following improvements:
Easier integration of favorite tools since you can work directly in the file system
More flexibility in source management and team development
No duplication of data in the file system and the workbench Team developers do all of their work in their individual workbenches, isolated from others, and then periodically submit changes to a team stream. This model allows individual developers to work on a team project, share their work with others as changes are made, and access the work of other developers as the

202

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

project evolves. At any time, developers can update their workbenches by retrieving the changes that have been made to the team stream or by submitting changes to the team stream.

7.2.1 Optimistic team model An optimistic model is one where any member of the team can make changes to any resource that one has access to. Because two team members can release the stream changes to the same resource, conflicts can occur (see Figure 7-6) and must be dealt with. In WebSphere Studio Application Developer, conflicting incoming and outgoing changes are detected automatically. This model is termed optimistic because it is assumed that conflicts are rare.

Optimistic Model - Ideal Initial Development

Change #2

Developer 1 Release

Catch-up

Release

Stream Catch-up

Catch-up

Release

Developer 2 Time

Change #1

Optimistic Model - Conflict (Rare) Change #3

Developer 1 Catch-up V1.3

Release V1.4

Stream Merge V1.4 and Release V1.5

Developer 2 Change #4

Time

Figure 7-6 Optimistic team model

Chapter 7. Development environment and build cycle

203

One of the key features in the team environment of WebSphere Studio Application Developer is the synchronization process. In an optimistic team mode, conflicts are assumed to be at the lowest level. Resource owners have to follow a certain set of guidelines to make sure that this assumption holds. For instance, drastic changes such as changing resource names or removing resources should only be done at a certain time of a week and need to be coordinated. When you make changes in the workbench, resources are saved locally. Eventually you will want to release your changes to the stream so others can have access to them. Meanwhile, others may have released changes to the stream. You will want to catch up these resources in the workbench. It is preferable to catch up before releasing changes, in case there is a conflict with the resources in your workbench and the resources currently in the stream. This model supports groups of highly collaborative developers who work on a common base of files and who frequently share their changes with each other. It also supports developers who work offline for long periods, connecting to their repository only occasionally to synchronize with the stream.

7.2.2 Ideal work flow No resource is an island. Usually resources do not exist in isolation; they typically contain implicit or explicit dependencies on other resources. As resources are released to the stream, these dependencies can be affected. Ensuring the integrity of the dependencies is important because the stream represents the current project state: at any point a team member could take the stream contents as a basis for new work. The ideal workflow therefore is one in which the stream integrity is preserved. Of course, under certain conditions you may be confident that the incoming changes do not affect you and choose to release without catching up. However, in general team members should make an effort to follow a flow similar to the following in order to ensure that the stream integrity is not accidentally compromised.

Start fresh Before starting work, get caught up with the current stream state. If you are sure that you have no local work that you care about, the fastest way to get caught up is to select the projects you are interested in from the stream or code server. This will blanket overwrite your local resources with those from the stream.

Make changes Work locally in your workbench, creating new resources, modifying existing ones, saving locally as you go.

204

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Synchronize When you are ready to release your work, synchronize with the stream. There are two distinct processes involved in synchronizing resources, catch up and release. When you make changes in the workbench, resources are saved locally. Eventually you will want to release your changes to the stream so others can have access to them. Meanwhile, others may have released changes to the steam. You will want to catch up these resources in the workbench. It is preferable to catch up before releasing changes, in case there is a conflict with the resources in your workbench and the resources currently in the stream.

Conflicts Conflicts arise when you have locally modified a resource for which a more recent version is available in the stream. In this situation you can choose to do one of three things:
Catch up the resource from the stream.
Release your version of the resource to the stream.
Merge your work and the stream resource. Typically you will want to merge, because the other two options will result in loss of work.

Catch up Examine incoming changes and add them to your local workbench. This allows you to determine if there are changes that might affect the integrity of what you are about to release. Resolve conflicts, retest, and run integrity checkers to ensure your code compiles and executes properly.

Release Now that you are confident that your changes are well integrated with the latest stream contents, release your changes to the stream. To be prudent, you may need to redo the synchronize process if there are again new incoming changes.

7.2.3 Source control management Source Control Management (SCM) is the process of managing the source code for your applications. It is the method whereby you:
Securely and safely store the source for your applications
Manage changes to this source code
Promote changes to the source code through the various stages of application development

Chapter 7. Development environment and build cycle

205


Control the version, release and modification level of the source code
Manage the build/compile step of creating executable applications from the source code Typically when we think of Source Control Management, we think of the tools that provide this sort of function - the basic synchronization check in-check out library control systems that prevent the changes of one developer from overwriting the changes created by another developer. In many IT environments, SCM tooling is pervasive. If you have source code and you modify applications, it is assumed that you are using SCM tooling to manage your development process. Version control systems provide two important features required for working in a team:
A history of the work submitted by the team
A way to coordinate and integrate this work Maintaining history is important so that one can compare the current work against previous efforts or revert to older work that is better. Coordinating the work is critical so that there exists one definition of the current project state, containing the integrated work of the team. This coordination is provided through the stream model.

Concurrent Version System (CVS) Concurrent Version System (CVS) is a version control system that can be used to record the history of your source files. WebSphere Studio Application Developer is shipped with a built-in client for the Concurrent Version System. With this client you can access CVS repositories. You could of course save every version of every file you have ever created. This would, however, waste an enormous amount of disk space. CVS stores all the versions of a file in a single file in a clever way that only stores the differences between versions. CVS also helps you if you are part of a group of people working on the same project. It is all too easy to overwrite each other's changes unless you are extremely careful. Some editors try to make sure that two people never modify the same file at the same time. Unfortunately, if someone is using another editor, that safeguard will not work. CVS solves this problem by insulating the different developers from each other. Every developer works in his/her own directory, and CVS merges the work when each developer is done.

Resources Resources is a collective term for projects, packages, folders, and files that exist in the workbench. The Navigator view provides a hierarchical view of resources

206

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

and allows you to open them for editing. Other tools may display and handle these resources differently. There are three basic types of resources that exist in the workbench:
Files Comparable to files as you see them in the file system.
Folders Comparable to directories on a file system. In the workbench, folders are contained in projects or other folders. Folders can contain files and other folders.
Projects Contain folders and files. Projects are used for builds, version management, sharing, and resource organization. Like folders, projects map to directories in the file system.

Branches In CVS, teams share and integrate their ongoing work in branches. Think of a branch as a shared work area that can be updated at any time by team members. In this way, individuals can work on a team project, share their work with others on the team, and access the work of others during all stages of the project. The branch effectively represents the current shared state of the project. Resources can be changed in the workbench without affecting the branch. Individuals must explicitly provide their changed resources to the branch.

Versions Resources are versioned in order to capture a snapshot of the current state of the resources at one specific point in time. Resources in CVS are versioned by tagging them with a version label. When a resource is versioned, it means that a non-modifiable copy of it can be retrieved from the repository.

Updating While you are working on a project in the workbench, other members of your team may be committing changes to the copy of the project in the repository. To get these changes, you may update your workbench to match the state of the branch. The changes you will see will be specific to the branch that your workbench project is configured to share. You control when you choose to update.

Chapter 7. Development environment and build cycle

207

Committing You can commit workbench resources that you have modified to the repository so that other team members can see your work. Only those changes committed on that branch will be visible to others working on that branch.

Resolving conflicts When updating or committing you may encounter conflicts. A conflict occurs when you have locally modified a resource for which a more recent revision is available in the branch in the repository. Specifically, the branch will contain a revision newer than the base revision of your resource. In this situation, you can choose to do one of the following:
You can take the change from the branch, discarding your local work. This could occur if you have made unintended changes locally, or if you realize that the revision in the repository is better than yours. Overwriting your local changes should be done with caution since you are in essence throwing work out.
You can commit your change, including the revision in the repository. This should be done with great caution since you are in essence throwing away someone else's work. In particular, the change you are overwriting may have other dependencies in the branch (for example there may be other incoming changes which depend on the conflict).
You can merge your work and the repository resource, saving the merged resource locally. You may then later choose to commit this merged result. Typically, you will want to take the third option, that is to merge, because of the loss of work issues with the other two choices.

7.2.4 Defect tracking Untracked defects can get lost for a while and then come out to bite you. Nobody likes bad surprises so it is wise to keep everyone informed. Tracked defects are a great measure of quality; it helps to manage resources by focusing on the most important problems. Defect tracking is a process to record and track problems that are found in software development, to ensure that problems get fixed. It is an important part of the overall software quality practices and it aids in measuring quality and minimizing number and cost of defects. The point of creating a defect report is to get defects fixed. There are mainly eight components in an effective defect tracking system: 1. Defect repository

208

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

2. 3. 4. 5. 6. 7. 8.

Defects described Defects prioritized Structured resolution (tracking status) Communications Continuous defect resolution Defect evaluation and analysis Defect reporting

The following are fields that your tracking database should contain:
Identifier or unique number
Short description
Date and time stamp
Severity
Priority
Classification
Status/state of the defect - open, working, closed, returned, or cancelled
Originator name and department of person recording the defect
Detailed description of the problem, how the test was conducted, and how to reproduce the problem
History of defect life cycle

7.3 Build environment overview If you want to create a simple computer program consisting of only one file, you merely need to compile and link that one file. On a typical team project involving dozens, hundreds, or even thousands of files, however, the process of creating an executable program becomes more complicated and time consuming. You must build the program from its various components. A common practice is the daily build and smoke test process. Every file is compiled, linked, and combined into an executable program every day, and the program is then put through a smoke test, a relatively simple check to see whether the product smokes when it runs.

7.3.1 Benefits of daily build and smoke tests There are many benefits of daily build and smoke tests:
Minimize integration risk

Chapter 7. Development environment and build cycle

209

One of the greatest risks that a team project faces when the different team members combine or integrate the code they have been working on separately is that the resulting composite code does not work well. Depending on how late in the project the incompatibility is discovered, debugging might take longer than it would have if integration had occurred earlier. Program interfaces might have to be changed, or major parts of the system might have to be redesigned and re-implemented. In extreme cases, integration errors have caused projects to be cancelled. A daily build and smoke test process keeps integration errors small and manageable, and it prevents runaway integration problems.
Reduce the risk of low quality Related to the risk of unsuccessful or problematic integration is the risk of low quality. By minimally smoke testing all the code daily, quality problems are prevented from taking control of the project. You bring the system to a known, good state, and then you keep it there. You simply don't allow it to deteriorate to the point where time-consuming quality problems can occur.
Support for easier defect diagnosis When the product is built and tested every day, it's easy to pinpoint why the product is broken on any given day. If the product worked on Day 17 and is broken on Day 18, something that happened between the two builds broke the product.
Improve morale Seeing a product work provides an incredible boost to morale. It almost doesn't matter what the product does. Developers can be excited just to see it display a rectangle! With daily builds, a bit more of the product works every day, and that keeps morale high.

7.3.2 Concepts of daily build and smoke tests The idea behind this process is simply to build the product and test it every day. The following is a list of key concepts of this idea:
Build daily The most fundamental part of the daily build is the daily part. Treat the daily build as the heartbeat of the project. If there's no heartbeat, the project is dead. Different developers' code can be allowed to get a little out of sync between these pulses, but every time there is a sync pulse, the code has to come back into alignment. When you insist on keeping the pulses close together, you prevent developers from getting out of sync entirely. Some organizations build every week, rather than every day. The problem with this is that if the build is broken one week, you might go for several weeks

210

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

before the next good build. When that happens, you lose virtually all of the benefit of frequent builds.
Smoke test daily The smoke test should exercise the entire system from end to end. It does not have to be exhaustive, but it should be capable of exposing major problems. The smoke test should be thorough enough that if the build passes, you can assume that it is stable enough to be tested more thoroughly. The daily build has little value without the smoke test. The smoke test is the sentry that guards against deteriorating product quality and creeping integration problems. Without it, the daily build becomes just a time-wasting exercise in ensuring that you have a clean compile every day.
Establish a build group On most projects, tending the daily build and keeping the smoke test up to date becomes a big enough task to be an explicit part of someone's job.
Check for broken builds For the daily build process to work, the software that is built has to work. If the software is not usable, the build is considered to be broken and fixing it becomes top priority. Each project sets its own standard for what constitutes breaking the build. The standard needs to set a quality level that is strict enough to keep show-stopper defects out but lenient enough to disregard trivial defects. Undue attention could paralyze progress. Here is a list of minimum criteria of a good build:
Good builds should compile all files, libraries, and other components successfully.
Good builds should not contain any show-stopper bugs that prevent the program from being launched or that make it hazardous to operate.
Good builds should pass the smoke test.
Create a penalty for breaking the build. Most groups that use daily builds create a penalty for breaking the build. Make it clear from the beginning that keeping the build healthy is the project's top priority. A broken build should be the exception, not the rule. Insist that developers who have broken the build stop all other work until they have fixed it. If the build is broken too often, it is hard to take seriously the job of not breaking the build.

Chapter 7. Development environment and build cycle

211

7.3.3 Build automation for daily builds and smoke tests If there is to be engineering in construction, the process must be consistent and repeatable. Without consistency, it is hard, if not impossible, to know how to build, test, or ship someone else's software. Without repeatability, it is hard to guarantee the results of a build or a test. The simple answer is discipline. The process of constructing software must be disciplined if it is to succeed. But people do not seem to come that way; in general, people find discipline hard to take, and even harder to maintain. Fortunately, there is a pragmatic solution: automate everything you can, so that the development environment itself provides the kind of disciplined repeatability and consistency needed to make the process run smoothly and reliably. This approach leaves developers free to work on the more creative side of software construction, which makes the programmers happier. At the same time, it makes the accountants happier by creating a development organization that is more efficient and less prone to costly human-induced errors and omissions. If you do nothing else, make sure that every developer on a project compiles their software the same way, using the same tools, and against the same set of dependencies. Make sure this compilation process is automated. This may seem obvious, but it is surprising how often it is ignored. We know teams where some developers compile using the automatic dependencies calculated by their IDE, others use a second IDE, and still others use command-line build tools. The result will be hours wasted every week tracking down problems that are not really problems, as each developer tests against subtly different executables generated by their own personal compilation system. Most automated build processes are performed on the computers of the build engineer or one of the developers. This approach is inherently flawed due to the lack of control over this environment. Here are some common problems that can occur with this approach:
A virus on the build machine could be inadvertently included in a software build.
Installation of new software or software updates on the build machine could change resources that are included in the software build.
Uncontrolled access to the build machine could result in unauthorized changes to the software build, including potential malicious changes that could be difficult to detect. While an automated build process is an important step towards higher quality software, the only way to achieve complete control over the build quality is for the software to be built in a clean build environment.

212

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

We have barely scratched the surface of automation. Automation does not need to be restricted to the build, or even to just development. Perhaps your project has strict reporting requirements, review and approval processes, or other onerous secretarial chores. Where possible, try to automate these repetitive tasks as well. There is more to constructing software than just constructing software, and we can leverage automation throughout the process.

7.4 Deployment overview The complete application development life cycle includes many different processes, such as the actual coding of the solution, the management of source control in a team development environment, the build process, the test process, the final packaging and staging, the deployment process, and often the upgrade of applications after they are installed in the production environment. A successful deployment relies on more than development of the application and the final packaging process. For example, solutions of any substantial complexity need to be tested in a controlled environment, and the deployment process often benefits from the use of staging servers. You need to manage the deployment of your solutions between these environments, as well as to the final production environment. The following sections briefly describe the characteristics of each environment, and explain how to use them to ensure a successful deployment of your solution.

7.4.1 Development environment A successful deployment relies on more than development of the application and the final packaging process. For example, solutions of any substantial complexity need to be tested in a controlled environment, and the deployment process often benefits from the use of staging servers. You need to manage the deployment of your solutions between these environments, as well as to the final production environment. The following list briefly describes the characteristics of each environment, and explains how to use them to ensure a successful deployment of your solution:
Software dependencies Dependencies required by your solution are present on the developer computers, but they may not be included or installed successfully in other environments. Some of these dependencies are present on your development computers simply because they are provided by the development tools, so you need to be aware of exactly what needs to be deployed to ensure successful installation into other environments.

Chapter 7. Development environment and build cycle

213


Repeatable deployment in different environments Application resources are created on developer workstations and servers, but they might not be successfully recreated or configured as part of the deployment to other environments. You need to thoroughly understand your application's architecture and any external resources that it uses if you are to deploy your solution successfully.
Application configuration updates Applications are configured to use resources while they are being developed. When they are deployed to another environment, these configuration settings need to be updated so that they use the resources appropriate for that particular environment. Because many of these settings are stored in configuration files within the new framework, you need to manage the process of updating or replacing these configuration files as you deploy your solution from one environment to another.

7.4.2 Test environment This environment should be used to test the actual deployment process. You (or your test team) need to verify that application files and resources are installed to the correct locations, and that all configuration requirements are met before testing the solution's functionality. After you are satisfied that the application installs correctly, you (or your test team) can then perform tests that verify the solution functions as expected. To be certain that your tests have meaningful implications for how your solution will install and function in the live production environment, you should ensure that test computers resemble your production computers as closely as possible. They should not have the development tools installed that you used to produce the solution because that could mask potential problems that will only become apparent when you roll out your solution to the end users.

7.4.3 Staging environment This environment should be used to house your solution after it has been fully tested in the test environment. It provides a convenient location from which to deploy to the final production environment. Because the staging environment is often used to perform final tests and checks on application functionality, it should resemble the production environment as closely as possible. For example, the staging environment should not only have the same operating systems and applications installed as the production computers, but it should also have a similar network topology (which your testing environment might not have). Usually, the staging network mimics the production environment in all respects

214

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

except that it is a scaled-down version (for example, it may have fewer cluster members or fewer processors than your server computers).

7.4.4 Production environment This is the live environment where your solutions are put to work to provide benefits and functionality for the enterprise that uses them. This environment is undoubtedly the most complex, usually with many installed productivity, line-of-business and decision support systems used by different users in the organization. Consequently, it is the most difficult to manage and control; therefore, teams of administrators and information technology professionals are employed to ensure that users can take advantage of your applications along with solutions from other vendors.

7.4.5 Practice deployment and create backup plan Some of the biggest problems during the life cycle of a distributed application occur when your solution is rolled out to the production environment. The lack of rehearsal and planning for this event often leads to all of the involved parties attempting to breathe air into a lifeless application that does not work in the environment for which it was designed. Before going live, you need to rehearse the deployment in a clean environment with all of the participants present. You should take this opportunity to work out the little problems in a controlled environment without the added pressure of impacting production users. You can avoid the turmoil and embarrassment of a failed deployment by planning and documenting the production installation process and the contingency plans. You should create an environment on a clean system. It should not know about your application and test deployment. Starting from a well-known configuration, begin to clearly document every step involved in the installation of the distributed application. Note the location of the application files and the installation points. Pretend that you and your developers will not be there to troubleshoot during this process. Ensure that you have included small test scenarios that the installers can use as checkpoints to verify that the installation is going well. Lastly, document how to uninstall your application.

7.4.6 Production debug vs development debugging Every developer or support engineer debugs applications at some stage of their career, yet debugging is often viewed as an arcane and difficult topic. While it is often difficult to determine why an application is hanging, leaking memory, or crashing, there are techniques you can apply to make the debugging process more productive and efficient.

Chapter 7. Development environment and build cycle

215

The primary goal of debugging a system is to isolate and determine the root cause of a performance, configuration, or abnormal error condition that impedes normal system operation. Generally speaking, this goal holds true whether you are debugging in a development environment or in a production environment. However, there are crucial differences between the two environments. When debugging in a production environment, determining the root cause may be less important than simply getting the system into an operational state. Time constraints and business cases also differ between development and production environments. Debugging within a production environment is usually done within much tighter time constraints, given that the end user or customer may be losing revenue as a consequence of a non-operational system. In a production environment, the system experiences live operational loads and timing situations, which may be difficult or impossible to reproduce in a development environment. In addition, scenarios can arise that have not been anticipated during system design. Timing-sensitive or load-sensitive scenarios that lead to abnormal behavior can be difficult to reproduce or debug successfully, even during live operation in a production environment. Because physical access to a production system is often restricted, offline or remote-access techniques are required. In a development environment, you usually have access to an integrated development environment (IDE), source code, and debug versions of libraries and symbols. In a production environment, the IDE and source code are often not present, and you may only have access to release versions of libraries and symbols. Note that release versions of symbols are an invaluable resource, but are often not built during a normal product development life cycle. In a development environment, you often have the luxury of using a full range of techniques to debug the system. That is not the case in a production environment, where it is essential to keep the system functioning while performing debugging. A production environment requires the following low-risk actions:
Using non-intrusive debugging techniques, such as capturing performance information, and saving hang or crash dumps.
Restricting the use of code changes, except in the case of critical problems. This means that you can't normally experiment using code modification to isolate root causes in production environments.
Adjusting the testing level to the user's comfort level. This may mean passing a system through a full battery of tests in a development environment, or simply ascertaining if the system is still running.

216

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Debugging a problem typically involves two phases. The initial discovery phase is used to gather information about the problem. This leads to a debugging phase, when you attempt to determine the cause of the problem.
Discovery phase Most developers are familiar with the debugging phase, yet the discovery phase is equally important to production-level debugging. The goal is usually to capture the state of the server and then allow the server to continue functioning.
Debug phase The debug phase may involve live or post-mortem debugging. Live debugging involves stepping through the code as it executes and looking for bugs or defects. Post-mortem debugging involves the analysis of data or program dumps produced by tools. One advantage of post-mortem debugging is that it uses data gathered from a real problem occurrence, instead of relying on a dedicated programmer to interactively step through the code and try to reproduce the problem. Choosing the right debugger depends on the environment and whether you're dealing with native or managed code.

Chapter 7. Development environment and build cycle

217

218

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

8

Chapter 8.

Globalization guidelines This chapter provides in-depth coverage of the globalization capabilities in WebSphere Commerce, and highlights the tools and techniques necessary to create global e-commerce sites. The chapter includes the following topics:










Introduction to globalization Globalization in WebSphere Commerce Cultural considerations WebSphere Commerce application model Globalized catalog content Globalized store design Globalized tools framework Globalization in the messaging system Globalization tips

© Copyright IBM Corp. 2003. All rights reserved.

219

8.1 Introduction to globalization This section provides an introduction to what globalization is and why it is important to businesses that need to operate in a global environment.

What is globalization Globalization (G11N) is the proper design and execution of systems, software, services, and procedures so that one instance of software, executing on a single server or end-user machine, can process multilingual data and present data culturally correctly in a multicultural environment such as the Internet. At its core, globalization can be defined as follows: Globalization = Internationalization + Localization + Multilingual Support
Internationalization (I18N) The process of producing a product (design and code) that is totally free of any dependency on the language, script, culture, and coded character set. Strictly speaking, an internationalized product is not usable in any region of the world unless it is localized to that specific region.
Localization (L10N) The process of adapting an internationalized product to a specific language, script, cultural, and coded character set environment. In localization, the same semantics are preserved while the syntax may be changed.
Multilingual support The process of supporting multiple languages, either concurrently or one language at any given time. A multilingual program strives to handle data in a way that is not dependent on a particular language or writing system. Multilingual documents combine text that is written in different languages. Multilingual may refer to many languages that all use the same script, (such as English, French, and German), or to many languages that use distinct scripts (such as German, Hebrew, and Korean). The latter case is also referred to as multiscript. Note: G11N or g11n is a commonly used abbreviation for globalization in the field of software development. The word starts with G and ends with N with 11 letters in between. It reads G eleven N. Similarly, I18N and L10N are abbreviations for internationalization and localization respectively.

Why globalization is important With the overwhelming acceptance and popularity of the Internet and its accompanying technologies, traditional business constraints, such as distance,

220

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

have disappeared. Companies and individuals can now do business with each other from almost any part of the world. With the help of the Internet, separate marketplaces are now being transformed into a single global marketplace. It is important that companies that want and need to operate globally create e-business software that meets new challenges, such as the following:
Working with global information Data displayed to customers must meet customer expectations for content and language. This implies that data from different languages must be stored, retrieved, and manipulated without loss of meaning.
Anticipating cultural norms It is important to provide information in the correct format to customers. Sellers that fail to address cultural norms run the risk of offending customers and losing sales.
Applying logic to worldwide business issues Business issues such as the use of various currencies and taxation rules need to be addressed.
Establishing and maintaining a cost-effective operation Deploying an e-commerce Web site for every region, may avoid some problems, but is prohibitively difficult to implement and maintain. A vast number of issues must be addressed when you enable software products for a global customer base. It is certainly not a simple matter of translation or format. Globalization is, therefore, necessary whether the product is translated or not. To take full advantage of the available opportunities that a single global marketplace has created, companies must tailor their e-commerce sites to their new consumers in a wide range of regions. This means that developers of e-commerce sites must consider language, cultural differences, divergent business practices, and data storage methods so that the e-commerce site has the greatest possibility to maximize its potential.

8.2 Globalization in WebSphere Commerce The WebSphere Commerce product architecture has been designed with globalization in mind. Globalization permeates all components within WebSphere Commerce, as every level within an e-commerce application model is affected by globalization. Beneath translation and simple formatting, globalization touches much deeper levels of the user experience.

Chapter 8. Globalization guidelines

221

Before describing the rich set of globalization-capable features in WebSphere Commerce, it is worthwhile to list some of the common challenges that impede the development and deployment of a globalized e-commerce Web site:
Storing data from different languages in a single database. For example, how do you store Korean, Japanese and German data in a single database?
The availability of a single set of integrated cultural formatting functions.
Lack of tooling to manage data in different languages and problems with organizing different national language data in a single database.
Maintenance of multilingual assets (HTML, GIF, JSP, etc).
Globalizing business logic. For example, taxation and shipping rules, marketing campaigns, etc.
Cultural customization for page look and feel. Recognizing the challenges, WebSphere Commerce needed to provide out-of-the-box globalization capabilities that include cultural norms, data, business logic, and maintenance.

Data An immediate advantage provided by WebSphere Commerce at the most basic stage of globalization is that data is stored in Unicode, thus enabling developers to store, retrieve, and display data from different languages simultaneously on the Web site. Also, language-sensitive data is fully separated from nonsensitive common data within the database design.

Cultural norms Leveraging the inherent globalization functionality of Java technology, WebSphere Commerce provides a suite of functions to accommodate cultural differences. The WebSphere Commerce Server software is fully enabled for multiple cultures so that sellers can ensure data is retrieved and presented in the cultural contexts anticipated by their customers. Also, the recommended JavaServer Pages (JSP) model of using culturally neutral master JSP templates provides tremendous advantages to customization and maintenance. The custom currency formatting capabilities provided by WebSphere Commerce currency manager allow sellers to customize formatting on a per-currency, per-store, per-country basis and/or display more than one currency simultaneously.

222

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Business logic WebSphere Commerce provides its customers with many of the tools needed to set up and easily deploy a global online business, by supporting a set of business logic features. Taxation and shipping editors available from the WebSphere Commerce Accelerator allow sellers to define proper tax and shipping calculation rules based on a customer’s physical location. Other tools include wizards to create and maintain global fulfillment centers to model real-life fulfillment systems, and product management tools that help to rapidly set up store catalogs for global store fronts.

Maintenance With the use of Unicode, WebSphere Commerce removes the traditional data management restrictions that in the past prevented the combination of data from different languages from being stored in a single database. Also, WebSphere Commerce provides a complete set of culturally neutral database management and content management tools to properly manage multilingual data. Those tools eliminate the need to procure separate tools for different geographies. Figure 8-1 on page 224 displays a summary of the features, functions, and benefits provided by WebSphere Commerce.

Chapter 8. Globalization guidelines

223

Maintenance

Database population and management tools Content management tools Seller-level tools JSP templates and store models

Easy maintenance of multilingual database data, static HTML or store information Reduced JSP maintenance Rapid site development for new languages

Business logic

Taxation wizard Shipping wizard Fulfillment Centers Campaigns and discounts

Realistic taxation and shipping charges based on customer jurisdiction Accurate modeling of real-life fulfillment systems Multilingual marketing initiatives

Cultural norms

Multiculturally enabled commands, beans and rules templates Inherited functions provided by Java components for data formatting Currency formatting functions Language and currency selected independently Single JSP design model

Automatic multilingual data manipulation and retrieval Automatic data formatting Dual currency display and customized currency formatting Easy language and cultural customizations for page look and feel

Data

Unicode database (UTF-8) Language and cultural data separation within database design Automatic code page conversion for multilingual data entry, storage and retrieval

Ability to store and manage data in different languages in a single database (Korean, German, Chinese) Database design for easy storage of multicultural data Accurate management of multilingual data to ensure no corruption

Most Difficult

Least Difficult

Figure 8-1 Globalization features in WebSphere Commerce

8.3 Cultural considerations In software development, cultural formatting refers to the selectibility of culturally sensitive information such as a country's numeric format, monetary format, date and time formats, and calendar format. Such information varies from one region to another, and thus the software application cannot mandate any cultural formats.

224

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

We discuss the following cultural considerations in this section:
Date and time formatting
Currency and number formatting
Name and address formatting Both the WebSphere Commerce Server runtime infrastructure and tools framework provide an extensible and customizable set of globalized user interface (UI) functions that allows programmers to quickly implement a full-featured UI with a culturally sensitive look and feel. By using existing elements, a programmer's efforts are greatly reduced. In the following two subsections we describe some of those elements.

8.3.1 Date and time formatting This section includes date and time formatting information.

Date format The date format presents the day, month, and year of a particular calendar system. Even when one specific calendar system is considered, there is no single world wide standard for the presentation of date information. Table 8-1 lists the date formats of the locales of the 10 languages to which WebSphere Commerce is translated. Note: The Gregorian calendar is very common and used throughout the world, but there are other calendar systems used widely in some parts of the world, such as the Hijri and Thai calendars. Table 8-1 Sample date formats Locale

Common Format

Long Format

Short Format

United States English

04/10/98

April 10, 1998

04/10/98

Brazilian Portuguese

10/04/1998

10 de Abril de 1998

10/04/98

Simplified Chinese

1998Year4Month10Day

1998Year4Month10Day

98-4-10

French

10/04/1998

10 avril 1998

10/04/98

German

10.4.1998

10. April 1998

10.04.98

Italian

10/04/1998

10 aprile 1998

10/04/98

Japanese

1998year 4month 10day

1998year 4month 10day

1998year 4month 10day

Chapter 8. Globalization guidelines

225

Locale

Common Format

Long Format

Short Format

Korean

1998/04/10

1998year 4month 10day

98/04/10

Spanish

10/04/1998

10 de abril de 1998

10/04/98

Traditional Chinese

1998Year4Month10Day

1998Year4Month10Day

98.4.10

Note: The underlined text in Table 8-1 is in the native language. For example, 1998year 4month 10day implies that year, month, and day are in the native language and not English. Table 8-2 lists the elements of the date format that make the date format unique in different regions of the world. Table 8-2 Date format elements used for presentation Element

Description

Date delimeter

Delimiters in date representation differ around the world. The following are some examples of delimiters used in dates
Space
Hyphen
Forward slash
Period (full stop)

Order of date components

The order of the day, month, and year differs around the world.

Day format

A zero may fill in the day if it is a single-digit day.

Month format

The month may be numeric, abbreviated, or fully spelled out.

Year format

The year format may have 2 digits or 4 digits.

In WebSphere Commerce, either the long format or short format is usually used. Using the WebSphere Commerce Tools Framework Calendar UI element, developers can display a calendar to the user and allow them to graphically or manually enter a date. This date is then returned to the calling window and placed in the correct field. The user's input is presented in text boxes. Because those text boxes have labels attached to them, there is no ambiguity in identifying which numbers are the year, month, and day respectively. Thus, cultural formatting is not required. Figure 8-2 on page 227 displays an example of an embedded calendar in WebSphere Commerce.

226

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Figure 8-2 Example of an embedded calendar in WebSphere Commerce

Time format The formats used for time differ around the world. Even though a software product may manipulate time information using a Timestamp, it should display time information to, and accept time information from, the user in the correct cultural context. Table 8-3 lists the time formats for the locales of the 10 languages to which the WebSphere Commerce product is translated. Table 8-3 Time formats Locale

Common format

Full format

Short format

United States English

2:45:16 PM

2:45:16 PM EST

2:45 PM

Brazilian Portuguese

14:45:16

14:45:16

14:45

Simplified Chinese

14:45:16

14hour45min16sec

14:45

French

14:45:16

14:45:16

14:45

German

14:45:16

14:45:16

14:45

Italian

14:45:16

14:45:16

14:45

Japanese

pm2hour45min16sec

pm2hour45min16sec

pm2hour45min16sec

Korean

2:45:16 PM or PM 2:45:16

2:45:16 PM KST or PM 2:45:16 KST

2:45 PM or PM 2:45

Spanish

14:45:16

14:45:16

14:45

Traditional Chinese

PM 2:45:16

pm2hour45min16sec

2:45 PM

Table 8-2 on page 226 lists the elements of the time format that make the time format unique in different regions of the world.

Chapter 8. Globalization guidelines

227

Table 8-4 Time format elements used for presentation Element

Description

Delimiters

Colon or period (full stop)

Format

Some countries display the leading zero in hours.

24-hour clock

Some countries use the 24-hour clock, while others such as the USA use the 12-hour clock with indicators AM/PM.

Note: The order of hours, minutes, and seconds does not change; the order is HH MM SS (with the appropriate delimiters). In the WebSphere Commerce Tools Framework, the functions used to validate dates are included in the web/JavaScript/tools/common/DateUtil.js JavaScript file. This file should be included in your JSPs. Always give the user the option to launch a calendar UI element. In case they enter the date manually, use the validDate (date) inside the DateUtil.js JavaScript file. The validTime() function is in Util.js. In WebSphere Commerce, the TimestampHelper class provides time and date formatting functions that are required by WebSphere Commerce tools and store development. The TimestampHelper() class is available in both com.ibm.commerce.utils (for tools framework) and com.ibm.commerce.ejb.helpers (for server runtime) packages to help perform the conversions described in Table 8-5. Table 8-5 Sample fconversions From

To

Timestamp

Date in yyyy-mm-dd

Timestamp

Time in hh:mm

Date and time

Timestamp

For example, TimestampHelper.getDateFromTimestamp(Timestamp t,Locale locale) will extract the date portion from the timestamp. The date will be returned in a locale-specific manner. Most of the WebSphere Commerce databeans are enabled to implicitly use the date/time formatting functionality of the TimestampHelper. One such data bean is described in Example 8-1 on page 229.

228

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Example 8-1 WebSphere Commerce DataBeans and usage of TimstampHelper

... ... ... ...

... ... ... // Get locale for formatting the date appropriately Locale jLocale = cmdcontext.getLocale(); // get the estimated ship date. Timestamp latestOrderAvailDate = orderBean.getFormattedEstimatedShipDate(); ....... .......

In the above example, the culturally formatted estimated ship date is retrieved by calling: Timestamp latestOrderAvailDate = orderBean.getFormattedEstimatedShipDate();

The above call is equivalent to: Timestamp latestOrderAvailDate = orderBean.getEstimatedShipDate(); String latestAvailableDate = TimestampHelper.getDateFromTimestamp(latestOrderAvailDate, jLocale);

8.3.2 Currency and number formatting The display of monetary amounts is often different from one country to another. Monetary values are usually accompanied by a currency symbol, which can exist in either the local currency symbols (for example,. $, , R$), or ISO 4217 international currency codes (for example, USD, EUR, BRL). Currency symbols may be placed before, within, or after the radix character of the monetary amount, and there may or may not be a space between the symbol and the

Chapter 8. Globalization guidelines

229

amount. Although, most countries use the comma or period as the decimal separator in currency, some countries, such as Japan, do not have a currency decimal separator. The rules for formatting numeric fields are not necessarily the same as the rules for formatting monetary amounts. Cultural formatting of numeric fields differs by country, since different countries use different positive and negative numeric representations for the same amount. The following list shows several ways to display the same numeric values:
1,234.56 .123
1,234,560,123
1.234,56 Negative number representation does not have a universal form. Some countries use a leading hyphen to denote negative non-monetary numbers. Some place the hyphen after the number, and some use another symbol altogether. The following list shows several ways to display the number negative fifteen:







¯15 -15 15(15) [15]

Note: Both the radix character and the commonly used term decimal separator have the same meaning. The radix character is more accurate since many countries do not use the dot symbol as the decimal separator.

There is much evidence that language and currency are orthogonal (not in sync) concepts. Canada is a prime example where there is a single currency, Canadian dollar, but two official languages, English and French. It is complex for businesses to operate in multiple currencies. Adding a language element increases this complexity and makes pricing and other currency-related tasks almost unmanageable in the WebSphere Commerce administration tools such as the Accelerator. A single default currency, which may be used as the basis for conversions or explicit pricing in other currencies, makes these operational tasks clearer and better matches business practices. Linking a store's default currency to its default language has no valid business relationship and thus it is not a valid currency defaulting method. For example, if you change the language it should not have to mean that you want the currency

230

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

changed. For this reason, the selection of language and currency are two separate tasks in WebSphere Commerce V5.5, as depicted in Figure 8-3.

Figure 8-3 Orthogonal concept of currency and language selection in FashionFlow store model

There is no way to define a one-to-one or one-to-many relationship between language and currency. Any given currency may be related to many languages (for example, Canadian dollar is related to both French and English), and any given language can be related to many currencies (for example, English is related to the US dollar, Canadian dollar, British Pound, etc.). In WebSphere Commerce, the shopping currency is the currency in which the shopper sees all prices. To determine the shopping currency of a shopper, the

Chapter 8. Globalization guidelines

231

following algorithm is performed by the currency engine named the Currency Manager:
If the shopper's preferred_currency is specified and supported by the store, then shopping_currency = preferred_currency.
If the shopper's preferred_currency is specified (and not supported) and it is the counter value for another_supported_currency, then shopping_currency = another_supported_currency.
If ( shopping_currency == null) then shopping_currency = store's default currency (from STOREENT table - column SETCCURR which is nullable) is not language dependent.
If( shopping_currency == null) then shopping_currency = default currency for the language (The SETCURR column of the STORELANG table) is language dependent. There are a few important points to highlight about the above algorithm performed by the Currency Manager:
The use of the SETCCURR column of the STORELANG table is strongly discouraged, since it may be deprecated in a future release; the column is therefore backwardly compatibility only. Your store models should not set the SETCCURR column of the STORELANG table (set it to null).
Migration from WebSphere Commerce Suite V5.1 to WebSphere Commerce V5.5, Business Edition will be accomplished by not setting the store's default currency in the STOREENT table (this will ensure the last step in the above algorithm is executed as in WebSphere Commerce Suite V5.1). Migrated stores can easily achieve the new behavior by setting the store default via the STOREENT table. The STORELANG table does not have to be changed. This allows some migrated stores to get the new behavior and some other migrated stores to keep the old behavior if they so desire.
Either the SETCCURR column of the store object or the storeGroup object should be set via the STOREENT table. For migrated stores, this will not be the case initially. Any new stores should set the store/storeGroup default currency. Setting the store default currency will ensure that the last step of the algorithm above will not be executed. Currency formatting in WebSphere Commerce is dependent upon two items: the currency (ISO three-letter code) and the language ID, which we describe in a later section. Only by knowing both of these items can a currency be validated or formatted. Number formatting is dependent only upon the language ID. The Currency Manager makes all of the formatting information for numbers and currency values available in the WebSphere Commerce instance database. When the WebSphere Commerce instance application server is started, this

232

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

information is turned into JavaScript and becomes available for use as part of the WebSphere Commerce Tools Framework. These JavaScript functions are available by importing the web/tools/common/NumberFormat.jsp into your JSP. The functions perform the following tasks:







Validate a currency value Convert from currency value to numeric Convert from numeric to currency value Validate a number value Convert from number value to a numeric value Convert from a numeric value to a number value Note: You need to Include the Util.js file in your JSP when you include NumberFormat.jsp.

Table 8-6 lists some of the key JavaScript currency and formatting functions. Table 8-6 Currency and number formatting JavaScript functions Task

Integer

Number

Currency

Validate User Input (anything)

isValidInteger()

isValidNumber()

isValidCurrency()

Save (convert to JavaScript number)

strToNumber()

strToNumber()

currencyToNumber()

Display (format a JavaScript number for a given language)

numberToStr()

numberToStr()

numberToCurrency()

Note: If you are using the notebook, wizard, or dialog UI elements, the NumberFormat is already included in the parent frame. Example 8-2 shows a typical JavaScript currency entry form in a tools JSP. Example 8-2 Sample JavaScript currency entry found in tools JSP // requirement :: provide a user input currency entry ... //prefilling it with the previous value ... function initializeState() { document.myForm.myInput.value = parent.numberToCurrency(currAmount, fCurr, ""); } function validatePanelData() { if ( !parent.isValidCurrency(document.myForm.myInput.value), fCurr, "")) { alert("not valid"); return false; } return true;

Chapter 8. Globalization guidelines

233

} function savePanelData() { MyCurr=parent.currencyToNumber(document.myForm.myInput.Value, fCurr, ""); parent.put("myCurrLbl",myCurr); }

A sample validation and format page is available in \commerce\web\tools\sample\, and can be executed by launching http://hostname/commerce/tools/sample/validationTest.jsp. Important: We highly recommend that you avoid using FormatNumber, FormatCurrency, and FormatInteger. Those functions are included in the WebSphere Commerce Tools Framework only for backward compatibility. FormatNumber and FormatCurrency do the validation first based on the language ID. If you get a primitive numeric format (1000.23) from the WebSphere Commerce Server, those functions return a Not a Number (NaN) value. Furthermore, FormatInteger only accepts primitive numeric integers. Therefore, if you have an integer such as 1,000 in the US English language ID, it returns a NaN.

8.3.3 Name and address formatting Globalizing Web-based software applications mandates support for country-specific name and address formats. Different countries and shipping regions have different address and name formats. This implies the need for different input fields during registration and also a different order when the address is displayed. Address and name formatting is country-specific rather than a language-specific item. For example, both French and English-speaking people in Canada use the same Canadian address format. In most object-oriented programming languages, cultural information such as date/time format, currency format, number format, collation rules, and text boundary rules, can be obtained from locale-sensitive classes. The locale-sensitive classes are smart classes that magically change the behavior to best meet current language and country environment (change the behavior based on the locale). Address and name formatting is much more complicated than other cultural formatting and does not have any locale-sensitive classes that software developers can use while globalizing (localizing) their software application (for example, address forms, address information, etc.). Therefore,

234

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

software developers are responsible for implementing their own address and name formatting scheme. Address and name formats can be accepted and stored in the WebSphere Commerce instance database in multiple formats and languages. Figure 8-4 displays an example of an address form, formatted differently for two different countries, Canada and the People’s Republic of China.

Figure 8-4 Address format example

Store pages and registration samples Address and name formatting in the store pages and the user registration samples is accomplished through the use of two separate properties files: one non-translatable local specific file, and a second properties file containing translatable text. The non-translatable locale-specific file is used to store the following address/name format control information:
Image files: The location of culturally sensitive image files.
Required fields: Different fields are required or optional for different cultures.
Displayed fields: Different fields are hidden or displayed for different cultures. Cultural differences that affect the order in which fields should be displayed are not demonstrated. Examples of the non-translatable locale-specific address format properties files are:
\runtime\properties\UserRegistration_xx_XX.properties
\runtime\properties\UserRegistrationB2B_xx_XX.properties

Chapter 8. Globalization guidelines

235

Where xx_XX represents a locale. Those properties hold the address format control information used by the UserRegistration sample shipped with WebSphere Commerce. The translatable properties file stores the following translatable elements:
Page titles: The title of the page is translated into each language.
Labels: Form field and button labels are translated into each language.
List items: The display of list items is translated for each language. Examples of the translatable locale address format properties files are:
\runtime\properties\UserRegistrationText_xx_XX.properties
\runtime\properties\UserRegistrationB2BText_xx_XX.properties Where xx_XX represents a locale. Those properties files hold the translatable text needed by the UserRegistration sample shipped with WebSphere Commerce.

Address and name formating in the tools Address and name formatting in the WebSphere Commerce tools is accomplished through the use of XML files to encapsulate the address/name format control information. The XML files hold address/name control information such as what fields are required, the number of lines that constitute an address/name format, the sequence and nature of address/name attributes that should be displayed on one line, etc. The following is a high-level description of the address/name format approach followed by the WebSphere Commerce tools: 1. Create an XML file to hold your address format information. For example:

Refer to \xml\tools\order\addressFormats.xml for sample implementation. 2. Use the tools framework XMLUtil.get(Hashtable tree, String path) to parse your XML file. This method is one of the utility classes to read and write XML files and strings contained in the tools framework. When reading XML files and strings, these parsers turn the XML data into a hashtable.

236

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

3. Use the address format control information stored in the hashtable created in the previous step to display the formatted address attributes to the end user. This following is an example: \wc.ear\CommerceAccelerator.war\tools\order\OrderBillingAddressPag e.jsp

8.4 WebSphere Commerce application model As discussed in the introduction, there are a number of characteristics that can be associated with a globalized site. Some of these characteristics are associated with display preferences, while other characteristics more closely resemble business logic. In order for a merchant to correctly model a globalized site, it is necessary for them to be able to model linguistic and cultural display preferences, business logic, and business processes in easy-to-manage pieces. Table 8-7 lists a high-level representation of the WebSphere Commerce application model. Table 8-7 WebSphere Commerce application model Layer

Features

Models




Tools with built-in support to manage multilingual data




Tools that are browser based and fully multilingual enabled




Multilingual store samples and documentation models




Pricing and promotions




Dynamic includes for dynamic look and feel




Built-in, correctly formatted data presentation




Built-in currency conversion and currency formatting




Dynamic language fallback




A single JSP component to handle all languages




Tax rules




Shipping logic




Pricing and promotions




Contain all data pulled by entity objects




Run in Unicode




Database in Unicode




Separated language and cultural items

Business processes Controls and Views

Business components

Business objects

Database

Chapter 8. Globalization guidelines

237

8.4.1 Language table A number of parameters are used within WebSphere Commerce to identify business qualifiers, such as the following:





Language preference of the shopper Cultural formatting preferences for the shopper Store location the shopper is shopping from Where the shopper is located

Without this information, it would be very difficult to offer the correct product set to the shopper at the correct prices and currencies. It is also not possible to display product description information in the correct language or formatting. WebSphere Commerce has introduced a formatting parameter that utilizes the Java Locale to identify the language, encoding and cultural formatting preference of the user. This parameter is called language_id. The language_id parameter is used as a key within most of the descriptive tables within the WebSphere Commerce instance database schema. The exact formatting that each language format represents is defined within the LANGUAGE table, which is qualified by a Java locale. Therefore, when the users select their preferred language, they select a number of display preferences to view the site. Formatting includes items such as how dates are represented and how numbers are formatted. The advantage of using the language_id parameter instead of directly using a locale is that it allows a merchant to define a number of distinct languages that can share the same formatting locale or a number of similar languages that have different formatting. For example, it is possible for a merchant to define English spoken in Singapore and have it formatted with the en_US locale, but at the same time allowing the merchant to enter a different description for it instead of being forced to use the American English description. This also allows a merchant to provide a number of different descriptions for a product in many different languages, all of which can share the same formatting locale. For example, a merchant would be able to create a language format that defines language as American English using the ISO-8859-1 encoding with the US formatting scheme. Table 8-8 on page 239 describes how the column names and types are modeled within the LANGUAGE table of the WebSphere Commerce instance database schema.

238

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Table 8-8 WebSphere Commerce LANGUAGE table Column name

Column type

Column description

Country

CHARACTER(5) NULL

Country or region component of the locale.

Encoding

VARCHAR(32) NIULL

The Character encoding value that the browser should use to display the page for this language.

Language

CHARACTER(5) NULL

Language component of the locale.

Language_ID

Integer Not NULL

A unique key for the language, used as part of the foreign key in tables that contain language-dependent information.

Localename

CHARACTER(16) Not NULL

A Java locale used to represent a political, geographical, or cultural region that has a distinct language and custom for formatting.

MIMECHARSET

VARCHAR(32) NULL

The MIME character encoding that the notification system uses to encode a message for this language.

VARIANT

CHARACTER(10) NULL

Variant component of the locale. Used to specify the locale character set or to further segregate a distinct formatting for a political, geographical, or cultural region.

Note: The term locale in software development is borrowed from the field of geography. The geographical term locality refers to a particular place, location or situation. A locale represents a specific geographical, political, or cultural region. Locale in the Java world is an object that consists of three parts: language, region, and variant. The language and region are normally the two-character ISO language and country codes. The region code often but not always represents a country. The variant is an arbitrary string used when there are multiple locales for the same language and region. Each row of Table 8-8 represents a language. Out of the box, WebSphere Commerce includes support for 10 languages/locales, which are populated by default (see Table 8-9 on page 240). Users can add other supported languages/locales by using the predefined ISO codes.

Chapter 8. Globalization guidelines

239

Table 8-9 WebSphere Commerce supported locales Locale

Language and Territory

langId

en_US

English US

-1

fr_FR

French France

-2

de_DE

German Germany

-3

it_IT

Italian Italy

-4

es_ES

Spanish Spain

-5

pt_BR

Portugese Brazil

-6

zh_CN

Simplified Chinese China

-7

zh_TW

Traditional Chinese Taiwan

-8

ko_KR

Korean Korea

-9

ja_JP

Japanese Japan

-10

There is another table added to complement the LANGUAGE table, which allows merchants to set a fallback language format. This table is called LANGPAIR. The LANGPAIR table allows a merchant to map one or more fallback formats to try if the description of the initial format is not found. When the fallback language format is set, merchants will be able to ensure that they will always have a description for a product or catalog, even if they don't have a fully translated catalog. For example, a merchant creates two language formats: format A for US English, and format B for Canadian English. In this case, the catalog and product descriptions are very similar in Canada and the US, with only a small set of descriptions being different between the two. The merchant can therefore create a complete catalog in US English, and a partial catalog in Canadian English to address the differences by seting the fallback language format to be US English format. A merchant can also set more than one default for a language format so that if the initial fallback is not found, the fallback language format with the next highest priority sequence number is used instead. Table 8-10 on page 241 describes the columns and types for the LANGPAIR table found within the WebSphere Commerce instance database schema.

240

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Table 8-10 WebSphere Commerce LANGPAIR table Column name

Column type

Column description

LANGUAGE_ID

INTEGER Not NULL

The requested language. Foreign key to the LANGUAGE table.

LANGUAGE_ID_ALT

INTEGER Not NULL

The alternative language.

SEQUENCE

DOUBLE Not NULL Default 0

When the requested language is supported by the store but information is not available in that language, each alternative language is tried in ascending order of SEQUENCE.

STOREENT_ID

INTEGER Not NULL

The StoreEntity that this relationship is part of.

If no description is found for the initial language or any of the fallback formats, then the description will be retrieved according to the default store format. Before we move on to the next section, it is worth mentioning the order of determining the user’s requested (active) language:
Highest: The language defined in the command (language_id parameter of the URL).
Current session language (result from the last/previous operation).
The language defined in the user profile (user-preferred language).
Store default language.

8.4.2 Introduction to encoding Computers deal with numbers only. They store and process characters by assigning a number for each one. There are hundreds of different systems for assigning these numbers. These systems are called encoding systems or encoding schemes. Character encoding has always been one of the least understood subjects in the science of software internationalization and localization. Some common questions are as follows:





What is Unicode? Is Unicode an encoding or a character set? What is the difference between UCS-2 and UTF-8? Is a character the same thing as a glyph?

When working with developers, we found that very few developers were able to clearly differentiate between character encoding, encoding scheme, code page,

Chapter 8. Globalization guidelines

241

character set, and coded character set. The reason behind this confusion is that one can rarely find two books, two papers or two journals that agree on the definition of those terms. Since understanding encoding and encoding-related topics is essential for comprehending the WebSphere Commerce data model, we will spend some time in this section breaking the byte barrier and discussing encoding and character representation concepts in more details. The following is a list of some easy-to-understand definitions on encoding and related topics:
Character The smallest symbol in a written language that represents information (for example, letters, ideograph, digits, punctuation marks, etc.).
Abstract Character Set A group of abstract characters that form one alphabet. The individual character in a character set are not mapped to a numerical value (for example, Greek alphabet, Arabic alphabet, Latin alphabet. etc.).
Coded Character Set A coded character set is a character set in which each character is mapped to a code point (numerical value or position in a table). US-ASCII and JIS (East Asian) are examples of very common coded character sets.
Character Encoding Form The mapping of code points to a series of fixed-length bit patterns (7-bit, 8-bit, 16-bit, 32-bit) called code units.
Encoding (Encoding Scheme or Encoding System) The process by which each code point in a coded character set is mapped (serialized) to a given sequence of bytes (that is, converted into a digital representation so it can be stored in a file or a database). Important: The term glyph is commonly confused with the term character. A glyph is a concrete visual representation of a character or part of a character. A glyph is one of many possible shapes of a given character. A character could be represented by a single glyph, or by different glyphs positioned (compounded or connected) appropriately. In bidirectional languages such as Arabic, glyphs are required to change their shape and widths depending on the position of the character they represent in the word and grammar.

242

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Note: In IBM the term code page refers to a coded character set. However, the generic use of code page is to refer to character encoding schemes. Some encoding schemes, such as the UTF-8, are used to serialize several character sets. Others are unique to a given character, such as the Big5 encoding of the Traditional Chinese character set. In some cases the encoding is just a direct mapping of the numerical values and there is no distinction between the coded character set, encoding form and the encoding. In other cases, when dealing with languages that need more than one byte to cover the inventory of their characters, such as Chinese, both Traditional and Simplified, Japanese, and Korean, known as CJK, the encoding is more complex. It involves multiple code units (multiple bytes). The distinction between encoding and a coded character set: Windows Cp1252: In the ASCII coded character set, the character Ä is assigned the numerical value 196. The Character is encoded as byte 0xC4 in the Windows Cp1252 encoding. There is no distinction between the encoding and the coded character set. Furthermore, the character encoding form mapping is null. UTF-8: In the Unicode coded character set, the character Ä is also assigned the scalar value 196(U+00C4). However, the same Character is encoded as two bytes: 0xC3+0x84 in the UTF-8 encoding (The character is mapped to two code units each of 8-bit length). DBCS is the abbreviation for Double Byte Character Set. Most written Asian languages (Chinese, Korean, Japanese, etc.) are based on ideographic symbols rather than an alphabet. Those languages have thousands of characters beyond the limit of one byte representation (that is, beyond 256 characters). When using two bytes, one can represent up to 65536 characters (256 x 256), enough to represent the coded character sets of any of the Asian languages needing double-byte support. Confusion can arise when using the phrase double-byte, as this phrase is usually thought of as the number of bytes needed to store one character as opposed to the way in which the DBCS characters are typed (using two English characters).

Chapter 8. Globalization guidelines

243

8.4.3 Unicode Unicode is essentially one giant coded character set that contains the characters of all the world's major languages. When using Unicode, it is possible to display multiple languages simultaneously, since all the characters in all the languages are defined within it. Before Unicode was created, hundreds of different encoding systems had been used, each in conflict with one another. That is to say, no two encodings could use the same number for two different characters, or use different numbers for the same character. Unicode allows data to be transported through many different systems without corruption, because it provided a unique number for every character. Unicode can be used as a medium of communication for the application server and database, so that the user's data can always be stored without corruption, no matter what the original encoding. Another benefit of using this unified standard for encoding is its ability to present sorted results based on locale-specific, multilevel collation rules. For more detailed information on the Unicode standard and consortium, as well as code charts, refer to the following Web site: http://www.unicode.org/

UTF-16 vs UTF-8 In 1992, the International Organization for Standards (ISO), and the International Electrotechnical Commission (IEC) formed the ISO/IEC 10646 standard, with the objective of being compatible with existing coded character sets, such as ASCII and ISO Latin 1. Parallel to the development of the ISO/IEC 10646 standard, Unicode was being developed by the non-profit Unicode consortium. Unicode was designed to embrace the following principals:
Universal: Code points to cover all of the world’s major languages.
Unique: Characters to have exactly one mapping to a given sequence of bytes.
Uniform: Fixed-width characters encoded in the same number of bits. To avoid having two competing 16-bit standards, the two development organizations compromised to define a common coded character set (Universal Character Set), known as both Unicode and Basic Multilingual Plane (BMP), encoded using two different standards.

244

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Note: UCS is the abbreviation for Universal Multiple-Octet Coded Character Set, which received its name from the ISO/IEC 10646 standard for the Universal Character Set. UCS-2 is the 2-Octet BMP form. It can represent all characters in BMP in 2-octet. UTF is the abbreviation for Unicode Transformation Format or Universal Character Set, and it defines a set of different transformations of UCS as different representations for data transfer. The most common transformation formats (UTF) are UTF-16 and UTF-8. Both encoding schemes encode the same character repertoire, such as Unicode 1.1, Unicode 2.0, Unicode 3.0, Unicode 3.1, etc. We will examine the UTF-16 and UTF-8 encoding schemes in more detail.

UTF-16 UTF-16 is the Unicode Transformation Format that serializes a Unicode code point as a sequence of two bytes, in either big-endian (bytes read left to right) or little-endian format (bytes read right to left). Because it is grouped by code units of 16-bit length (2 bytes), it is called UTF-16. Each Unicode code point up to U+FFFF is encoded as a single 16-bit value. Code points above U+FFFF are represented as a pair of 16-bit high and low surrogate. In this encoding, even the 7-bit US-ASCII characters are represented by a 16-bit code.

UTF-8 UTF-8 is a multibyte 8-bit flavor of UTF that each Unicode code point is a mapped to a sequence of one to four bytes. Because it varies from 8 bits (1 byte), it is so called UTF-8. UTF-8 is compatible with US-ASCII if no extended characters (for example, characters that require the 8th bit to be represented) are present. Table 8-11 lists the number of bytes required to represent every Unicode code point using UTF-8. Table 8-11 Code point range in UTF-8 Code point range

Number of bytes

0x00..0x7F

1 byte

0x80..0x7FF

2 bytes

0x800..0xD7FF, 0xE000..0xFFFF

3 bytes

Chapter 8. Globalization guidelines

245

Code point range

Number of bytes

0x10000 .. 0x10FFFF

4 bytes

The last point to cover before we move to the next section is, what flavor of UTF is preferred? For example, should one use UTF-8 or UTF-16? The answer is simple. It depends on the nature of the data being saved. If the majority of the data being saved in the database and/or the file system is basic Latin characters (Latin-1 characters), then it would take twice as much space to store the data in UTF-16 than in UTF-8 and thus UTF-8 is preferred. For this reason, WebSphere Commerce uses UTF-8. On the other hand, If the majority of the data being saved is non-Latin extended characters (the 3 bytes range), UTF-8 takes more space. What is a surrogate? Two bytes are not enough to accommodate all the world’s common languages. Thus, Unicode was expanded to comprise 17 planes:
Plane 0, the Basic Multilingual Plane (BMP), covers code points U+0000 through U+FFFF
Planes 1 through 16 have been reserved to cover code points U+10000 through U+10FFFF. One way to reference the code points in the supplementary planes is to make use of surrogate pairs of 16-bit code points. The code points U+D800 through U+DBFF are reserved as high surrogates, and the code points U+DC00 through U+DFFF are reserved as low surrogates. Each code point in a supplementary plane maps to a pair of 16-bit code points comprising a high surrogate followed by a low surrogate.

What is the difference between UCS-2 and UTF-16? UTF-16 without support for surrogates is just like UCS-2. The difference lies in the surrogate planes. UCS-2 can represent only BMP characters. Surrogate-plane characters cannot be represented in UCS-2. In other words, UTF-16 is UCS-2 plus the surrogate mechanism. Since there are no characters currently defined in the surrogate planes, the difference between UCS-2 and UTF-16 is really negligible.

Use of Unicode in WebSphere Commerce WebSphere Commerce uses Unicode databases for both DB2 and Oracle, and the database charset is UTF-8. While it is possible to convert data originally encoded using many different encodings into Unicode and to store this information safely within a database, it is a much greater challenge to display this

246

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

information via a Web page. The key decision is under what encoding should the pages displayed in. Typically, the general rule is that any data that is being sent out to the client should be converted into the client's browser's default encoding. This ensures that their browser will be able to display at least some of the data. However, in order to display multiple languages, it will be necessary for the client's browser to support Unicode.

Encoding store pages We recommend that developers use native encoding instead of UTF-8 for store pages that shoppers will browse. The primary reason for this recommendation is that merchants will likely not know with certainty what browser levels or browser configurations a shopper would be using to access their site. If the data is not converted to the client's default browser encoding and the shopper's browser does not support Unicode, garbled characters would appear in the shopper's browser. This is not desirable since there is a strong likelihood that the merchant would lose the business of that customer. Therefore the information will always be converted into the native encoding of the shopper’s browser.

Encoding tools pages There is a requirement for WebSphere Commerce tools to be able to maintain information in multiple languages. Also, only one browser, Microsoft Internet Explorer V6 is officially supported by WebSphere Commerce tools. Therefore, Unicode is uses to encode all out-of-the-box tools pages. This allows a merchant to maintain data that is in multiple languages.

8.4.4 WebSphere Commerce data model: input WebSphere Commerce is designed such that a single store can work with any language. A single store can display pages in multiple languages, even when the languages use different character sets. To accomplish this, the WebSphere Commerce instance database is configured at creation time to store data in UTF-8 encoding. A UTF-8 database supports multiple language storage in a single database and the database has the correct character mappings to handle all single-byte, double-byte, and bi-directional characters. When data is requested by a JSP page from the UTF-8 encoded database, the data is converted into an appropriate character set. The JDBC drivers load data from the database and convert text data from UTF-8 to Java's native 16-bit Unicode encoding. Developers need to understand the multilingual programming model to take advantage of this feature.

Chapter 8. Globalization guidelines

247

To better understand how data is transferred from the Web browser to the Database, refer to Figure 8-5 on page 248 and the following text: 1. Data is entered into the Web browser. Multilingual data can be entered using an input method editor. 2. WebSphere Commerce converts the data coming in from the Web browser into Java 16-bit encoding using the setCharacterEncoding() method. Each LANGUAGE_ID in the LANGUAGE table is mapped to an encoding value using the ENCODING column. This value is used to interpret the data coming from the Web browser 3. The data is sent to the database, where the JDBC driver converts it from Java 16-bit to UTF-8 encoding, which is how it is stored in the database. Note: Input Method Editors (IMEs) were created so that language scripts with large character inventories such as CJK (Chinese, Japanese and Korean) can enter all of the available characters from a limited number of keys on the keyboard.

Conversion by WAS to UTF-16 (using the Encoding Value in the Language Table)

Conversion by JDBC Driver to UTF-8

DB UTF-8

JDBC Driver

Java Code Unicode UTF-16

JSP

WC Servlet API

Browser Encoding XXX

Unicode UTF-16

Figure 8-5 Data transfer from Web browser and database

Another data input vehicle in WebSphere Commerce is the mass import tool MassLoader. The MassLoader supports the import of such features as catalog data, payment data, taxation data, shipping data, access control data, etc., in XML format. The XML data is turned into SQL statements and populated in the database using JDBC. The tool supports the import of Unicode and non-Unicode data. Any non-Unicode data gets converted into Unicode before reaching the UTF-8 database.

248

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

It is essential that developers understand the different data conversions that take place between the XML input file and the database as described below: 1. Parse the XML document encoded in any encoding. The XML Parser converts the data in the original encoding to Java String objects encoded in UTF-16. 2. Compose the SQL statement. 3. Execute the SQL query through JDBC. Java String Object. Values are in UTF-16. 4. Either: – DB2/CLI receives the query and converts the encoding of the incoming data into the database destination character encoding (UTF-8). or – Oracle/OCI receives the query and converts the encoding of the incoming data into the database destination character encoding (UTF-8). Figure 8-6 on page 249 depicts the data conversion of XML data using the MassLoader with a DB2 database.

MASSLOADER

XML File

€ in any character encoding

XML Parser Characters in Unicode (codepoint 0u20AC)

DB2

JDBC Driver Characters in Unicode (codepoint 0u20AC)

DB2 CLI

DB

Characters in Unicode (codepoint 0u20AC)

Characters in UTF-8 (codepoint 0xE282AC)

Figure 8-6 Data conversion for XML data round trip using the MassLoader on DB2

Figure 8-7 depicts the data conversion of XML data using the MassLoader with an Oracle database.

Chapter 8. Globalization guidelines

249

MASSLOADER

XML File

€ in any character encoding

XML Parser Characters in Unicode (codepoint 0u20AC)

DB2

ORACLE OCI

DB

Characters in Unicode (codepoint 0u20AC)

Characters in UTF-8 (codepoint 0xE282AC)

JDBC Driver Characters in Unicode (codepoint 0u20AC)

Figure 8-7 Data conversion for XML data round trip using the MassLoader on Oracle

Important: The MassLoader tool uses the Oracle OCI JDBC driver, thus setting the NLS_LANG environment variable to UTF8 is required on the client side before MassLoading to avoid data corruption You could set the variable in the command window, but preferably set it as a system environment variable. The format for the NLS_LANG variable is as follows: NLS_LANGUAGE_NLS_TERRITORY.NLS_CHARACTERSET For example, Japanese_Japan.UTF8

8.4.5 WebSphere Commerce data model: output In this section we discuss the second part of the data round trip between the Web browser and the database (browserWebSphere Commerce Serverdatabase). The following steps outline how data travels from the database to the Web browser: 1. Data is stored in the database using UTF-8 encoding. The WebSphere Commerce Configuration Manager configures the WebSphere Commerce instance database at creation time to store data in UTF-8. 2. JDBC drivers load data from the database and store textual data in java.lang.String. To do this, the drivers convert text data from UTF-8 to Java's native 16-bit Unicode encoding. 3. Strings are handled inside the Java code as Unicode 16-bit encoding. 4. JSP output strings using Unicode 16-bit encoding, because JSP is 100% Java code.

250

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

5. JSP authors can specify the encoding to be used to send the HTTP response to the Web browser. For example: )

6. The WebSphere Application Server will convert JSP output text from 16-bit Unicode to the target encoding as specified in the JSP (for example, Shift-JIS). The converted data will be sent back to the Web browser. The WebSphere Application Server will also specify the encoding used in the HTTP reply (for example, Content-type: text/html; charset=Shift-JIS). 7. The Web browser will interpret the HTTP reply based on the encoding specified in the header. Since not all Web browsers can understand all encoding schemes, it's better to specify only the most well-known encoding schemes in the JSP (for example, UTF-8 and Shift-JIS). Figure 8-8 on page 251 depicts the WebSphere Commerce output data model, where data is transferred from the database to the Web browser.

Conversion by WAS to encoding XXX (specified by ContentType statement)

Conversion by JDBC Driver to UTF-16

DB UTF-8

JDBC Driver

Java Code Unicode UTF-16

JSP

WC Servlet API

Browser Encoding XXX

Unicode UTF-16

Figure 8-8 Data transfer from database to the Web browser

8.5 Globalized catalog content The WebSphere Commerce catalog subsystem is designed to facilitate the creation and processing of globalized catalogs. All catalog descriptive tables are qualified by a language format column (language_id). In addition to this, the attribute tables are also qualified by the same language format column. At runtime, the command context is sent through a data bean to determine which translation to retrieve from the database and display on the page.

Chapter 8. Globalization guidelines

251

The globalized catalog design in WebSphere Commerce provides the following features:
Product descriptions and attributes can be culturally specific. The merchant has the ability to create a catalog that allows product descriptions and attributes to be culturally specific. This master catalog contains all of the products that the merchant offers in all the language formats that the merchant supports. Not all products need to be available in all the supported languages formats and all types of formatting.
Multiple descriptions or attributes for same product and language. Ability to provide multiple descriptions or attributes for the same product in the same language. This allows stores that share products to offer different descriptions for the same product in the same language.
Depending on the locales that the store supports, different features of the same products may need to be highlighted in different locales. Different images may be appropriate for different locales. Prices may be varied and can be expressed in different currencies. For more detailed information, refer to the WebSphere Commerce V5.5 online documentation, and the WebSphere Commerce JavaDocs associated with the catalog subsystem.

8.6 Globalized store design A store typically contains several types of pages. A globalized store is a store in which all pages are enabled for globalization. In WebSphere Commerce, globalization enablement of store pages is accomplished through the use of language-independent and culturally sensitive templates. A template is a skeleton or pattern that defines how information in the WebSphere Commerce instance database will be displayed on a Web page. The template determines the location and type of text and images on the page, as well as other page attributes, such as a background color. These elements are defined in templates created with JavaServer Pages (JSP) technology using HTML tags or beans that are linked to the WebSphere Commerce instance database. To manage static pages and dynamic templates in a globalized environment, it is necessary to store files in a directory structure that allows for the quick and easy identification of the files and which locale they belong to. The file directory path is constructed based on the WebSphere Commerce instance, the store path contained within the store profile, and also the registered file path.

252

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

In WebSphere Commerce, the management and storage of templates in a globalized environment is referred to as template management. There are three models for template management:
One template for all stores and languages
One template per language
One template per store Note: Details about each of the above models can be found in the IBM WebSphere Commerce V5.5 online documentation. To manage static pages and dynamic templates in a globalized environment, it is necessary to store files in a directory structure that allows for the quick and easy identification of the files and which locale they belong to. In WebSphere Commerce, the file directory path is constructed based on the Commerce instance, the store path contained within the store profile, and also the registered file path. When you create a globalized site, you create multiple stores, each one having a list of supported languages. Since the template files influence the look-and-feel of a site, the template files are stored under locale-specific directories so that they can be selected similar to the manner in which resource bundles are selected, using a locale value. When the system selects a template to use for a particular language format, the locale is used to determine the language format that will be used to determine the directory from which the file is retrieved. The sample stores provided with WebSphere Commerce follow the one template for all stores and languages model. If you are creating store pages to work with existing sample store pages, they should also follow this model. Also, the use of one template per store model is discouraged, since it provides the lowest levels of maintainability and scalability in a globalized environment.

8.6.1 Globalized page framework: one template for stores/languages While there are various options from which to choose when creating a globalized store, the one that offers the most globalized approach is that of a single, culturally neutral template that calls or includes culturally sensitive content at runtime. This model makes maintenance simple, since changes to the design of a page only need to be made once. It also makes adding or removing languages or cultures simple, since the culturally sensitive content is kept separate from other features of the page.

Chapter 8. Globalization guidelines

253

Figure 8-9 on page 254 depicts the one template for all stores and languages programming model. This globalized programming model offers a powerful way to design and organize your e-commerce site. Each page consists of a single JSP template, containing a basic page layout and culturally neutral data and images. This template is combined at runtime with culturally sensitive components, based on the display format selected by the customer. With this model, each supported language has its own property file. Within the property file, a number of page elements are translated:





Text: Textual page content. Labels: Form field labels. Messages: Error, status, and confirmation messages. Alternate text: For images, Java applets, and other embedded objects.

The encoding of the text is also indicated in the property file under the ENCODESTATEMENT property. This indicates the encoding in which the text is displayed in a Web browser. Because it is specified within the property file, the encoding can be different for each language. The value is retrieved from the property file, and the character-encoding of the generated JSP is set using the following statement in the JSP template:

en_US JSP templates

Displayed JSP files

Message files (resource bundles/ property files)

fr_CA de_DE fr_FR

image/ text

Included page components (such as header, footer, or navigation bar)

Image files (culturally neutral)

en_GB

Image files (culturally specific)

Figure 8-9 Globalized page framework: one template for all stores and languages

254

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Resource bundles Resource bundles allow you to maintain collections of Java objects that are locale-specific for your JavaServer Pages. When the page needs a locale-specific resource, such as a form field label, a graphical user interface message, or a value for a drop-down menu, the page can load it from the resource bundle or property file that is appropriate for the selected locale, allowing the customer to view the page in their own language. In this way, you can create language-independent core application while leaving the chance to create as many translated versions as translation is done. Such modules can be created in Java through the use of ResourceBundle class. The ResourceBundle class is included in Java.util package. Practically, for ease of use, you may want to use its subclasses:
PropertyResourceBundle (properties files)
ListResourceBundle Although ListResourceBundles and properties files perform similar functions, there are some differences in the manner in which they are processed. Table 8-12 shows some of the more important differences between ListResourceBundles and properties files. Table 8-12 Comparison between ListResourceBundles and properties files Class name

Objects Stored

Format of resource file

Performance

PropertyResourceBundle

String only

Flat text file. Editable. (Properties file)

Slightly slower

ListResourceBundle

Any kind of objects

Byte code. Needs compilation after editing

Faster

In WebSphere Commerce, using PropertiesResourceBundles to separate translatable text as the format of the ListResourceBundles (properties file) is much easier to translate and maintain than the Java files associated with ListResourceBundles. Unless the performance of your application is severely degraded or there is a need to use non-string type, we recommend the use of PropertiesResourceBundles. The search order used by which properties files are retrieved in Java (ResourceBundle.getBundle) is as follows: 1. basename_language_region_variant 2. basename_language_region 3. basename_language If we take Japanese as an example, the Japanese property file should be named either AddressText_ja.properties or AddressText_ja_JP.properties. For the

Chapter 8. Globalization guidelines

255

Chinese languages, the locale name for the S-Chinese is zh_CN, and for the T-Chinese is zh_TW. Therefore, you must include the country name to distinguish property files for these two countries.

Native2ascii tool The Java compiler and other Java tools can only process files that contain Latin-1 and/or Unicode-encoded (\udddd notation) characters. This is because Java uses Unicode as its internal encoding. However, most operating system, editors, and other tools still use regional code pages to represent text. In most cases, this means that you will create your .java files in a regional encoding, not Unicode. Of course, the Java compiler must compensate for the difference by converting your native code page into Unicode. The native2ascii tool converts files that contain other character encodings into files containing Latin-1 and/or Unicode-encoded characters. ISO-8859_1 characters are represented as they are, while characters other than ISO8859_1 are represented in the Unicode escape sequence, which is preceded by \u. For example, the phrase DDEmad, where DD represents a DBCS character, is converted to \u3053Emad. The properties files of languages other than Latin-1 languages (ISO-8859_1) must be converted to the Unicode-encoded characters format using the native2ascii tool such as the following: The native2ascii tool is run as follows: native2ascii [options] [inputfile [outputfile]] Example: conversion from the Japanese Shift-JIS encoding: native2ascii -encoding Shift_JIS GreetingResource_ja_JP.temp GreetingResource_ja_JP.properties

Also there are some cases where you want to convert from the Unicode-encoded format to the original character encoding. You can use the reverse option to do so, as follows: native2ascii -reverse -encoding Shift_JIS GreetingResource_ja_JP.properties GreetingResource_ja_JP.temp

Note: The native2ascii tool is included in both the SUN Java2 SDK and IBM JDK. The JRE, which is the runtime environment only, does not include native2ascii.

256

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Tip: The Java compiler automatically assumes that your resource files are written in the default code page of your operating system. Therefore, if you are using a U.S. English version of Solaris, the compiler will probably assume your character set is Cp1252(ISO_8859-1). Although 8859-1 supports many languages, it doesn't represent everything. So, if you need to compile a Japanese resource bundle, you would get incorrect results. As an alternative to using the native2ascii tool, the Java compiler allows a command-line directive that specifies the encoding of the source file. Using the appropriate converter, you can direct the compiler to accurately convert the .java source into Unicode. The following example shows the command line directive you would use to compile a Japanese resource bundle that's written in Shift_JIS, the popular Japanese encoding: javac -encoding Shift_JIS GreetingResource_ja_JP.java

Use of resource bundles in the store pages The store pages use JSP templates that are largely independent of the customer's locale. At runtime, each requested JSP includes the file EnvironmentSetup.jsp. Within this file, the command context is retrieved, and from that, the locale is retrieved as follows: CommandContext cmdcontext = (CommandContext) request.getAttribute(ECConstants.EC_COMMANDCONTEXT); Locale locale = cmdcontext.getLocale();

The locale is used to retrieve appropriate locale-specific ResourceBundle (properties file) through a call to the StoreDataBean.getResourceBundle as seen in Example 8-3. Example 8-3 Sample of StoreDataBean.getResourceBundle from JSP

....... JSPResourceBundle infashiontext = (JSPResourceBundle) request.getAttribute("ResourceText"); JSPResourceBundle infashionDynamictext = (JSPResourceBundle) request.getAttribute("ResourceDynamicText");

Chapter 8. Globalization guidelines

257

JSPResourceBundle auctionSampletext = (JSPResourceBundle) request.getAttribute("AuctionSampleText"); if (infashiontext == null) { infashiontext = new JSPResourceBundle(sdb.getResourceBundle("infashiontext")); request.setAttribute("ResourceText", infashiontext); } if (infashionDynamictext == null) { infashionDynamictext = new JSPResourceBundle(sdb.getResourceBundle("infashiontext_dynamic")); request.setAttribute("ResourceDynamicText", infashionDynamictext); } if (auctionSampletext == null) { auctionSampletext = new JSPResourceBundle(sdb.getResourceBundle("AuctionSample")); request.setAttribute("AuctionSampleText", auctionSampletext); }

The template then has access to each of the properties as needed, through the use of the getProperty() method of the properties object. Dynamic data is retrieved at runtime using various server bean methods and is performed in the context of the current language. Example 8-4 shows the request for the language-specific store display name. The returned value for the language parameter (language_ID) will determine the language in which the store name will display, having been retrieved by the getDisplayName method of the StoreDataBean. Example 8-4 Request for language-specific store display name // Name of the store String storeName;

258

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

try { storeName = sdb.getDescription(cmdcontext.getLanguageId()).getDisplayName(); } catch (Exception e) { // store name is not defined storeName = " ";

}

The locale and language are retrieved at runtime to determine the correct folder in which to look for the image file. For example, the template might look for the file FashionFlow/xx_XX/images/go_button.gif , where xx_XX is the language_Country part of the locale retrieved from the command context. For example, the resulting page will display the image: FashionFlow/en_US/images/go_button.gif FashionFlow/ja_JP/images/go_button.gif

8.6.2 Support for bi-directional languages Languages such as Arabic, Hebrew, Farsi, Urdu, and Yiddish have their text written from right to left. Numeric and embedded segments of Western language text are written from left to right. Because of this possible mixture of text segments in two directions, as displayed in Figure 8-10, those languages are called bi-directional or BiDi for short.

Figure 8-10 Example of the mixture of text segments

Mirroring of graphic user interface elements If the global orientation is right to left, as is the case for BiDi languages, then most of the GUI elements in the window body should appear mirrored from the left-to-right window. For example, in a right-to-left window, the position of the vertical scroll bar appears to the left of the scroll box, and radio buttons are to the right of their labels. Other elements, such as the title bar icon, the title bar, and the minimize and maximize buttons, remain the same as in the left-to-right window to ensure consistency in usability. Figure 8-10 displays an example of a mirrored vertical scroll bar.

Chapter 8. Globalization guidelines

259

The HTML specifications provides BiDi support through the use of a number of language information and text direction attributes/elements. The main such attribute is the dir attribute. The dir attribute specifies the base directionality of the following:
Portions of document’s text
Entire document (at the declaration level)
Table structure The possible values of the dir attribute are either RTL (read as right-to-left) for BiDi languages or LTR (read as left-to-right - the default value) for non-BiDi languages.

Figure 8-11 Mirroring of a GUI element

One of the challenges that face store developers in WebSphere Commerce is specifying the direction of text when using the recommended single page template for all languages model to develop multilingual store pages that include both BiDi languages and non-BiDi languages (left-to-right languages). The directionality attribute dir has to be set properly in the single JSP template depending on the nature of the language selected by the shopper/buyer (for example, if the shopper selects a BiDi language, the dir attribute should be set to RTL and set to LTR otherwise). Figure 8-12 on page 261 shows how Arabic characters are wrongly aligned to the left of the GUI objects when the dir attribute is set wrongly to LTR.

260

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Figure 8-12 Arabic characters misaligned because of wrong dir attribute setting

WebSphere Commerce provides two ways to dynamically set the dir attribute, and other HTML BiDi specifications, to the correct value in the JSP template: 1. Encapsulating of the directional HTML elements, as shown in Example 8-5. Example 8-5 Encapsulating of directional HTML elements



Chapter 8. Globalization guidelines

261

The is the language_id of the BiDi language that // needs the dir attribute to be set to “RTL”. For example:

2. Use a locale-specific Cascading Style Sheet (CSS file) in which you can specify the directionality attribute. a. Create one CSS file for each of the languages supported by your store. Table 8-13 lists the equivalence between HTML and Style Sheet BiDi features. Table 8-13 Style Sheet BiDi features

262

HTML

Style Sheet

dir=”rtl”

direction: rtl; unicode-bidi: embed;

dir=”ltr”

direction: ltr; unicode-bidi: embed;

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

b. Create a method similar to UIUtil.getCSSFile(locale) described in 8.9.2, “Using locale-dependent Cascading Style Sheets (CSS)” on page 285 to load the locale-specific CSS file. Encapsulate this method in a JSP include file.

8.6.3 Understanding the localized store assets As described so far in this chapter, globalization permeates the WebSphere Commerce suite of products. Localization is, therefore, embedded in almost all of the store data assets. In this section, we will highlight those store assets to which localization is most relevant. We will discuss the localization of the following store assets:





Language assets Currency assets Tax assets Shipping assets

Language assets in WebSphere Commerce stores There are four classifications of languages in WebSphere Commerce:
Default language A default language is associated with each store. This is the language that the store has chosen to use as its main language, and will be the language displayed to customers that do not explicitly choose a shopping language. The default language for a store is implicitly supported by the store; that is, the store must always be able to display information in the default language, or one of its alternative languages, if any are defined in the LANGPAIR table. When information is not available in one of its supported languages, or alternative languages, the information will be displayed in the default language.
Supported language The STORELANG table indicates the languages each store supports. A store must be able to display information in its supported languages, or one of their alternative languages, if any are defined in the LANGPAIR table. A store also supports all languages supported by its store group.
Alternative language When information is not available in one of the supported languages, the store tries to display the information in an alternative language, if it is available. A store can specify the sequence in which to try each of its alternative languages. The alternative languages for a store include the alternative languages for its store group. Alternative languages can be useful when some information is available in only one language, but should be made

Chapter 8. Globalization guidelines

263

available to customers shopping in a different, related, language. This might be the case when, for example, not all information has yet been translated into all supported languages, or when, for example, two very similar dialects of the same language are supported, sometimes with identical information. For more detailed information on the structure of language assets in WebSphere Commerce Server and Store, see the language data models in the WebSphere Commerce V5.5 online documentation and the Store Development Guide, IBM WebSphere Commerce V5.5, respectively.

Currency assets in WebSphere Commerce stores You can display prices in your site in multiple currencies. For a site with multiple stores, you can use different currencies for the stores, or you can assign currencies to the store group. Depending on the nature of the site that you are creating, you can specify what currencies you want to use and how they are displayed. You can also allow customers to select a shopping currency. Currency is at the center of the WebSphere Commerce Server information model. The following table illustrates the currency structure in the WebSphere Commerce Server and Store:
Currency format A store entity can have many currency formatting rules. If a store does not have a formatting rule for a particular currency, it uses the formatting rule of its store group. Currency formats are set up in the CURFORMAT table.
Number usage Each formatted currency rule is associated with one number usage. Numbers such as quantities and monetary amounts can be rounded and formatted differently depending on their associated usage. Stores can specify different rounding and formatting rules for the numbers they display according to how they are used, such as a store may round unit prices to four decimal places by specifying the unit price usage, but other currency amounts to two decimal places by specifying the default usage. Number usage is stored in the NUMBRUSG table.
Currency format description A currency format rule can have many currency format descriptions. A currency format description describes how to format (for display purposes) a monetary amount in a particular currency and particular language. Each description is associated with a language in the LANGUAGE table. Currency format descriptions are stored in the CURFMTDESC table.

264

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide


Supported currency A store entity can have many supported currencies. A supported currency is one in which payment is accepted.
Currency conversion rule All currencies have rules governing their conversions to and from other currencies. Each currency conversion rule can be used to convert a price (stored in the database in a particular currency) to an amount customers will be charged in a supported shopping currency.
Counter currency Counter currencies are currency amounts that are displayed along with a supported currency. They cannot be used for purchases but are used for informational purposes. If customers decide to shop in the Euro, they can have the European Monetary Union monetary amounts and other currency amounts displayed in the store. Amounts in the shopping currency are converted to all the counter value currencies for that shopping currency. The counter currencies are paired with a supported currency, such as the Netherlands guilder, and the Euro. Counter currency pairs are stored in the CURCVLIST table. Note: The WebSphere Commerce V5.5 online documentation contains information about each of the data assets contained in the sample stores. Each sample store includes a currency.xml file, which includes the currency information.

Shipping assets in WebSphere Commerce stores Shipping is how a store handles physically delivering goods to customers. In most cases, goods are shipped from a fulfillment center, a separate agency that is responsible for warehousing the store’s goods. In order to offer shipping services, and charge for these services, a store created with WebSphere Commerce should include the following:
At least one shipping mode
At least one shipping calculation code
Jurisdictions and jurisdiction groups Understanding shipping assets in WebSphere Commerce requires an understanding of the concepts defined in the following table:
Shipping modes The shipping mode is a way of shipping goods. More specifically, a shipping mode is the combination of a shipping carrier (which is a company that provides shipping services from a fulfillment center to a customer), and the

Chapter 8. Globalization guidelines

265

shipping service offered by that carrier. A shipping mode belongs to a store entity. If the store entity is deleted, the shipping modes defined within that store entity are also deleted. A store is not required to have a default shipping mode, but it is recommended.
Shipping arrangements A shipping arrangement is an arrangement between the store and the fulfillment center, indicating that a fulfillment center will ship goods for a particular store using specified shipping modes. Certain restrictions can be placed on a shipping arrangement, including the time period for which the shipping arrangement is effective, and the shipping jurisdictions. If a shipping arrangement is associated with a shipping mode, it applies only for that shipping mode. Otherwise, the shipping arrangement applies to all available shipping modes. A shipping arrangement is part of a store and will be deleted if the store is deleted.
Calculation codes Calculation codes are used to calculate shipping charges, that is, a shipping calculation code indicates how shipping charges are calculated for order items. In order to calculate shipping charges on the order item, you must assign shipping calculation codes to either a catalog entry or a group of catalog entries. A calculation code is part of a store entity. A calculation code can only be associated with one store entity, but a store entity may have several calculation codes.
Calculation rules Each calculation code has a set of calculation rules. Shipping charges for an order item may vary depending on the shipping mode, fulfillment center, and which shipping jurisdictions. ShippingJurisdictionGroupCalculationRules are relationship objects that associate shipping calculation rules with jurisdictions, fulfillment centers, and shipping modes, to determine which calculation rules should be used for each order item. If the calculation rule, or any of the other objects referred to by the ShippingJurisdictionGroupCalculationRules, is deleted, the ShippingJurisdictionGroupCalculation rule is also deleted. For more information about the use of shipping rules and calculation codes, see the Store Development Guide, IBM WebSphere Commerce V5.5. Note: The Sample Store Guide, IBM WebSphere Commerce V5.5 product guide contains information about each of the data assets contained in the sample stores.

266

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Tax assets in WebSphere Commerce stores In order to charge and collect taxes on the goods and services your store provides, a store created with WebSphere Commerce must include the following:
Tax categories
Calculation codes
Jurisdictions and jurisdiction groups The combination of the tax categories, calculation codes, and jurisdictions and jurisdiction groups create the tax charges for the store. The following table illustrates the currency structure in the WebSphere Commerce Server and Store:
Tax category Tax categories correspond to the different kinds of tax a store may be required to collect, such as federal, state or provincial, and municipal. A tax category is part of one store entity, although a store entity may have several tax categories. If the store entity is deleted, the tax categories associated with that store entity are also deleted.
Tax type A store typically collects two type of taxes: sales or use tax, and shipping tax. Each tax category has one tax type. Although each tax category may only be of one tax type (for example the tax category federal is a sales tax type), several different tax categories may belong to the same tax type (for example, the tax type sales tax, applies to the categories federal, provincial, and municipal).
Calculation code Calculation codes are used to calculate tax charges, that is, a tax calculation code indicates how tax is calculated for order items. In order to calculate tax on the order item, you must assign sales tax and shipping tax calculation codes to either a catalog entry or a group of catalog entries. Only one tax calculation code of each tax type can be applied to a particular catalog entry or group of catalog entries. Typically, sales or use tax is levied on the net price, and shipping tax is levied on shipping charges. A calculation code is part of a store entity. A calculation code can only be associated with one store entity, but a store entity may have several calculation codes. If the store entity is deleted, the calculation codes associated with that store are also deleted.
Calculation rules Each calculation code has at least one calculation rule, which defines the calculations for each tax category, and specifies the conditions under which the calculations will be done. Each tax calculation rule is associated with a tax category, a jurisdiction group and a fulfillment center, which together define

Chapter 8. Globalization guidelines

267

the conditions under which the calculation rule is used. For example, a different rule may be selected to calculate an amount for a particular tax category depending on the shipping address and fulfillment center specified in the order. Each calculation rule belongs to exactly one calculation code. A particular tax calculation code can have several calculation rules, one for each combination of tax category, tax jurisdiction group, and fulfillment center associated with the store. Each sales tax and shipping tax calculation rule can be associated with multiple TaxJurisdictionGroupCalculationRules (TaxRules). For more detailed information about how to create tax assets for your store, refer to the Store Development Guide, IBM WebSphere Commerce V5.5. Note: When you create a globalized store, we recommend that you create separate XML files for each locale your store supports. The locale-specific file should specify all description information, so it can be easily translated. The sample stores, shipped with WebSphere Commerce, use one tax.xml file for all information that does not need to be translated, and another tax.xml file for each locale the store supports, for the information that needs to be translated. The locale-specific files contain all the description information.

8.6.4 Creating a new display format for WebSphere Commerce A display format (language) allows a single store to sell to a multicultural, multilingual customer base. Each display format can be identified by three factors: a language, a locale and a factor that you can define. You can design your site to display different content to groups that differ on any of these factors. In WebSphere Commerce, your site can define many display formats (languages) that can be used within it. At instance creation, the LANGUAGE table can have 10 supported languages including German, Traditional and Simplified Chinese, Japanese, Korean, Italian, French, Spanish, Brazilian Portuguese, and English. Sites can define additional languages, or dialects of existing languages, to tailor the way information is presented to customers from different cultures or demographics. The language and locale are used to indicate a separate format for Arabic/Egypt in the following example: 1. In a text editor open the following file: \schema\wcs.bootstrap_multi_en_US.xml 2. Copy the file to the following name: \schema\wcs.bootstrap_multi_ar_EG.xml

268

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

Where ar_EG is the locale for Egypt. 3. Change all occurrences of language_id to -11. -11 will be the language ID for Arabic (ar_EG locale). 4. Add the following lines immediately below the line:

For example:

The preceding statement defines the Arabic language and the ar_EG locale as WebSphere Commerce system supported language and locale and assigns language_id=-11 to this display format. (14 zeros)

The preceding statement creates an alternative language for Arabic to be used if data requested in Arabic does not exist in the database.

For example:

The preceding statement adds an English description to the Arabic language to the database.

For example:

The preceding statement adds an Arabic language description to the database using Arabic characters. 5. Save and close the file. 6. Populate the file in the database using the MassLoader. For example: java -Dcom.ibm.wca.logging.configFile=%wcaloggerconfigfile% -Dcom.ibm.wcm.ErrorReporterDir=%errorlogdir% -classpath %CP% %populateschema% -infile %schema%\wcs.bootstrap_multi_ar_EG.xml -dbname %database% -dbuser %user% -dbpwd %password% -dbtype DB2 >> %log%

Chapter 8. Globalization guidelines

269

8.6.5 Adding a new currency to WebSphere Commerce By default, WebSphere Commerce comes populated with many currencies. The list of currencies supported by default are found in \schema\xml\wcs.bootstrap_multi_fr_FR.xml. To add a new currency (not supported by default) to WebSphere Commerce as a site supported currency, do the following: 1. Add your national currency as a site-supported currency: Insert into setcurr (setccurr, setccode, setcexp) values (, , )

For example: insert into setcurr (setccurr, setccode, setcexp) values ('THB', 818, -2)

2. Add a description to your national currency at the site level for at least your language_id. You can add a description to your national currency in as many languages as supported by your system. Insert into setcurrdsc (setccurr, language_id, description) values (, , )

For example: insert into setcurrdsc (setccurr, language_id, description) values ('THB', -1, 'Thai Baht') insert into setcurrdsc (setccurr, language_id, description) values ('THB', -11, 'Thai Baht')

3. Add a currency formatting rule: Insert into curformat (storeent_id, setccurr, roundingmultiple, roundingmethod, decimalplaces) values ( , , , , );

For example: insert into curformat values(-1,'THB',1,-1,'R',0,NULL) insert into curformat values(-1,'THB',1,-4,'R',0,NULL) insert into curformat values(-1,'THB',1,-5,'R',0,NULL)

4. Add a currency formatting description: Insert into curfmtdesc (storeent_id, setccurr, language_id, currencysymbol, customizedcurrstr, currencyprefixpos, currencysuffixpos, displaylocale,

270

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

currencyprefixneg, currencysuffixneg, radixpoint, groupingchar, numberpattern, description) values (-1, 'THB', -11, 'B', null, 'B', null, null, 'B-', null, null, null, '#,##0.00', null)

Note: Refer to the IBM WebSphere Commerce V5.5 online documentation for the schema on the CURFMTDESC table. 5. Add a conversion rule between the store default currency and created currency: Insert into curconvert (storeent_id, fromccurr, tocurr, factor, multiplyordivide, bidirectional, updatable, curconvert_id) values(-1,'USD','THB',’44.62’,'M','Y','Y',-12)

Note: Refer to the IBM WebSphere Commerce V5.5 online documentation for the schema on the CURCONVERT table.

8.6.6 How to add/delete a language/currency for a store archive By default the store archives (SAR) for all business models are packaged with full translation and data support for all of the 10 language (locales) into which WebSphere Commerce is translated. To add a new language/currency to the SAR file, do the following: 1. Unzip the BusinessDirect SAR file to a temporary directory. For example: From: \samplestores\BusinessDirect\BusinessDirect.sar To: D:\SAR-new 2. Add the following line to the end of the D:\SAR-new\WEB-INF\stores\BusinessDirect\data\ForeignKeys.dtd file: "-11">

For example:

3. Copy: From: D:\SAR-new\WEB-INF\stores\BusinessDirect\data\ToolTech\data\en_US To: D:\SAR-new\WEB-INF\stores\BusinessDirect\data\ToolTech\data\

Chapter 8. Globalization guidelines

271

4. Edit the following XML files: ax.xml, store.xml, fullfilment.xml, catalog.xml, businesspolicy.xml, contract.xml, found in the following directory: D:\SAR-new\WEB-INF\stores\BusinessDirect\data\ToolTech\data\ a. Partially translate the (long/short) description field. b. Change every occurrence of en_US to . 5. Edit accesscontrol.xml. a. Partially translate the Displayname and description fields. b. Change every occurrence of en_US to 6. Edit shipping.xml. a. Partially translate the description, field1, and field2 fields. b. Change every occurrence of en_US to . 7. Follow the steps outlined in 8.6.4, “Creating a new display format for WebSphere Commerce” on page 268 to a new display format for your language in WebSphere Commerce (for example, make it a site-supported language). 8. Follow the steps outlined in 8.6.5, “Adding a new currency to WebSphere Commerce” on page 270 to add your national currency to the WebSphere Commerce system if it is not one of the currencies supported by default. 9. Edit currency.xml found in the following directory: D:\SAR-new\WEB-INF\stores\BusinessDirect\data\ToolTech\data a. Add the following line after the last tag:

b. Add the following file at the end of the file:

Where the National Currency Code is the ISO 4217 Alphabetic Currency Code. 10.Edit the store-data-assets.xml file found in the following directory: D:\SAR-new\WEB-INF\stores\BusinessDirect\data Add the following lines after &en_US_fulfillment.xml: &_store.xml; &_fulfillment.xml;

272

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

&_catalog.xml; &_tax.xml; &_shipping.xml; &_businesspolicy.xml;

11.Edit the store-data-assets.dtd file found in the following directory: D:\SAR-new\WEB-INF\stores\BusinessDirect\data Add the following lines at the end of the file: _fulfillment.xml SYSTEM "ToolTech/data//fulfillment.xml"> _store.xml SYSTEM "ToolTech/data//store.xml"> _campaign.xml SYSTEM "ToolTech/data//campaign.xml"> _shipping.xml SYSTEM "ToolTech/data//shipping.xml"> _tax.xml SYSTEM "ToolTech/data//tax.xml"> _catalog.xml SYSTEM "ToolTech/data//catalog.xml"> _offering.xml SYSTEM "ToolTech/data//offering.xml"> _businesspolicy.xml SYSTEM "ToolTech/data//businesspolicy.xml">

12.Create the following properties files for your locale by copying the English and renaming them: – D:\SAR-new\SARINF\properties\publishNLS_.properties – D:\SAR-new\ToolTech\devtools\flow\ui\config_.properties – D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\AddressText_.pr operties – D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\Address_.proper ties – D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\tooltechtext_.pro perties D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\UserRegistrationB2BTe xt_.properties – D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\UserRegistrationB2B_.properties – D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\UserRegistrationText_.properties – D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\UserRegistration_.properties

Chapter 8. Globalization guidelines

273

13.Create the following properties files for your locale by copying the English and renaming, then translate them: – D:\SAR-new\SARINF\properties\publishNLS_.properties – D:\SAR-new\ToolTech\devtools\flow\ui\config_.properties – D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\AddressText_.pr operties – D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\tooltechtext_.pro perties – D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\UserRegistrationB2BText _.properties – D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\UserRegistrationText_.properties 14.Run the Native2ascii tool to convert the files you translated into the ASCII representation of Unicode. This is not required if your language uses the ISO-8859-1 encoding. a. At the command prompt, run native2ascii -encoding :

For example: native2ascii -encoding ISO-8859-6 D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\tooltechtext_ar_EG .properties D:\SAR-new\tooltechtext_.properties.temp

b. Delete D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\tooltechtext_ar_EG .properties c. Copy the temp file D:\SAR-new\tooltechtext_.properties.temp to D:\SAR-new\ToolTech\WEB-INF\classes\ToolTech\tooltechtext_ar_EG .properties. 15.Re-zip your changes into BusinessDirect.sar file and use this modified version when publishing.

8.7 Globalized tools framework As is the case with globalized stores in WebSphere Commerce, all tools pages are enabled for globalization. The globalization enablement of tools pages is accomplished through the use of a set of tools framework’s functions and utilities.

274

WebSphere Commerce V5.5 Handbook Customization and Deployment Guide

All national language-sensitive data is separated into properties files. All messages listed in the WebSphere Commerce documentation use the logging and message subsystem. All other text that is not placed in an ECException object and does not need any additional descriptions (such as field labels) is retrieved using the resource bundle handling classes provided by the tools framework. To allow for easy modification of fields, those classes access PropertyResourceBundle (.properties files) only and turn those bundles into hashtables. Some of the features provided by these classes are:
Auto-reload of .properties file if modified.
XML configuration. To create and use a resource bundle within the tools framework, do the following: 1. Create a properties file and place it in the following directory: commerce/com/ibm/commerce/tools/tools_component_name/properties 2. Add the following line to commerce/properties/tools_component_name/resources.xml:

Where name is the name you want to use to refer to the bundle throughout your code and filename_with_no_extension is the filename for your properties file without the “.properties” extension. The framework contains a set of utility classes to read and write XML and properties files. When reading properties strings, those classes turn the properties files into a hashtable. To use a resource string (from a resource bundle) in your code, follow these steps: 1. Retrieve your properties file with the following command: Hashtable myResource = (Hashtable) com.ibm.commerce.tools.util.ResourceDirectory.lookup(String resourceName, Locale locale)

Where resourceName is namespace.resource_name. 2. Use the following command to retrieve required information from the hashtable: String resource = (String)myResource.get("");

The following is an example of how to retrieve a resource strings to be used in your JSP:

..... ..... .....

Note: As discussed in the encoding section of this chapter, there is a requirement for WebSphere Commerce tools to be encoded in UTF-8. All tools pages (JSPs) include a common file called common.jsp to set some servlet response parameters, among which is: response.setContentType("text/html;charset=UTF-8"); One frequently implemented task in store-related tooling in WebSphere Commerce is the creation of a language selection drop-down list. A selection determines the language, encoding and cultural formatting preference of the user. Figure 8-13 on page 277 shows an example of a language selection drop-down list in the Administration Console. 276 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 8-13 Language selection drop-down list To create a store language selection drop-down list, follow these steps: 1. Include a bean declaration to the StoreLanguageBean by adding the following statement to your JSP: 2. Make a call to the StoreLanguageBean.getStoreJS(storeName,out): The getStoresJS method creates a JavaScript array with all information entitled to the user according to the access control policy. The information includes the stores that the user is entitled to access, the fullfilment centers of those stores, and the languages supported by each of the stores. The following is an example of a JavaScript array created by a call to the getStoresJS method: stores[0] = new Object(); stores[0].storeId = '10001' stores[0].languages = new Array(); Chapter 8. Globalization guidelines 277 stores[0].languages[0] = new Object(); stores[0].languages[0].langId = '-1'; stores[0].languages[0].langDesc = 'United States English'; stores[0].languages[1] = new Object(); stores[0].languages[1].langId = '-3'; stores[0].languages[1].langDesc = 'German'; stores[0].languages[2] = new Object(); stores[0].languages[2].langId = '-5'; stores[0].languages[2].langDesc = 'Spanish'; stores[0].languages[3] = new Object(); stores[0].languages[3].langId = '-2'; stores[0].languages[3].langDesc = 'French'; stores[0].languages[4] = new Object(); stores[0].languages[4].langId = '-4'; stores[0].languages[4].langDesc = 'Italian'; stores[0].languages[5] = new Object(); stores[0].languages[5].langId = '-10'; stores[0].languages[5].langDesc = 'Japanese'; stores[0].languages[6] = new Object(); stores[0].languages[6].langId = '-9'; stores[0].languages[6].langDesc = 'Korean'; stores[0].languages[7] = new Object(); stores[0].languages[7].langId = '-6'; stores[0].languages[7].langDesc = 'Brazilian Portuguese'; stores[0].languages[8] = new Object(); stores[0].languages[8].langId = '-7'; stores[0].languages[8].langDesc = 'Simplified Chinese'; stores[0].languages[9] = new Object(); stores[0].languages[9].langId = '-8'; stores[0].languages[9].langDesc = 'Traditional Chinese'; 3. Use the language data contained in the JavaScript array retrieved by the StoreLanguageBean.getStoreJS(storeName,out) to construct the drop-down list: function getLanguageList() { var selectObj = document.all['langlb']; selectObj.innerHTML = ''; firstTime = false; if (selectedStore == '') { selectedStore = document.f1.storelb.selectedIndex; firstTime = true; } if (stores.length > 0) { for (var x=0; x Customer (Information) Any content that the user requests to see or that is needed to complete the customer request. Relatively large amount of information including graphical content. 24x7 ITSO Site -> Production Unit (Control) Request for product, category and article information. N/A 24x7 Production Unit -> ITSO Site (Information) Product, category and article information. Relatively large amount of data including images 24x7 ITSO Site -> Fulfilment Center (Control) Request for order, status, stock information and previous order information. N/A 24x7 Fulfillment Services-> ITSO Site (Information) Order status, stock information, previous order information. Relatively small amount of data 24x7 Flow (type) Information or Control Customer -> ITSO Site (Control) WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Volume information Availability* Request to check customer creditability or charge customer credit card. N/A 24x7 Credit information (yes/no). Small amount of data 24x7 Flow (type) Information or Control ITSO Site -> Payment Services (Control) Payment Services -> ITSO Site (Information) * For the purpose of this book we assume the availability of 24x7, but we are not providing an exact solution needed to achieve this requirement. 9.2.4 Use case model This section describes the functional requirements of the ITSO site represented by the use case model. The use case model actors are displayed in Figure 9-3 on page 302 in graphical form to show the use with the system. The descriptions of the use cases are from the actor’s point of view; they do not describe how the system works internally or tis internal structure or mechanisms. We have categorized the use cases for the ITSO site by shopper and administrator (site administrator, line-of-business user). Actors defined The actors are people or systems outside of the WebSphere Commerce server that interact with the system (ITSO site). This section identifies the primary and secondary actors. A primary actor is one that initiate a use case and a secondary actor is one that is involved in one or more of the steps in the use case but does not initiate it. Figure 9-3 on page 302 depicts actors modeled for ITSO site. Chapter 9. Requirements analysis and solution design 301 Payment ITSO Production Fulfillment Service Service Unit Actors Customer Site Administrator Customer Service Representative Product Data Manager Developer Line-of-business user Retail Business Business Customer Customer Resellers Customer Figure 9-3 ITSO site actors Primary actors The primary actors for the ITSO site are as follows: Customer Site Administrator Customer Service Representative (CSR) Product Data Manager Developer Line-of-business user Secondary actors The secondary actors for the ITSO site are as follows: ITSO Production Unit Fulfilment Services Payment Services Customer Site administrator Line-of-business user Use cases summary This section lists the use cases, describes the goal of the use case, and shows the primary actors. 302 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide A summary of the shopper/system use cases can be found in Table 9-3. Table 9-3 Shopper/system use case summary Use case ID Use case name Primary actor Requirement UC-PW01 Display price watch list Customer REQ02 UC-PW02 Add items to price watch list Customer REQ02 UC-PW03 Delete item from price watch list Customer REQ02 UC-PW04 Delete all items from price watch list Customer REQ02 UC-PW05 Schedule job checks price watch list and e-mail customers System (scheduler) REQ02 A summary of the administration use cases can be found in Table 9-4. Table 9-4 Administration use case summary Use case ID Use case name Primary actor UC-A01 Create a contract for a business site administrator line-of-business user Requiremen t REQ01 UC-A03 Add a category Product data manager REQ03 UC-A04 Add a product Product data manager REQ03 UC-A05 Generate commerce analytics reports Line-of-business user REQ04 UC-A06 Register customers from external system via MQ. System REQ05 UC-A07 Notify customer via e-mail of an event. System (scheduler) REQ06 Use cases detail This section provides detail for each of the use cases defined for the shopper/system and administration. Chapter 9. Requirements analysis and solution design 303 Table 9-5 UC-PW01: Display the price watch list Use Case ID: name UC-PW01 Description Customer wishes to view a list of items that he currently has a price watch on. Precondition Customer is a registered user. Customer has logged on to the site. Primary actor Customer Secondary actor N/A Main Scenario 1. Customer clicks the price watch option from the header menu on the site. 2. The price watch list page is displayed to the customer. The price watch items are shown in a table containing the following column headings: – – – – Item SKU Item description Item price Price watch price Alternatives (Alternative Step 2): If the customer has no items in his price watch list, a message informing him of this is displayed. Solution chapter Chapter 13, “Customize a store: Price Watch example” on page 393 Table 9-6 UC-PW02: Add an item to the price watch list Use Case ID: name UC-PW02 Description Customer wishes to add a price watch for a specific item. Precondition Customer has navigated to the item display page of the item he wishes to create a price watch for. Primary actor Customer Secondary actor N/A Main Scenario 1. Customer enters the desired price into the price watch text box. 2. Customer clicks the Add Price Watch button. 3. A new price watch is created for the item with the specified price. 4. The price watch list page is displayed to the customer. 304 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Use Case ID: name UC-PW02 Alternatives (Alternative Step 3): If a price watch already exists for the item, the price watch price value is overwritten with the new value specified. Solution chapter Chapter 13, “Customize a store: Price Watch example” on page 393 Table 9-7 UC-PW03: Delete an item from the price watch list Use Case ID: name UC-PW03 Description Customer wishes to delete a price watch for a specific item. Precondition Customer has navigated to the price watch list page; see Table 9-5 on page 304. User has added at least one item to his price watch list; see Table 9-6 on page 304 Primary actor Customer Secondary actor N/A Main Scenario 1. Customer clicks the Delete option next to the price watch item in the table. 2. The item is deleted and the price watch list page is displayed to the customer. Alternatives N/A Solution chapter Chapter 13, “Customize a store: Price Watch example” on page 393 Table 9-8 UC-PW04: Delete all items from the price watch list Use Case ID: name UC-PW04 Description Customer wishes to delete all items in his price watch list. Precondition Customer has navigated to the price watch list page; see Table 9-5 on page 304. User has added at least one item to his price watch list; see Table 9-6 on page 304 Primary actor Customer Secondary actor N/A Main Scenario 1. Customer clicks the Delete All option. 2. All items are deleted and the price watch list page is displayed to the customer with the message that there are no price watch items in the list. Chapter 9. Requirements analysis and solution design 305 Use Case ID: name UC-PW04 Alternatives N/A Solution chapter Chapter 13, “Customize a store: Price Watch example” on page 393 Table 9-9 UC-PW05: Scheduled job checks price watch list and e-mails customers Use Case ID: name UC-PW05 Description Price watch list is checked for any new items that are within the price watch price and e-mails the customer to inform them. Precondition Scheduler is configured to execute the job and is active. Primary actor WebSphere Commerce Scheduler Secondary actor Customer Main Scenario 1. Items in the Store’s price watch list are evaluated in turn. 2. A notification e-mail is sent to the associated customer for an item that has a price watch price greater than or equal too the item’s actual price. 3. The price watch item is removed from the list if an e-mail was sent. Alternatives (Alternative Step 2): If there are no items in the price watch list, do nothing. Solution chapter Chapter 13, “Customize a store: Price Watch example” on page 393 Table 9-10 UC-A01: Create a contract for a business 306 Use Case ID: name UC-A01 Description Create a contract that defines specific items, prices and terms between a business direct customer and the ITSO store. Precondition ITSO store is deployed Primary actor Line-of-business user Secondary actor Customer WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Use Case ID: name UC-A01 Main Scenario 1. The line-of-business and customer negotiate a contract for specific items and terms with Seller administrator. 2. Create organizations. 3. Create business accounts 4. Create contract. Alternatives The Loader Package can be used via the command line to load the contract.xml or include the file within the store archive and republish the store archive. Solution chapter Chapter 15, “Manage the ITSO store” on page 527 Table 9-11 UC-A02: Add a category Use Case ID: name UC-A02 Description Add a new category to the catalog using the Accelerator Product Management tool GUI. Precondition ITSO store is deployed. Primary actor Product data manager Secondary actor Site administrator Main Scenario The product data manager will use the Accelerator Product Management tooling to add a new product. 1. Log on to the Accelerator 2. Add a new product using the product management tooling. Alternatives Add product using the Loader Package defined in a WebSphere Commerce XML data file. Solution chapter Chapter 15, “Manage the ITSO store” on page 527 Table 9-12 UC-A03: Add a product Use Case ID: name UC-A03 Description Add a new product to the catalog using the Accelerator Product Management tool GUI. Precondition ITSO store is deployed. Primary actor Product data manager Secondary actor Site administrator Chapter 9. Requirements analysis and solution design 307 Use Case ID: name UC-A03 Main Scenario The product data manager will use the Accelerator Product Management tooling to add a new product. 1. Log on to the Accelerator 2. Add a new product using the product management tooling. Alternatives Add product using the Loader Package defined in a WebSphere Commerce XML data file. Solution chapter 15.1.2, “Add a product” on page 528 Table 9-13 UC-A04: Generate commerce analytics reports Use Case ID: name UC-A04 Description Generate commerce analytics reports to show trends in shopping transactions. The customized report will list users who have placed the most orders on the site. Precondition ITSO store is deployed WebSphere Commerce Analyzer is deployed as described in Chapter 20, “Commerce analytics” on page 787. Primary actor Line-of-business user Secondary actor N/A Main Scenario 1. Log on to the Accelerator 2. Access the predefined or customized business intelligence reports. Alternatives N/A Solution chapter Chapter 20, “Commerce analytics” on page 787 Table 9-14 UC-A05: Register customers from external system using MQ 308 Use Case ID: name UC-A05 Description Register a customer from an external system using MQ by sending an inbound XML message containing the customer information and executing the UserRegistrationAdd controller command. WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Use Case ID: name UC-A05 Precondition ITSO store is deployed. WebSphere Commerce and WebSphere MQ have been configured as described in Chapter 21, “Messaging integration with MQ and e-mail” on page 883. Primary actor System Site administrator Secondary actor Customer Main Scenario 1. First the inbound message is sent from an external system to the WebSphere MQ inbound serial queue (wc_inbound_ser). 2. The WebSphere Commerce MQ listener is listening for messages in the queues via the JMS objects. The MQ listener sends the message to the adapter manager. 3. The adapter manager analyzes the contents of the message to determine the appropriate adapter to send the request. In the case of MQ, the message is sent to the program adapter. 4. When an inbound message is received by the program adapter, the program adapter invokes the XML parser. The XML parser parses the XML message using the sys_template.xml or user_template.xml, to identify the controller command to be called and the mapping of message elements to command parameters. If the message is not found, an error is generated and returned to the MQ listener. The MQ listener puts the error in the WebSphere MQ wc_error queue via the JMSErrorQueue object. 5. Once the message has been parsed and mapped and the proper command and parameters are available to be executed, the program adapter passes the command name and command parameters to the Web controller. 6. The Web controller starts the transaction and executes the command. The controller command will execute business logic by invoking various tasks commands and business logic which update the instance database. 7. If successful, the Web controller commits the transaction and returns. 8. Customer is registered and can now log on. Chapter 9. Requirements analysis and solution design 309 Use Case ID: name UC-A05 Alternatives Register a customer using the online registration available from the store, or by a CSR using the Organization Administration Console. Solution chapter 21.6, “Scenario: add new inbound message for MQ” on page 936 Table 9-15 UC-A06: Notify users via e-mail that an event has occurred Use Case ID: name UC-A06 Description Notify users via e-mail that an event has occurred within WebSphere Commerce such as a password reset or order approved confirmation. Precondition Primary actor Customer Secondary actor System Main Scenario Upon an event such as a password reset, an e-mail is sent to the user or administrator alerting them of the event. Alternatives N/A Solution chapter 21.7, “Scenario: e-mail notification” on page 950 ITSO store is deployed e-mail messaging is enabled and message type is defined. Refer to 21.7, “Scenario: e-mail notification” on page 950 for details. 9.3 Solution design This section provides an overview of the technical solution and its benefits for the ITSO site scenario, and includes the following: Systems architecture Component model ITSO store navigation ITSO store catalog hierarchy ITSO store organizational hierarchy 9.3.1 Systems architecture The architecture overview diagram represents the governing ideas and candidate building blocks of an ITSO site system. It provides an overview of the 310 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide main conceptual elements and relationships in an architecture, including nodes, connections, data stores, users, and external systems. The main purpose of the architecture overview diagram is to explain the target IT system by providing a conceptual view of the components and operational environment as seen in Figure 9-4. DMZ Outside world Internal network WebSphere Commerce 5.5 BE + Fixpack 2 WebSphere Commerce Payments 5.5 WebSphere Application Server V5 + Fixpack 2 DB2 8.1 UDB Client + Fixpack 2 WebSphere MQ 5.3.1 (bindings mode) JavaMail 1.2 Windows 2000 Server + SP4 User I N T E R N E T 80/443 80/443 Web Server Web node Server (webwin1) IBM HTTP Server 1.3.26 WebSphere V5 plugin + Fixes Windows 2000 Server + SP4 Domain Firewall Domain Name Server Protocol Firewall Public Key Infrastructure WebSphere Commerce node (wcwin1) WebSphere Commerce Analyzer node WebSphere Commerce Analyzer 5.5 DB2 Intelligent Miner for Data 8.1.1 DB2 UDB 8.1 Enterprise Server Edition + Fixpack 1 + Fixes Windows 2000 Server + SP4 DB2 UDB 8.1 Enterprise Server Edition + Fixpack 2 Windows 2000 Server + SP4 DB2 Server node (db2win1) WC instance database WC Payments database Back-end Systems James 2.1.3 (e-mail) Procurement Fullfilment Payment External System(s) Figure 9-4 ITSO site system diagram System architecture implementation The implementation procedures for the ITSO site system architecture depicted in Figure 9-4 can be found in several chapters in this redbook. The ITSO sample store can be deployed on any supported platform and topology. To illustrate a production-like environment, we chose the configuration seen in Figure 9-4 on the Windows platform. For testing purposes, all nodes and components can be installed on the same node, with the exception of the WebSphere Commerce Analyzer. Chapter 9. Requirements analysis and solution design 311 For details on how to implement the system architecture for the ITSO working example, refer to the following: Web Server node For details on the Windows platform, refer to 16.4, “Add remote Web Server node” on page 587. WebSphere Commerce node For details on the Windows platform, refer to 16.2, “Single-tier implementation” on page 559. DB2 Server node For details on the Windows platform, refer to 16.3, “Add a remote Database Server node” on page 582. WebSphere Commerce Analyzer node For details on the Windows platform, refer to Chapter 20, “Commerce analytics” on page 787. Integrating WebSphere MQ with WebSphere Commerce For details on the Windows platform, refer to Chapter 21, “Messaging integration with MQ and e-mail” on page 883. Integrating e-mail with WebSphere Commerce For details on the Windows platform, refer to Chapter 21.7, “Scenario: e-mail notification” on page 950. 9.3.2 Component model The component model describes the ITSO site's entire hierarchy of components and briefly defines their responsibilities. Note: A component is a relatively independent part of an information technology (IT) system. It is characterized by its responsibilities and eventually by the interface(s) it offers. Components can be decomposed into smaller components or composed into larger components. Most components are software, although some may be hardware. Some components may already exist within the IT system, but it may be necessary to build or buy others. Component relationship diagram Figure 9-5 on page 313 outlines the component model for ITSO site in four layers: 1. The channel control layer contains channel-specific components responsible for a certain view of the system and certain protocols. 312 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 2. The presentation control layer contains components responsible for controlling a specific use case. A presentation component acts as a controller in executing a use case. This means that the presentation component will keep track of the use case flow (step logic), keep track of the current state, and present adequate views to interact with the user. To perform business operations, the component will call upon components in the business services layer. 3. Business services are responsible for all ITSO business logic provided by different WebSphere Commerce subsystems. 4. The back-end integration layer contains components that act as wrappers to ITSO back-end systems. The technical components layer provides functionality that is required but it is not a part of the core business processes, for example, database or content management. Channel Control Presentation Control Back-end Integration Login HTTP Request Servlet Web Controller Business Services Register/Update User Information Browse ITSO Site Shop MQ Listener Member Services Catalog Services Product Import Order Services Order Fulfillment Get Order Status Technical components Content Mgmt. Payment Database Figure 9-5 ITSO site components Component descriptions The component descriptions are as follows: 1. HTTP request servlet The HTTP request servlet handles incoming HTTP requests passed on from the servlet engine. 2. MQ listener The MQ listener is a protocol listener that listens for messages from the JMS objects (queues) defined for WebSphere MQ, and then dispatches the requests to the program adapter. The program adapter uses the XML parser Chapter 9. Requirements analysis and solution design 313 and template mapping files to parse the message elements, map the elements to command parameters, and pass them with the identified command to the Web controller. 3. Web controller The Web controller provides the presentation component with services such as session management, transaction control, access control, and authentication. The controller is also responsible for dispatching the appropriate presentation components depending on the request. 4. Login This component is responsible for the login presentation logic. It can cover the presentation of use cases such as login, forgotten password or post-login page customization. 5. Registration/customer information update This component handles the registration and customer information update presentation logic. It can cover the presentation of use cases such as registering new customers or updating customer profiles. 6. Browse ITSO site This component is responsible for the ITSO site catalog presentation logic. 7. Shop This is the core commerce component that allows all customers to buy items from the ITSO catalog. This component can be responsible for the use cases of adding an item to a shopping basket, placing an order, canceling an order, etc. 8. Get Order Status This component allows customers to retrieve the status of placed orders. 9. Member Services Member Services cover all business logic for login, registration, customer user profile updates, and logoff. 10.Catalog Services This component provides the online catalog navigation, merchandising features, interest lists, and search capabilities. 11.Order Services Order Services provide shopping carts, order processing, and order management function support. 314 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 12.Product Import This ITSO site component is the main focus of this book. The Product import component is responsible for: a. Importing product data from a back-end system. b. Transformation of data using the Loader Package Transformation Tool. c. Loading data to the staging server using the Loader Package MassLoad tool. d. Propagating data to the production server using WebSphere Commerce Staging Server utilities. 13.Order fulfillment Order fulfillment does a routing of all orders placed to the ITSO fulfillment services. 14.Payment Payment is an interface to the ITSO payment services. 15.Content management This component is responsible for managing all content for the ITSO site that is not dynamically generated from data stored in the WebSphere Commerce database. The content management component can be divided into several internal subcomponents that only interact within the content management component. These subcomponents are: – – – – – – – Workflow Data Capture Templating Presentation Templating Deployment Virtualization Navigation/Site Mapping Link Tool 16.Database The database contains all data that the ITSO site needs for operation. This includes the complete set of products and categories as well as user profile information. 9.3.3 ITSO store navigation Figure 9-6 on page 316 displays the ITSO store navigation. The site navigation is virtually the same as the Business Direct (ToolTech) sample we used to create the ITSO store. In Chapter 12, “Create a store” on page 341, we modify the store front assets for look and feel. In Chapter 13, “Customize a store: Price Watch example” on page 393, we add a page for price watch. Chapter 9. Requirements analysis and solution design 315 Logon page Forgot password Forgot password page Login Register Login Registration Page Home page Collaborative Home workspaces* Catalog Account Collaborative workspaces page* Main category display page Account page View members Select a sub-category Collaborative workspaces members page Requisition list page Select a requisition list Your order page Order status Order status page Log off Logon page Create a requisition list Edit requisition list page Sub-category page Select a product Requisition list Current order Update quantity Product display page RFQ list Advanced search Advanced search page Quick order Enter more items Search results Quick order page Product display page Your order page Place order Your order page Select an item Item display page Add to RFQ Add to order Add to requisition list New Existing New Create RFQ page Add to RFQ list page New requisition list page Existing Add to requisition list page Legend These pages can be accessed from any page in the site. * The collaborative workspaces link can only be seen if the feature is enabled. Figure 9-6 IITSO store navigation 316 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 9.3.4 ITSO store catalog hierarchy The ITSO sells two product types, software and books. The ITSO has decided that they would like the catalog hierarchy organized by brand. Figure 9-7 depicts the ITSO catalog hierarchy for categories and products. Category Sub category Product ITSO Master Catalog Item Software Redbooks WebSphere WebSphere Redbook products PDF item DB2 Tivoli DB2 Redbook products Tivoli Redbook products Hardcopy PDF item item Hardcopy PDF item item Lotus Lotus Redbook products Hardcopy PDF item item Hardcopy item WebSphere DB2 Tivoli Lotus WebSphere software products DB2 software products Tivoli software products Lotus software products Zip item Zip item Zip item Zip item CD item CD item CD item CD item Figure 9-7 ITSO store catalog hierarchy for categories and products by brand 9.3.5 ITSO store organizational hierarchy Figure 9-8 on page 318 displays the ITSO store organizational structure. For more detailed information refer to Chapter 15, “Manage the ITSO store” on page 527. Chapter 9. Requirements analysis and solution design 317 Root Organization Site Administrators Default Organization Seller Organization Seller Seller Administrators Adm inistrators Buyer A Organization Buyer B Organization Buyer Buyer Administrators Administrators B 2B Organization Buyer Organization BigCo Buyer Organization EduCo B uyer Organization Figure 9-8 ITSO organizational structure 318 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 10 Chapter 10. ITSO sample code This chapter provides a description of the ITSO sample code developed for the ITSO B2B working example. In addition, we explain where to download the ITSO sample code zip file and how to configure the scripts provided. © Copyright IBM Corp. 2003. All rights reserved. 319 10.1 Description of sample code The sample code and configuration files developed for the ITSO B2B working example and other chapters can be found in the 6969code.zip file. The ITSO sample code 6969code.zip can be downloaded at: ftp://www.redbooks.ibm.com/redbooks/SG246969 Unzip the contents of the Web material zip file. For example, after unzipping the 6969code.zip, you will have the c:\6969code directory. Table 0-1 Redbook sample code contents File name or directory Description c:\6969code Root directory of redbook samples. c:\6969code\build\SARFile * Contains build.xml Ant script used to package the SAR with store front and data assets. * For details refer to Chapter 12, “Create a store” on page 341. c:\6969code\build\DeployTool * The DeployTool is used to build Java application assets (commands and EJBs), package them to a JAR file, and deploy the JAR file to the WebSphere Commerce runtime environment. * For details refer to Chapter 12, “Create a store” on page 341. c:\6969code\pricewatch * Price watch customization sample Java source code files. * For details refer to Chapter 13, “Customize a store: Price Watch example” on page 393. c:\6969code\sar * ITSO.sar (full working SAR for ITSO sample) * For details refer to Chapter 12, “Create a store” on page 341. c:\6969code\catdata * Development test catalog data for ITSO sample * Pruned catalog data * For details refer to Chapter 12, “Create a store” on page 341. c:\6969code\storexml * Contains ITSO modified XML files found in ITSO.sar. c:\6969code\scripts Scripts used to automate tasks such as server startup, JSP pre-compile, etc. c:\6969code\wca * WebSphere Commerce Analyzer custom report sample. * For details refer to Chapter 20, “Commerce analytics” on page 787. c:\6969code\mq * MQ messaging sample message customization files. * For details refer to Chapter 21, “Messaging integration with MQ and e-mail” on page 883. 320 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 10.2 Prepare DeployTool files After downloading and unpacking the ITSO sample code zip file (6969code.zip), you will need to manually copy some files from the WebSphere Commerce and WebSphere Application Server runtime and WebSphere Commerce Studio to the DeployTool directory for the DeployTool to work properly. The DeployTool is used in Chapter 14, “Build and deployment” on page 505. Note: DeployTool The DeployTool is used to build Java application assets (commands and EJBs) and package them to a JAR, and is used to deploy the JAR file to the WebSphere Commerce runtime environment. The DeployTool included in the ITSO sample code zip file was supplied by the IBM Electronic Commerce development organization. New versions of the DeployTool will be made available in the future via the IBM WebSphere Commerce Support page. 10.2.1 Copy WebSphere Commerce files Copy the following files from the \installedApps\\WC_.ear of a WebSphere Commerce instance (WebSphere Commerce node) to the c:\6969code\build\DeployTool\buildjars directory: Catalog-ProductManagementData.jar Catalog-ProductManagementLogic.jar Enablement-BaseComponentsData.jar Enablement-BaseComponentsLogic.jar Enablement-IntegrationData.jar Enablement-IntegrationLogic.jar Enablement-RelationshipManagementData.jar Enablement-RelationshipManagementLogic.jar Marketing-CampaignsAndScenarioMarketingData.jar Marketing-CampaignsAndScenarioMarketingLogic.jar Marketing-CustomerProfilingAndSegmentationData.jar Marketing-CustomerProfilingAndSegmentationLogic.jar Member-MemberManagementData.jar Member-MemberManagementLogic.jar Merchandising-PromotionsAndDiscountsData.jar Merchandising-PromotionsAndDiscountsLogic.jar Order-OrderCaptureData.jar Order-OrderCaptureLogic.jar Chapter 10. ITSO sample code 321 Order-OrderManagementData.jar Order-OrderManagementLogic.jar Trading-AuctionsAndRFQsData.jar Trading-AuctionsAndRFQsLogic.jar 10.2.2 Copy WebSphere Application Server files Copy the following files from the \lib directory to the c:\6969\code\build\DeployTool\wasjars directory: appprofile.jar distexcep.jar dynacache.jar ecutils.jar ejbcontainer.jar ejbportable.jar ivjejb35.jar j2ee.jar ras.jar runtime.jar runtimefw.jar vaprt.jar wsexception.jar 10.2.3 Copy WebSphere Commerce Studio files Copy the following file from the \Commerce\lib directory to the c:\6969\code\build\DeployTool\tools directory: Utilities.jar Copy the following files from and to the following directories: as400.mapping oracle.mapping From: \Commerce\properties\com\ibm\commerce\metadata\conv ersion To: c:\6969\code\build\DeployTool\tools 322 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 11 Chapter 11. Implement a team development environment When developing software in teams, it is especially important to have a proper system for software configuration management (SCM) and a controlled build environment. This chapter describes how to implement the solution components of the Build and SCM node, Development node, and Development Integration Test node within ITSO team development environment. The chapter is organized into the following sections: Team development environment scenario Build and SCM node implementation Development node implementation Development Integration Test node implementation © Copyright IBM Corp. 2003. All rights reserved. 323 11.1 Team development environment scenario To create the development artifacts for the ITSO working example, we set up a controlled build environment that included software configuration management (SCM). The ITSO team development environment consisted of three primary node types: Build and SCM node, Development node, and Development node (1-to-n), as seen in Figure 11-1. There are several alternatives that are not depicted in Figure 11-1, such as a shared database server, shared WebSphere Commerce instance database, and shared remote WebSphere Commerce Payments node. WebSphere Commerce 5.5.0.2 BE WebSphere Commerce Payments 5.5 WebSphere Application Server 5.0.1 IBM HTTP Server 1.3.26.2 DB2 UDB V8.1 ESE + Fixpack 3 Microsoft Internet Explorer 6 + SP1 Windows 2000 Server + SP4 VMWare Workstation 4 Development Integration Test node (wc55be) Development node Deploy Concurrent Versions System for NT 2.0.4 Server WebSphere Commerce Studio 5.5 BDE + FP2 WebSphere Studio Application Developer 5.0.1 DB2 UDB V8.1 + Fixpack 3 WebSphere Commerce build scripts Microsoft Internet Explorer 6 + SP1 Windows 2000 Server + SP4 Build and SCM node (wcbuild) Development node WebSphere Commerce Studio 5.5.0.2 BDE WebSphere Studio Application Developer 5.0.1 Concurrent Versions System client plugin for WSAD DB2 UDB V8.1 ESE + Fixpack 3 Microsoft Internet Explorer 6 + SP1 Windows 2000 Server + SP4 Development node Figure 11-1 ITSO team development environment Build and SCM node The Build and SCM node includes the Concurrent Version System (CVS) Server, WebSphere Commerce Studio, and the build scripts. It has two primary functions: CVS Server and repository for ITSO development assets, and a build server to extract source code from CVS and execute a headless WebSphere Commerce build (WebSphere Commerce Studio workbench not required). The 324 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Build and SCM node is managed by the development lead or on very large projects, a designated build person or team. It is desirable to have WebSphere Commerce Studio on the Build and SCM node for several reasons. First, the Java tools and required classes will be present to compile the Java assets developed. Second, WebSphere Studio Application Developer offers a source level debug test facility within the WebSphere Test Environment. Third, although we will demonstrate how to perform a headless build, it is beneficial to have a common method of extracting CVS as on the Development node if a manual procedure is needed. Finally, on smaller teams, the Build and SCM node may be the lead developer’s system where the CVS environment is seeded with the development assets. Table 11-1 lists the software and versions used on the Build and SCM node within the ITSO team development environment. Table 11-1 Build and SCM node software components Software Version Microsoft Windows 2000 Server Service Pack 4 Microsoft Internet Explorer 6.0 + Service Pack 1 Concurrent Versions System for NT (CVSNT) Note: Works on Windows NT® and Windows 2000 2.0.4 WebSphere Commerce Studio, Business Developers Edition 5.5.0.2 (5.5 + Fix Pack 2) WebSphere Studio Application Developer 5.0.1 (5.0 + PTF 1) IBM DB2 UDB Enterprise Server Edition 8.1.3.132 (8.1 + Fix Pack 3) WebSphere Commerce build scripts Note: Supplied with ITSO sample code N/A Development node The Development node includes WebSphere Commerce Studio, and a CVS client plug-in for WebSphere Studio Application Developer. Developers will interact with the CVS Server via the CVS client to manage source code (commit, update, etc.). Table 11-2 on page 326 lists the software and versions used on the Development node within the ITSO team development environment. Chapter 11. Implement a team development environment 325 Table 11-2 Development node software components Software Version Microsoft Windows 2000 Server Service Pack 4 Microsoft Internet Explorer 6.0 + Service Pack 1 WebSphere Commerce Studio, Business Developer Edition 5.5.0.2 (5.5 + Fix Pack 2) WebSphere Studio Application Developer 5.0.1 (5.0 + PTF 1) Concurrent Versions System for Windows Client plug-in for WebSphere Studio Application Developer N/A IBM DB2 UDB Enterprise Server Edition 8.1.3.132 (8.1 + Fix Pack 3) Development Integration Test node The Development Integration Test node is a fully working WebSphere Commerce V5.5 runtime environment, including IBM HTTP Server, DB2, WebSphere Application Server, WebSphere Commerce, and WebSphere Commerce Payments. The Development Integration Test node is used by the ITSO development team to verify the integration of code from multiple developers. 326 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: On large development projects, there are often several types of tests performed on a build. The type of testing we focused on while developing the ITSO store is limited to the development unit test and integration test. For example: Unit Test: Each developer will unit test the code being developed within his or her own WebSphere Commerce Studio workspace. Development Integration Test: This involves integrating and testing code from multiple developers on a common team development test node. Build Verification Test (BVT): After the build has compiled and packaged, a basic suite of tests are run to verify that the application is working properly. This is done to establish a basic quality level of the build prior to more extensive testing is done. Function Verification Test (FVT): This type of testing is performed to verify specific functionality within the newly developed code. This type of testing is done typically early in the testing cycle in preparation for system testing or integration testing. System Verification Test (SVT): This type of testing includes integration and full testing of the application. Customer Acceptance Test (CAT): After the application has been approved for deployment by the SVT team, the application is now ready to be tested and eventually approved by the customer before going live. When constructing a Development Integration Test node, there are several things to consider. First, you may have daily builds and will need an environment that can be reset to a known state before deploying the new build. Second, the Development Integration Test node should be consistent from one build to the next. Finally, the setup of the Development Integration Test node should be quick and easy. For the reasons stated, we recommend using a product such as Ghost or VMware to quickly reload a clean WebSphere Commerce runtime environment to verify new builds. For the ITSO team development environment, VMware V4 Workstation Edition offered an ideal solution for the Development Integration Test node. We constructed a VMware image with Windows 2000 Server, IBM WebSphere Commerce V5.5, Business Edition + Fix Pack 2, WebSphere Application Server V5 + Fix Pack 1 + Fixes, DB2 UDB V8.1 + Fix Pack 3, and a newly created WebSphere Commerce instance, and WebSphere Commerce Payments database. We refer to this as the perfect image of WebSphere Commerce. After we created the perfect VMware WebSphere Commerce image, we created a backup of the VMware image (zip file), and used the backup of the image as a starting point to verify the new builds. Chapter 11. Implement a team development environment 327 Table 11-3 lists the software and versions used on the Development Integration Test node within the ITSO team development environment. Table 11-3 Development Integration Test node software components Software Version VMware Workstation for Windows 4 Microsoft Windows 2000 Server Service Pack 4 Microsoft Internet Explorer 6.0 + Service Pack 1 IBM HTTP Server 1.3.26.2 (1.3.26 + WAS 5 FP1) IBM WebSphere Application Server 5.0.1 (5.0 + FP1 + Fixes) IBM DB2 UDB Enterprise Edition 8.1.3.132 (8.1 + Fix Pack 3) IBM WebSphere Commerce Business Edition * includes IBM WebSphere Commerce Payments 5.5.0.2 (5.5 + Fix Pack 2) 11.2 Build and SCM node implementation This section describes how to implement the Build and SCM node used within the ITSO team development environment. This section is organized as follows: CVS overview CVSNT Server implementation WebSphere Commerce Studio installation Publish store archive within WebSphere Test Environment CVS client configuration The primary development environment component of WebSphere Commerce Studio is WebSphere Studio Application Developer. WebSphere Studio Application Developer is a file-based integrated development environment (IDE). In most cases, developers do not work alone, but rather as part of a team. The open architecture of WebSphere Studio Application Developer V5 allows software configuration management (SCM) systems to be integrated through the use of a plug-in. WebSphere Studio Application Developer includes SCM plug-ins for Concurrent Version System (CVS) and Rational ClearCase® LT. Both SCM plug-ins are installed with the default WebSphere Studio Application Developer installation. The SCM server products are not installed by WebSphere 328 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Studio Application Developer. The built-in CVS client support includes CVS Team Provider Core 2.0.0, CVS SSH Core 2.0.0 and CVS Team Provider UI 2.0.1 plug-ins. Rational ClearCase LT is the bundled SCM server included with WebSphere Studio Application Developer. The CVS Server is available for download on several platforms, including AIX, Linux and Windows. Within IBM, there is also an SCM plug-in for CMVC, which is an IBM internal SCM tool used by the IBM software development community. CMVC is a very powerful SCM tool, but is no longer available as a product for sale outside of IBM. In the remainder of this section, we will focus our attention on CVS. 11.2.1 CVS overview Concurrent Version System (CVS) is a simple open-source software configuration management (SCM) system. CVS offers version control for parallel development, but does not offer many of the advanced features included with a product, such as Rational ClearCase. We selected CVS for the ITSO example for several reasons. First, we wanted to use a SCM tool that people could easily download for free. Second, we wanted to keep the software configuration management within this redbook at a basic level so that it would not detract too much from the core WebSphere Commerce development. Finally, CVS is relatively easy to use and many people are already familiar with how to install, configure and use it. Some of the main features of CVS are as follows: Multiple client/server protocols over TCP/IP that let developers access the latest code from a wide variety of clients from virtually any location with an Internet connection. Note: WebSphere Studio Application Developer supports two communication protocols: pserver (password server) and ssh. The default is pserver. The other protocol has to be manually configured by selecting Window -> Preferences -> Team -> CVS -> Ext Connection Method. It stores all the versions of a file in a single file using forward-delta versioning, keeping only the most current version and differences from earlier versions. It insulates the different developers from each other. Every developer works in his own directory, and CVS merges the work in the repository when each developer is done. Conflicts should be resolved in the process. Chapter 11. Implement a team development environment 329 Important: CVS and WebSphere Studio Application Developer have a different understanding of what a conflict is. For CVS, a conflict arises when two changes to the same base file are close enough to be noticed by the merge command. For WebSphere Studio Application Developer, a conflict is when the base revision of a modified file is different from the revision stored in the repository. Its unreserved checkout approach to version control helps avoid artificial conflicts common when using an exclusive checkout model. It keeps your shared projects’ data in repositories. Each repository has a root directory on the file system. CVS maintains a history of the source code revisions. Each change is stamped with the time it was made and the user name of the person who made it. It is recommended that developers also provide a description of the change. Given that information, CVS can help you find who made the change and when it was made and why. For more information on CVS, refer to the following URLs: Concurrent Versions System home page: http://www.cvshome.org Concurrent Versions System for NT (CVSNT) home page: http://www.cvsnt.org 11.2.2 CVSNT Server implementation In the ITSO team development environment, we decided to install the CVS server on the same node as the build server. WebSphere Commerce Studio is only available on Windows, so we needed to use CVS for NT (CVSNT), and we wanted to run CVS on the same node (Build and SCM node). The CVSNT Server implementation is organized as follows: CVS Server installation CVS Server repository configuration Create CVS users 330 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: CVSNT is not officially supported by the Eclipse platform, which WebSphere Studio Application Developer is based on. Eclipse does officially support CVS on AIX and Linux. Depending on the version, different bugs may occur. In our case, we used CVSNT 2.0.4 without any problems. An important note about CVSNT support can be found at: http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-vcm-home /docs/online/cvs_features2.0/cvs-faq.html CVSNT was ideal for our environment because we could install the CVS Server on the same node as WebSphere Commerce Studio, and it is easy to use. We did not experience any significant problems using the CVSNT version. CVS Server installation To install CVS on the Windows platform, do the following: 1. Before installing CVSNT, we recommend reading the installation tips found at: http://www.cvsnt.org/wiki/InstallationTips 2. Download the CVSNT V2.0.4 Server (cvsnt-2.0.4.exe) from the following URL to a temporary directory (for example, c:\temp) on the Build and SCM node: http://www.cvsnt.org 3. Execute the CVSNT installer by double-clicking the self-extracting cvsnt-2.0.4.exe file from the temporary directory. 4. Unless noted, we accepted the default options: – We selected Typical installation. – We installed to the c:\cvsnt directory. – Under protocol, we selected Named Pipe (:ntserver) Protocol 5. When the installation is complete, restart your system even if the installer does not prompt you to do so. This step will guarantee that the environment variables are set up properly. CVS Server repository configuration After you have installed the CVS Server and restarted your system (Build and SCM node), do the following to create and configure the CVS Server repository: 1. Stop the CVS services in order to create the repository, by clicking Start -> Programs -> CVSNT -> Service Control Panel. Chapter 11. Implement a team development environment 331 2. When the CVSNT control panel window appears, stop the services CVS service and CVS Lock service by clicking Stop (see Figure 11-2). Figure 11-2 CVSNT service configuration (Service Status page) 3. Click the Repositories tab, and check Repository Prefix. We want our repositories to be under a common root directory. This is purely an organizational feature and is optional. 4. You have to manually create the common root directory. For example, we created the c:\rep directory. 5. Click the Browse button. Select the path you want to be the repository prefix. For example, we selected the c:\rep directory. 6. Click Add to create the new itso repository (c:/rep prefix should be displayed). We choose to call the repository /itso, as seen in Figure 11-3 on page 333 and then clicked OK. 332 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 11-3 ITSO repository path 7. When prompted with the message “c:/rep/itso does not exist, Create it?”, click Yes to create it. When done, the Repository page should look like Figure 11-4. Figure 11-4 CVSNT service configuration (Repository page) 8. Select the Advanced tab. Do the following and then click Apply (see Figure 11-5 on page 334): – Check Server side support for ntserver protocol – Check Impersonation enabled – Check Use local users for pserver authentication instead of domain users Chapter 11. Implement a team development environment 333 CVSNT uses either the domain or the local server directory for user authentication under the pserver protocol. You have to choose the correct value for your environment. This setting only applies if your machine is connected to a Windows domain. Figure 11-5 CVS service configuration (Advanced page) 9. Select the Services Status tab. Click Start for the CVS service and CVS Lock service. The status should change to Running. Create CVS users When setting up CVS users, you have two options: creating separate Windows users for each CVS user (good for high security and auditing needs), or sharing one Windows user for all CVS users (good for ease of configuration and less stringent security needs). Note: As mentioned when configuring the CVS repository, you can choose between local accounts or domain accounts (we used local accounts). Within our example we are not focused on security. In a production environment, we recommend that you refer to the CVS documentation to secure your environment for your needs. 334 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide For the ITSO team development environment, we shared one Windows user for all CVS users as follows: 1. To add the Windows users for developers using CVS, do the following: a. Add desired CVS users to Windows on the Build and SCM node by clicking Start -> Setting -> Control Panel -> Administrative Tools -> Computer Management. b. Select Local Users and Groups -> Users. c. From the menu bar, click Action -> New User. d. We created a user called CVSuser. e. Add CVSuser to the group Power Users. 2. To add CVS users to the CVS repository, do the following: a. Open a Windows command prompt. b. Set the cvsroot as follows: set cvsroot=:ntserver:wcbuild:/itso Where wcbuild is the host name of the Build and SCM node, and itso is the repository created for the ITSO (no prefix). Note: The host name must be specified. For example, specifying localhost will not work. c. Enter the following CVS commands to add users: cvs passwd -a -r CVSuser jganci Where CVSuser is the Windows user created that will be shared by all CVS users, and jganci is the CVS user added to the CVS passwd file found in the c:\rep\itso\CVSROOT. You will be prompted for the desired password of the user being created. We do not recommend that you modify the passwd file directly. Repeat this step for each developer needing CVS access. 3. Next, provide the development users their CVS account information, host name and connection type to the CVS server so that they can establish a connection from WebSphere Studio Application Developer in a later configuration step on the Development node. For example: – Account info: developer CVS user created (for example, jganci) – Host name: CVS Server host name (for example, wcbuild) – Connection type: pserver Chapter 11. Implement a team development environment 335 11.2.3 WebSphere Commerce Studio installation Refer to Appendix E, “WebSphere Commerce Studio implementation” on page 1005 for details. The appendix includes updated procedures for installing and configuring WebSphere Commerce Studio V5.5 with fix packs for WebSphere Studio Application Developer V5.0.1, WebSphere Test Environment V5.0.1, IBM DB2 UDB V8.1 Fix Pack 3, and the WebSphere Commerce Studio Toolkit V5.5.0.2 Fix Pack. 11.2.4 Publish store archive within WebSphere Test Environment After installing and configuring WebSphere Commerce Studio, we will prepare the workspace for development by backing up the WebSphere Commerce instance database and publishing the store archive. Back up databases Before publishing a store within the WebSphere Studio Application Developer WebSphere Test Environment, we recommend that you back up the WebSphere Commerce development instance database (for example, wc1dev) and the WebSphere Commerce Payments database (wpm). For details on how to back up a DB2 database, refer to, “DB2 backup and restore” on page 988. Publish a store archive (SAR) In our example, we used the modified store archive customized by the lead developer to publish into the development environment. For details on the customized store, refer to Chapter 12, “Create a store” on page 341. You can publish any store to this environment. You have the option of restoring the clean WebSphere Commerce instance database at a later time if needed. For details on how to publish a store archive refer to 14.3.1, “Publish the store archive (SAR)” on page 520. You will need to copy the store archive that has been customized to the appropriate location within the WebSphere Commerce Studio environment. 11.2.5 CVS client configuration This section describes CVS client configurations to be made for use with WebSphere Studio Application Developer. 336 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Set CVS DTD file extension to ASCII We discovered when adding DTD files to the CVS repository that by default the file would be added as a binary file. This is not the desired or expected behavior. To address this issue, we did the following: 1. From within WebSphere Commerce Studio Workspace, select Window -> Preferences. 2. Select and expand Team -> File Content. 3. Click Add, and enter dtd in the file extension text box, then click OK. When done, you should see dtd file extension listed as ASCII content type. Label decorations for CVS When working with CVS within WebSphere Studio Application Developer, we recommend adding some visual clues to the environment: 1. Select Window->Preferences in WebSphere Studio Application Developer 2. Expand the Workbench node and click Label Decorations. Note: Workbench is listed first, even though all other options are listed alphabetically. 3. Ensure the CVS check box is checked. 4. Click OK. This will make sure that the icons of any resource that is under source control will get a small cylinder icon, the release number appended to the resource name, the file type (ASCII/Binary) and a greater-than sign in front of the resource name if the file is locally modified and therefore not in synchronization with the repository. If the resource is not under source control, it will have a small question-mark added to its icon, signifying that the file is unknown to CVS. 11.3 Development node implementation This section describes how to implement the Development node used within the ITSO team development environment. The primary software component of WebSphere Commerce Studio used on the Development node is WebSphere Studio Application Developer V5.0.1. Once the WebSphere Commerce Studio is installed, we explain how to configure the CVS client within WebSphere Studio Application Developer. Chapter 11. Implement a team development environment 337 11.3.1 WebSphere Commerce Studio installation Refer to Appendix E, “WebSphere Commerce Studio implementation” on page 1005 for details. The appendix includes updated procedures for installing and configuring WebSphere Commerce Studio V5.5 with fix packs for WebSphere Studio Application Developer V5.0.1, WebSphere Test Environment V5.0.1, IBM DB2 UDB V8.1 Fix Pack 3, and the WebSphere Commerce Studio Toolkit V5.5.0.2 Fix Pack. 11.3.2 CVS client configuration For details on configuring the CVS client within WebSphere Studio Application Developer, refer to 11.2.5, “CVS client configuration” on page 336. 11.4 Development Integration Test node implementation While developing the implementation procedure, we found it very useful to use VMware 4.0 and Ghost 6.5 to take a snapshot of the IBM WebSphere Commerce V5.5, Business Edition runtime environment by creating an image of the system. There are other utilities like this on the market. Each utility has advantages. For details on implementing the Development Integration Test node, refer to the following: 16.2, “Single-tier implementation” on page 559 Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000 product guide A VMware system image is very nice in that it is portable to different systems. You can store multiple versions of virtual machines on the same system and easily start them (limited by disk space). When using VMware you do sacrifice a bit on performance. We used VMware 4.0 and the Microsoft Sysprep utility to change the Windows SID. We found VMware to be especially useful and amazingly compatible and reliable (truly excellent software). For more information on VMware, refer to the following URL: http://www.vmware.com/ During the installation of the nodes in the ITSO runtime environment, we created zip files (backups) for key stages of the implementation. Ghost allows for the imaging of systems, but is much more limited in moving images to a system of different hardware specs (device drivers). The big 338 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide advantage of Ghost is that when done, you are running the native operating system on the hardware and have better performance. We used the Ghost multicast feature to load systems on the network and created Microsoft DOS-based network client boot diskettes to connect to a Windows 2000 share where the Ghost image was stored. This can be used to capture (dump) or load from image. For more information on Symantec Ghost, refer to the following URL: http://www.ghost.com/ Using these utilities allowed us to go back to a previous state during the installation (provided an image was captured of the system). This can save a tremendous amount of time and allow you to verify your knowledge of the environment before proceeding to a deployment in a production environment. Tip: The following only applies if you have Windows 2000 Datacenter Server on your build server. VMware V3.2 does not support a Physical Address Extension (PAE) enabled host system, so we had to disable PAE by removing “/PAE” from the boot.ini file of the host system, which is running Windows 2000 Datacenter Server, by doing the following: Make a copy of the original copy of boot.ini file Change the last line in boot.ini file from: multi(o)disk(0)rdisk(0)partition(1)\WINNT=”Microsoft Windows 2000 Datacenter Server” /fastdetect /PAE To: multi(0)disk(0)disk(0)partition(1)\WINNT=”Microsoft Windows 2000 Datacenter Server” /fastdetect Chapter 11. Implement a team development environment 339 340 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 12 Chapter 12. Create a store This chapter describes how to seed the development environment with a new store using one of the sample stores shipped with IBM WebSphere Commerce V5.5, Business Edition as a starting point. In addition, we demonstrate by example the key changes that must be made to assets of the store and provide a procedure and Ant script to package the store archive in preparation for deployment. For more advanced customization of commands and EJBs, refer to Chapter 13, “Customize a store: Price Watch example” on page 393. The chapter is organized into the following sections: Overview Package and verify store archive Import store assets into CVS Required customization of basic store assets Further customization of basic store assets Publish the store archive to the workspace Add the store front files to CVS Set up additional team development nodes © Copyright IBM Corp. 2003. All rights reserved. 341 12.1 Overview The following sections describe the steps that we recommend be followed when setting up the development environment and creating a store. The instructions in 12.2, “Package and verify store archive” on page 343 and 12.6, “Publish the store archive to the workspace” on page 384 only needs to be done once, whereas the instructions in 12.8, “Set up additional team development nodes” on page 388 must be followed once for each development machine. The steps involved in the preparation of the workspace and customization of the store archive are as follows: 1. Prepare the WebSphere Commerce Studio workspace (see 12.2, “Package and verify store archive” on page 343). 2. Prepare the source control repository (optional - see 12.3, “Import store assets into CVS” on page 350). 3. Customize the store archive (see 12.4, “Required customization of basic store assets” on page 354). 4. Publish the store archive to the workspace (see 12.6, “Publish the store archive to the workspace” on page 384). 5. Prepare subsequent team developer machines (optional - see 12.8, “Set up additional team development nodes” on page 388). Figure 12-1 on page 343 gives an overview of these steps. The figure shows the individual that performs each step and illustrates the different steps involved in a stand-alone and a team development environment. 342 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Stand-alone Environment Team Environment Package and verify store archive Package and verify store archive Import store assets into CVS Stand-alone Developer Required customizations of basic store assets Required customizations of basic store assets Team Lead Optional customizations of basic store assets Optional customizations of basic store assets Publish store archive to the workspace Publish store archive to the workspace Add store front files to CVS Set up additional team development nodes Team Developer Figure 12-1 Overview of store creation steps 12.2 Package and verify store archive In this section we prepare the WebSphere Commerce Studio workspace for store customization. The WebSphere Commerce Studio installation will already have created a workspace with the WebSphere Commerce base classes and store-independent JSPs. In this section we augment this workspace with additional resources. We assume that you have already decided on a store model to base your development on. In the following examples, we use the B2B Direct store model, also known as ToolTech. Substitute all references to B2B Direct or ToolTech for the store model that you will use for development. Chapter 12. Create a store 343 If you just want to import directly the customized ITSO store assets found throughout this chapter, use ITSO.sar found in the c:\6969code\sar directory in place of the B2B Direct store archive. Note: In a team development environment, the following preparations should be performed on the Build and SCM node, acting as a master development environment. These preparation are typically performed by the development lead. For details on configuring the Build and SCM node, refer to 11.2, “Build and SCM node implementation” on page 328. 12.2.1 Back up workspace and databases Since the WebSphere Commerce Studio workspace tends to fill up with classes and projects during the life cycle of a product, it is a good idea to make a backup of the workspace before any modifications are made. In addition, we recommend that you back up the WebSphere Commerce instance database and WebSphere Commerce Payments database. Back up workspace The backup is simply done by copying the workspace from the location chosen during installation of WebSphere Commerce Studio (for example, c:\ibm\workspace) to a backup location. Ensure that WebSphere Studio Application Developer is not running during the backup. Note that the WebSphere Commerce Studio workspace occupies a lot of space. Ensure that the target drive for the backup has sufficient free space to hold the entire workspace. The workspace is approximately 400-500 MB. Back up databases We recommend that you back up the WebSphere Commerce instance database (for example, wc1dev) and WebSphere Commerce Payments database (for example, wpm) used by WebSphere Commerce Studio. For details on using the DB2 backup command, refer to “DB2 backup and restore” on page 988. 12.2.2 Create the Packaging project In this section we create a project that will be used for packaging the store archives and other deployment assets. The project will contain build scripts as well as configuration data for the store archive and a stand-alone deployment tool. This project will also include XML files used for data mass load into the instance database. 344 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide We recommend using store archives as a base for development. Using store archives has several advantages, including: Convenient packaging of database and store front assets. Useful for distributing prototypes and demo stores. Ability to change the store directory and identifier at publish time, resulting in the ability to deploy the same store in multiple instances. The concept profile stores introduced in WebSphere Commerce V5.5 are tightly linked to store archives. Possibility to package the same store in several versions, such as database-only for development purposes, lightweight upgrade version, etc. Store archives do not, however, support the deployment of database schema changes, customized Java code (such as commands and EJBs), instance-level (store-independent) data, or database assets for customized tables. In order to simplify deployment of such assets, we supply a stand-alone deployment tool to be used as a supplement to the store archive. The high-level steps involved in the creation of the packaging project are as follows: Create a project in WebSphere Studio Application Developer called Packaging. Extract the script files supplied with this redbook. Extract the sample store model archive into the project. We describe these steps in detail in the following sections. Create project in WebSphere Commerce Studio To create a project in WebSphere Commerce Studio, do the following: 1. Open WebSphere Commerce Studio by selecting Start -> Programs -> IBM WebSphere Commerce Studio -> WebSphere Commerce development environment. 2. Select File -> New -> Project. 3. Select Simple in the left-hand pane of the new window and Project in the right-hand pane (see Figure 12-2 on page 346). Click Next. Chapter 12. Create a store 345 Figure 12-2 Selecting the type of the new project 4. Enter Packaging as the project name. Click Next. Figure 12-3 Specifying the name of the new project 5. The Referenced Projects window will appear. Check Stores, WebSphereCommerceServerExtensionsData and WebSphereCommerceServerExtensionsLogic projects, then click Finish. 346 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 12-4 Selecting the referenced projects The new project will now be created. Add build script files supplied with this redbook To add the build script files supplied with this redbook, do the following: Note: The build scripts provided with this redbook will be used to package SAR files, build the application, and deploy the application. The build script can be found in the ITSO sample code c:\6969code\build directory. For more information, refer to Chapter 10, “ITSO sample code” on page 319. 1. Go to the Resource perspective by selecting Window -> Open Perspective -> Other..., select Resource in the Select Perspective window, and click OK. 2. Highlight the Packaging project and select File -> Import. 3. Select File system and click Next. 4. Enter the path to the build directory of the additional material supplied with this redbook in the Directory field, for example c:\6969code\build. 5. Select and expand the build folder in the left-hand pane. 6. Check the DeployTool folder and SARFile folder check boxes. Click Finish. Chapter 12. Create a store 347 Extract the sample store archive to the SARFile folder To extract the sample store archive into the SARFile folder, do the following: 1. Go to the Resource perspective by selecting Window -> Open Perspective -> Other, select Resource in the Select Perspective window, and click OK. 2. Select and expand the Packaging project, highlight the new SARFile folder and select File -> Import. 3. Select Zip file in the Import window and click Next. 4. Enter the path to the store archive for the store model and click Finish. Tip: You can click Browse to search for the file, but since WebSphere Studio Application Developer assumes that you will be importing a file with extension .jar or .zip, the browser window will not show store archives. To search for store archives, enter *.sar in the File name field and click Open. For example, we entered the following for the B2BDirect.sar which we chose to use as a starting point for our working example. c:\ibm\wcstudio\Commerce\samplestores\B2BDirect\B2BDirect.sar Note: If you do not wish to make the modifications found throughout this chapter, but simply want to import them, use ITSO.sar (found in c:\6969code\sar directory) instead of B2BDirect.sar. 12.2.3 Package a store archive (SAR) To ensure that the build script that was added to the SARFile project in the previous section correctly builds the store archive, we recommend that you package the store archive using the build.xml Ant script and then publish this to the Development Integration Test node as defined in 11.4, “Development Integration Test node implementation” on page 338. The purpose of this section is to validate that you have all assets of the store archive and that the store archive packaging works properly as a baseline for development. At this point, we have not customized the store archive; we are just validating that we can reproduce it. The store archive that is packaged during this procedure will be called ITSO.sar to distinguish it from the original B2BDirect.sar. The ITSO.sar at this stage is identical in function to the B2BDirect.sar. We will later make customizations to the ITSO.sar. 348 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: build.xml Ant script for store archive packaging We have supplied build.xml Ant script to package the store archive. There are a few scenarios in which the build.xml script is used, depending upon where the files are that it will package. The build.xml script will package both the data and store front assets into the store archive. The store archive will contain assets from the following locations: Packaging/SARFile/META-INF Packaging/SARFile/WEB-INF Packaging/SARFile/SAR-INF Packaging/SARFile/xml Stores/Web Content/ (if found) Packaging/SARFile/ (if not found in the Store project) If you have published a store archive to the workspace, the store front assets will thus be picked up from the Stores/Web Content/. Otherwise, the store front assets will be retrieved from the Packaging/SARFile/. To package the SAR file, do the following: 1. Go to the WebSphere Commerce Studio workspace. 2. Change to the Resource Pespective. 3. Expand the Packaging project. 4. Expand the SARFile folder 5. Right-click the build.xml file and select Run Ant. 6. Enter -DSTOREDIR=ToolTech in the Arguments text field. Ensure that only the build-sar-full target is checked. Note: This is a way of temporarily overriding the store directory specified in the build script. If you have chosen to base your development on another store model, substitute that model’s store directory for ToolTech in the parameter value. ITSO.sar: If you chose to use ITSO.sar, do not specify this argument. 7. Click Finish. 8. Running the build.xml script will generate a file called ITSO.sar in the SARFile folder. To verify that the file exists, select the SARFile folder, and select File -> Refresh. Chapter 12. Create a store 349 Note: The build.xml Ant script contains the store archive name. 12.2.4 Publish the store archive (SAR) To publish the ITSO.sar to the Development Integration Test node, refer to 14.3.1, “Publish the store archive (SAR)” on page 520. Ensure that you have a pristine runtime environment to publish to. As we recommended, you should have a backup of the WebSphere Commerce instance database and better yet a pristine WebSphere Commerce instance using such software as VMware or Ghost. 12.2.5 Verify the store after publish After you have published the repackaged store archive on the Development Integration Test node, we recommend that you verify the store is working properly. For details on how to verify the store, refer to 16.2.10, “Verify the runtime environment and store functionality” on page 577. At this stage you have validated the ITSO defined process for packaging the store archive. 12.3 Import store assets into CVS The purpose of this step is to prepare the CVS repository with the code and data for the store as a base for further customization. Note: You can skip this step if you do not need source control management in your environment. Up to this point all resources have been stored on the local file system. In a team development environment with software configuration management (SCM), we want to put the resources that will be changed as part of the customizations under source control. Importing store assets into CVS is done as follows: Create a CVS module from the project Add the files to CVS Table 12-1 on page 351 summarizes the projects and the resources in each project that must be added to source control. 350 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Table 12-1 Names of projects and contained directories to add to source control Project Resources Project description Packaging DeployTool SARFile Deployment packaging tools Stores Web Content Web content, such as JSPs and property files WebSphereCommerceServerExtensionsData ejbModule Custom EJBs and data beans WebSphereCommerceServerExtensionsLogic src Custom commands and utilities 12.3.1 Create a CVS module from the project The following procedure shows how to add the first project. Repeat these steps for the remaining three projects shown in Table 12-1: 1. Change to the Resource perspective. 2. Right-click the Packaging project. 3. Select Team -> Share Project. 4. When the Share Project wizard opens, we entered the CVS connection details as seen in Figure 12-5 on page 352 and then clicked Finish. In this example, we created the CVS user needed for authentication in “Create CVS users” on page 334. Tip: In our example, we chose to put only some of the files in each project under source control. This results in the label decorations for the projects always showing up with a greater-than sign, as if the contents had been altered. To avoid this, you can tell WebSphere Studio Application Developer to ignore non-CVS files by right-clicking such files or directories, selecting Team -> Add to .cvsignore and clicking OK. This will create a file named .cvsignore containing the names of those files. This file can then be put under source control using the procedure outlined above. Chapter 12. Create a store 351 Figure 12-5 Example of CVS connection information Note: At times during the development we encountered the following message even when specifying a correct user name and password: If you get this error, just enter the password once again and the CVS server should accept the user name and password. 352 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 5. WebSphere Studio Application Developer will communicate with the CVS server and create the new project as a module on the server. To verify that CVS module was created correctly, you should see the CVS server host name [CVS_Server_hostname] to the right of the Packaging project. 6. Repeat this process for each of the projects listed in Table 12-1 on page 351. 12.3.2 Add the files to CVS In the previous section, we only created the module in the CVS repository. At this point the CVS repository thus has only the Packaging directory, but no files. This step details how to add the files to the CVS module. To add files to CVS module within the CVS repository, do the following: 1. Ensure you have set the DTD to ASCII within CVS, as described in “Set CVS DTD file extension to ASCII” on page 337. Tip: If you do not perform this step, the DTD files added to the CVS repository will be stored in binary format. If you make this mistake, you can change the file content type from binary to ASCII by right-clicking the file and selecting Team -> Change ASCII/Binary Property. Next, select ASCII without keyword substitution, click Next, select Include files that are already shared in the repository and then click Finish. 2. Highlight the two folders DeployTool and SARFile, right-click one of them and select Team -> Add to Version Control. Note: In this example, we are adding the DeployTool and SARFile projects. You will need to repeat the process for each project listed in Table 12-1 on page 351. 3. Right-click the project folder and select Team -> Commit. 4. Enter a comment, such as First time import of build project, and click OK. WebSphere Studio Application Developer will now add the files to the repository. 5. Repeat this process for each of the projects listed in Table 12-1 on page 351. Chapter 12. Create a store 353 12.4 Required customization of basic store assets The sample store that we have built upon for the ITSO store contains a lot of information that does not apply to our store. This section describes the steps that are necessary in order to customize the basic store information. The information that should always be modified for a store includes: Store directory and identifier Hardcoded references Store address Catalog data Store front-end assets All of the configuration and catalog data for the store, is contained in XML files, which can be found in the Packaging project under the directory SARFiles/WEB-INF/stores/BusinessDirect/data/ToolTech/data. Note: The sample store archives contain the database assets in the following directory format: WEB-INF/stores//data//data In our example, the directory structure includes BusinessDirect for the business model, and ToolTech for the store directory. Internally, the B2BDirect business model default store identifier and directory is ToolTech. The following sections describe how to customize the assets outlined. For additional information, refer to the Store Development Guide, IBM WebSphere Commerce V5.5 product guide. 12.4.1 Store directory and identifier The composite sample stores provided with IBM WebSphere Commerce V5.5, visible in the default store publishing view, have unfortunately been configured by default in a way that the store identifier and store directory parameters are read-only. In previous versions of WebSphere Commerce, the store directory and identifier were user defined at publishing time. We have defined two possible solutions to change the read-only attributes in the SAR file for store directory and identifier: Modify ForeignKeys.dtd store identifier and directory values Modify store-refs.xml to expose publishing parameters 354 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: In our example, we did both. In some cases we wanted to default to ITSO, and in other cases we wanted to specify the store directory and identifier at publishing time. Lastly, we did both just to demonstrate how. Modify ForeignKeys.dtd store identifier and directory values To modify the store archive with the desired store identifier and store directory values for your store, do the following: 1. Change to the Resource perspective. 2. Select and expand the Packaging project. 3. Select and expand the SARFile folder. 4. Open the file WEB-INF/stores/BusinessDirect/data/ForeignKeys.dtd. 5. Change the values of the store directory and identifier in ForeignKeys.dtd to suit your store. See Example 12-1 for ITSO store changes. Note: Within WebSphere Studio Application Developer, the default view for DTD files is the Design view. You will need to click the Source tab to see the contents of the ForeignKeys.dtd file. Also, in Example 12-1, we have ordered the locale entities. Example 12-1 ForeignKeys.dtd for the ITSO Store Note: We noticed that the ORGANIZATION_DN and ORGENTITYNAME values have been changed to lowercase as of the WebSphere Commerce V5.5.0.2 Fix Pack. Chapter 12. Create a store 355 Modify store-refs.xml to expose publishing parameters The ForeignKeys.dtd displayed in Example 12-1 on page 355 defines a number of XML entitities that may be used in the XML file that will be mass loaded during the store publishing process. Any of these entities can be exposed to the Parameters page in the store publishing user interface, in either read-only or editable mode, by adding them to the SAR-INF/store-refs.xml file. Example 12-2 displays how to add the store owner organization to the publishing Parameters page. The sample stores expose the store directory and identifier, but do not allow the user to change the store directory and identifier at publish time. If you wish to allow this, edit the file SAR-INF/store-refs.xml in the SARFile project by changing the two occurrences of the string readonly to text. Example 12-2 shows an example of this. Example 12-2 Modify store-refs.xml to expose publishing parameters If the parameters are changed at publishing time, the XML entities will be updated to reflect this. For example, the value entered as the store directory in the store publishing Parameters page will be substituted by the store publishing XML parser for &STORE_DIR; in all of the XML files being mass loaded during the publishing process. 356 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: At the time of writing, a problem with the store publishing component resulted in erroneous renaming of store front files. We found that all files that had the same name as the source store directory would be renamed to the target store directory name. In this case, the result was that the cascading stylesheet file ToolTech.css would be renamed to ITSO.css during the store publish if the target store directory was set to ITSO. To work around this problem, we chose to rename this file to Main.css and update all references to the file. This was simply done using search and replace in all JSP files in the store archive. 12.4.2 Hardcoded references The sample store archives contain many references that have been hard-coded to the internal store model name. For example, the B2BDirect.sar known as ToolTech contains many hardcoded references to ToolTech. There are two types of files that need to be modified, each in a different way: Hardcoded files for mass load files Replace the hardcoded references in these files with &STORE_IDENTIFIER;. This type of file is resolved during mass load. Hardcoded references for runtime files Replace the hardcoded references with the desired store name (hardcoded value). For example, from ToolTech to ITSO. Hardcoded files for mass load files We did a search on the files (grep) and found that B2BDirect.sar (ToolTech) contained hardcoded references to ToolTech. We modified the files listed in Example 12-3 and replaced ToolTech with &STORE_IDENTIFIER;. Note: There are other files that contain ToolTech, but do not need to be changed. For example, ibm-wc-load.xml, unpack.xml and store-data-assets.dtd contain ToolTech. However, ToolTech is the name of a temporary directory that store publish uses to unpack and process files. Example 12-3 Hardcoded references in mass load files with ToolTech WEB-INF\stores\BusinessDirect\data\ToolTech\accesscontrol.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\accesscontrol.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\businesspolicy.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\campaign.xml (comment only) WEB-INF\stores\BusinessDirect\data\ToolTech\data\catalog.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\fulfillment.xml Chapter 12. Create a store 357 WEB-INF\stores\BusinessDirect\data\ToolTech\data\offering.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\shipping.xml (comment only) WEB-INF\stores\BusinessDirect\data\ToolTech\data\de_DE\accesscontrol.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\de_DE\store.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\en_US\accesscontrol.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\en_US\store.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\es_ES\accesscontrol.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\es_ES\store.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\fr_FR\accesscontrol.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\fr_FR\store.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\it_IT\accesscontrol.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\it_IT\store.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\ja_JP\accesscontrol.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\ja_JP\store.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\ko_KR\accesscontrol.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\ko_KR\store.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\pt_BR\accesscontrol.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\pt_BR\store.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\zh_CN\accesscontrol.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\zh_CN\store.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\zh_TW\accesscontrol.xml WEB-INF\stores\BusinessDirect\data\ToolTech\data\zh_TW\store.xml For example, the action groups for the access control for the ToolTech sample store are all prefixed with the string ToolTech, as can be seen from the short excerpt from the accesscontrol.xml file in Example 12-4. Example 12-4 Example of hard-coded references These references should be changed to refer to an XML entity. In our store archive we changed all occurrences of the string ToolTech to the string &STORE_IDENTIFIER;. The previous excerpt should thus be changed as seen in Example 12-5. Example 12-5 Example of dynamic references to the store identifier 358 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: It is not strictly necessary to change the names of the ID resolver internal alias resolution identifiers (strings identified by the preceeding @-sign), but we did so for consistency. Hardcoded references for runtime files Replace the hardcoded references with desired store name (hardcoded value) for the files listed in Example 12-6. For example, replace ToolTech with ITSO. Example 12-6 Hardcoded references in runtime files for ToolTech WEB-INF\xml\tools\stores\ToolTech\devtools\flow\fsf\fsf.xml WEB-INF\xml\tools\stores\ToolTech\devtools\flow\repository\RepositoryInfo.xml WEB-INF\xml\tools\stores\ToolTech\devtools\flow\repository\Site.xml 12.4.3 Store address The address of the store is defined on a per-locale basis in the store.xml files found in WEB-INF/stores/BusinessDirect/data/ToolTech/data/, where is the locale. Example 12-7 shows a modified version of the en_US locale variant of the store address. Note that the business title was changed in the previous section from the default hard-coded value of ToolTech to the dynamic value &STORE_IDENTIFIER;. Example 12-7 Sample en_US/store.xml store address for the en_US locale Chapter 12. Create a store 359 12.4.4 Catalog data The catalog data for the store archive is stored in the files listed in Table 12-8. Example 12-8 Catalog related XML files in the store archivee File Description catalog.xml Catalog master data. /catalog.xml Locale-dependent catalog data for locale . store-catalog.xml Relations between the store and catalog. store-catalog-shipping.xml Definition of shipping costs for products. store-catalog-tax.xml Definition of tax codes for the catalog. offering.xml Prices for products in the catalog. While developing the ITSO store, we constructed two sets of catalog data files: Development ITSO catalog ITSO catalog hierarchy and sample products for development. Note: The ITSO.sar contains product catalog data for US English only. The /catalog.xml for all other languages besides US English have been pruned (contain no data). Pruned ITSO catalog The pruned catalog.xml files are structurally intact, but do not contain any product data. The pruned ITSO catalog.xml file will be used for the purposes of packaging and publishing a store archive without catalog data. Note: Once the ITSO store is deployed in a production environment, only store assets will be published using a store archive. The store catalog will be maintained using the WebSphere Commerce Accelerator and CSV file imports. Long term, the ITSO store will devise an automated method of managing catalog data using the MassLoader and supporting tools. Development ITSO catalog While developing the ITSO store, we wanted to have the proper catalog hierarchy and some sample data available to test with. For this reason, we updated the 360 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide catalog XML files within WebSphere Commerce Studio to contain the categories and products listed in Table 12-2. Table 12-2 Development ITSO catalog with sample products Category Sub category WebSphere Redbook Software DB2 Redbook Software Product Item SKU # IBM WebSphere Application Server V5.0 Systems Management and Configuration: WebSphere Handbook Series, SG24-6195 Hardcopy SG24-6195 PDF SG24-6195-PDF WebSphere Commerce V5.5 Handbook, Customization and Deployment Guide, SG24-6969 Hardcopy SG24-6969 PDF SG24-6969-PDF IBM WebSphere Application Server V5 CD WAS-001-CD Zip WAS-001-ZIP IBM WebSphere Commerce V5.5, Business Edition CD WC-001-CD Zip WC-001-ZIP DB2 UDB/WebSphere Performance Tuning Guide, SG24-6417 Hardcopy SG24-6417 PDF SG24-6417-PDF DB2 UDB Evaluation Guide for Linux and Windows, SG24-6934 Hardcopy SG24-6934 PDF SG24-6934-PDF IBM DB2 UDB V8.1 Enterprise Server Edition CD DB2-001-CD Zip DB2-001-ZIP IBM DB2 Data Miner V8.1 CD DB2DM-001-CD Zip DB2DM-001-ZIP Chapter 12. Create a store 361 Category Sub category Tivoli Redbook Software Product Item SKU # Enterprise Business Portals II with IBM Tivoli Access Manager, SG24-6885 Hardcopy SG24-6885 PDF SG24-6885-PDF Measuring e-business Web Usage, Performance, and Availability, SG24-6931 Hardcopy SG24-6931 PDF SG24-6931-PDF Tivoli Access Manager V4.1 CD TAM-001-CD Zip TAM-001-ZIP CD TWSA-001-CD Zip TWSA-001-ZIP Domino Designer 6: A Developer’s Handbook, SG24-6854 Hardcopy SG24-6854 PDF SG24-6854-PDF Patterns: Custom Designs for Domino & WebSphere Integration, SG24-6903 Hardcopy SG24-6903 PDF SG24-6903-PDF Lotus Domino V6.0 CD DOM-001-CD Zip DOM-001-ZIP CD ST-001-CD Zip ST-001-ZIP Tivoli Web Site Analyzer V4.2 Lotus Redbook Software Lotus Sametime V3.0 The sample ITSO catalog files created for development test purposes can be found in the ITSO provided in ITSO.sar and in the sample code c:\6969code\catdata directory. We modified the following files to include the ITSO catalog categories, products and items listed in Table 12-2 on page 361 for the en_US locale: 362 catalog.xml en_US/catalog.xml /catalog.xml (all other locales pruned - no data) store-catalog.xml store-catalog-shipping.xml offering.xml WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: Since the sample development catalog has only been defined for US English, it is important that all the locale-dependent catalog.xml files for other locales are pruned as described in the next section (see Example 12-10 on page 363). If this is not done, the store publishing will fail. The c:\6969code directory structure matches that of the SAR directory structure for the files listed. Pruned ITSO catalog In 12.4.4, “Catalog data” on page 360, we described two methods of constructing catalog data files. This section describes the method of pruning the catalog files. In this case the pruned catalog.xml files are structurally intact, but do not contain any product data. The pruned ITSO catalog XML files can be used to package and publish a store archive without catalog data. This is useful if your catalog data will be managed in a separate process from deploying your store front assets. For example, you may decide to manage the catalog data in an automated fashion using the MassLoad utility. Since a store must have a master catalog, the catalog.xml file should not be removed from the store archive. Instead the catalog.xml file should be pruned to only contain a catalog skeleton. Example 12-9 shows the data that should be left in the catalog-related XML files. Example 12-9 Sample pruned catalog.xml defining the master catalog Example 12-10 lists a sample pruned locale-specific catalog.xml. This file is used for the language-dependent description for the master catalog. Example 12-10 Sample en_US/catalog.xml Example 12-13 lists the pruned store-catalog-tax.xml. This file contains the tax calculation information. Example 12-13 Sample pruned store-catalog-tax.xml Example 12-14 lists the pruned offering.xml. This file contains the trading position containers available in the store. Example 12-14 Sample pruned offering.xml Assign roles to container buyer organization Example 12-21 on page 377 lists the XML added to the modelorgrole.xml, to assign roles to the new container Buyer Organization. The modelorgrole.xml file can be found in the WEB-INF/stores/BusinessDirect/data/model directory in the store archive, For reference purposes we looked at the storeorgrole.xml for roles assigned to the Buyer A Organization, since our example Buyer Organization requires the same roles listed in Example 12-4 on page 377. 376 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Table 12-4 Role assigned to container buyer organization Role name role_id Buyer Administrator -21 Buyer Approver -22 Buyer (buy-side) -24 Procurement Buyer Administrator -25 Procurement Buyer -26 Example 12-21 ITSO modified modelorgrole.xml (snippet) We would like to highlight a few key points regarding the code snippet in Example 12-22. When a user registers and specifies as its parent organization any descendent of “o=Buyer Organization,o=Root Organization” (meaning any store, since Root is at the top of the tree), assign them the Registered Customer role in the organization that owns the store in which they are registering (effectively granting them access to the store only), as long as that store’s owner is a descendent of “o=Seller Organization,o=Root Organization”. Configure business entity flag For the purposes of contracts, we need to specify that any organization created under the Buyer Organization container is marked as a business entity. This will allow the descendent buyer organizational units to the Buyer Organization to participate in contracts. Example 12-23 lists the code added to the BusinessEntities section in the MemberRegistrationAttributes.xml, which can be found in the xml\member directory in the store archive. Example 12-23 ITSO snippet to BusinessEntities in MemberRegistrationAttributes.xml The business entity flag will be checked for every organization registration. The meaning of Example 12-23 is as follows: whenever an organization is registered as a descendent of “o=Buyer Organization,o=Root Organization”, and to any store under “o=Root Organization” (any store in the system), assign to this organization the BusinessEntity flag. The business entity flag is captured interally as a MemberAttribute in the MBRATTRVAL table. 378 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: When a store archive is published containing the XML files we have modified in this section, there are database table entries that are refreshed in cache. If you were to manually load these files, you would need to refresh the registry or restart the WebSphere Commerce instance application server for the changes to take effect. 12.5.4 Business accounts Business accounts can be created by either of the following methods: Create a business account using the WebSphere Commerce Accelerator Create a business account using an XML file included in the store archive In this section, we provide an overview of business accounts and provide a brief explanation of what we did in the store archive for the ITSO store for business accounts. Business account overview Business accounts represent the relationship between a store and the store's customer organizations. Business accounts provide a starting point for managing business relationships. Using business accounts, you can track contracts and orders for customer organizations. In addition, you can configure how buyers from customer organizations shop in a store. A business account contains the following information about a customer organization: The name of the customer organization and a contact person within that organization. The department and name of the account representative from the store assigned to the customer organization. Information about purchase orders a customer organization has with a store. How invoices are delivered to the customer organization. If the customer organization has a credit line. Any display customization information for the business customer. Store pages can be customized for a business account by specifying a piece of HTML code that can be used by a store's JavaServer Pages files. Any general remarks about the business account. Business accounts control customer entitlement by providing the ability to buyers from customer organizations to access a store's master catalog and see standard pricing for products contained in the master catalog. If a customer Chapter 12. Create a store 379 organization is not entitled to purchase products in the store's master catalog at standard prices, they are limited to products and prices covered by contracts the customer organization has with a store. Before creating a business account for a customer organization, the customer organization must already exist in WebSphere Commerce. Also, at least one person associated with the customer organization should be a registered customer, since a contact at the customer organization is required when creating a business account. 12.5.5 Contracts This section provides an overview of contracts and describes the modifications to the contract.xml that we made for the ITSO store. Contracts overview Contracts enable a customer organization to purchase products from a store or a group of stores at a specified price for a specified period of time under specific conditions. WebSphere Commerce provides the ability to define and deploy contracts that have been negotiated. A contract consists of the following elements: Profile The contract profile contains the identifying information for the contract. This information includes a unique name for the contract, a short description, and a time period for which the contract is valid. Participants Contract participants are the organizations that take part in the contract. There is a buyer organization, a seller organization, and contacts at both organizations. Terms and conditions Contract terms and conditions are the rules that cover the actual implementation of the contract. Contract terms and conditions cover such information as product pricing, returns and refunds, payment, shipping, and order approval. Attachments Contract attachments cover any information not covered by the previous elements, such as file attachments, that provide additional information about the contract and any general remarks about the contract. WebSphere Commerce stores Universal Resource Identifiers (URIs) for contract attachments, not the actual attachments. 380 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Reference A contract can refer to another contract to share its terms and conditions. For example, contract A can refer to contract B. Thus, a buyer who is entitled to contract A will be entitled to all the terms and conditions from contract A, as well as to all the terms and conditions in contract B. All contracts are associated with business accounts. Contracts cannot be created for customers you have not created an account for. Different items in a single order may be purchased under different contracts. Buyers can select the contract they shop under at either the start of the shopping flow or when they add an item to their order, depending on the store design. When purchasing items under different contracts, the following rules apply: Contracts for all items in an order must share at least one payment method. If the contract for an item does not share a payment method, the buyer cannot add that item to the order. Only the payment methods shared by all items in an order can be used to pay for the order. All items in an order must come from contracts belonging to the same business account or the store default contract. In IBM WebSphere Commerce V5.5, Business Edition, a contract can be created by either of the following two methods: Create a contract using the WebSphere Commerce Accelerator Contracts created using the Accelerator are always associated with an account. Create contract using XML Creating a new contract using XML allows you to create contracts that are not associated with business accounts. Every store has at least one contract not associated with a business account: the store default contract. To successfully create a contract using XML, you should be familiar with XML and the structure of the DTD or XSD files that defines the structure of contract XML files. Contracts.xml for the ITSO store The business policy related data in the store archive is found in the contract.xml file. This file can be used to load data, such as contracts, and the related terms and conditions at store publishing time. The contract.xml supplied in the ToolTech sample store defines four contracts: Contract 1234, which is the store default contract. Chapter 12. Create a store 381 Contract 2345, belonging to account 1. This contract defines a storewide discount, an order approval limit, a contract purchase minimum and maximum, as well as a number of shipping-related restrictions. Contract 3456, belonging to account 2. This contract defines a discount on two of the product categories and allows the use of the OfflineCard cassette for VISA, Master Card, and American Express. Contract 4567, belonging to account 2. This contract defines a larger discount on two of the categories, and allows the buyer to use two more shipping options than contract 3456. Restriction: IBM WebSphere Commerce V5.5, Professional Edition only supports one contract, the default contract, which defines the terms and conditions for all customers. IBM WebSphere Commerce V5.5, Business Edition supports contracts that are related to specific business accounts. In our working example, we only define the store default contract in the store archive. Contracts for other buyers will be created and loaded subsequently using the WebSphere Commerce Accelerator. The store default contract, as defined in contract.xml for the ITSO store, is shown in Example 12-24. This contract is identical to the ToolTech default contract, with the exception of the name. Example 12-24 Default contract.xml for the ITSO store 382 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Chapter 12. Create a store 383 12.5.6 Taxes, shipping couriers and shipping prices The tax related store archive data can be found in the files tax.xml, taxfulfill.xml and store-catalog-tax.xml. Shipping information is stored in the files shipping.xml, shipfulfill.xml and store-catalog-shipping.xml. Taxes, discounts, and shipping prices are defined in the Calculation Code Framework of WebSphere Commerce, which is complex. Unless you fully understand this framework, we suggest that you leave out tax information (prune XML files of data) from the store archive and configure the tax information manually using the WebSphere Commerce Accelerator. Tip: In WebSphere Commerce V5.4, tax and shipping information was managed from Store Services. In WebSphere Commerce V5.5, this functionality has been moved to the WebSphere Commerce Accelerator. If you choose to include taxes and shipping information in the store archive, refer to Store Development Guide, IBM WebSphere Commerce V5.5 for details about the data model and XML file format. 12.5.7 Payment information The file paymentinfo.xml contains data used by store publish to configure WebSphere Commerce Payments for the store. The file specifies whether the store uses WebSphere Commerce Payments and if so, the detailed configuration of each enabled cassette. Refer to Store Development Guide, IBM WebSphere Commerce V5.5 for information on customizing the paymentinfo.xml file. 12.6 Publish the store archive to the workspace After the customizations in the previous sections have been completed, the store archive is ready to be published to the WebSphere Commerce Studio workspace 384 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide by the development lead who has been preparing this base store archive to the development team as a starting point. Note: In a team development environment, the following preparations should be performed on the Build and SCM node, acting as a master development environment. These preparation are typically performed by the development lead. For details on configuring the Build and SCM node, refer to 11.2, “Build and SCM node implementation” on page 328. 12.6.1 Package the customized store archive Refer to 12.2.3, “Package a store archive (SAR)” on page 348 for details on how to package the store archive with the updated store assets. Note: At this stage you have a customized version of the B2B Direct (ToolTech) store model with the ITSO store front and catalog assets. The store archive is packaged as ITSO.sar. 12.6.2 Publish the customized store archive to runtime After packaging of the customized base store archive, we recommend that you publish the store archive as described in 12.2.4, “Publish the store archive (SAR)” on page 350 on the Development Integration Test node. This step is done to verify that the customized store archive publishes and works properly before publishing to the workspace. If you wish, you can skip this step and directly publish to the workspace. 12.6.3 Verify the customized store archive Verify that the customized store archive is working properly with the changes made on the Development Integration Test node. Refer to 12.2.5, “Verify the store after publish” on page 350 for details. 12.6.4 Publish the store archive to the workspace Now that you have verified that the customized store archive is working properly as your base store for customization, you are ready to publish the store in the WebSphere Commerce Studio environment. 1. We recommend that you back up the workspace and instance database as described in 12.2.1, “Back up workspace and databases” on page 344 and “DB2 backup and restore” on page 988, respectively before proceeding. Chapter 12. Create a store 385 2. Create the .sar directory as follows: \Commerce\instances\\sar For example: c\ibm\wcstudio\Commerce\instances\wc1dev\sar 3. Copy ITSO.sar. For example, in the ITSO team development environment we copied the ITSO.sar from the Development node as follows: From: \Packaging\SARFile\ITSO.sar To: \Commerce\instances\\sar 4. Start the servers for WebSphere Commerce and WebSphere Commerce Payments from within WebSphere Commerce Studio. a. Select Window -> Show View -> Servers. b. Select WebSphereCommercePaymentsServer, and right-click Start. Note: By default, when the WebSphere Commerce Payments instance is created during the WebSphere Commerce Studio installation, the instance does not require a database password (no need for IBMPayServer). c. Select WebSphereCommerceServer, and right-click Start. Note: We started the WebSphereCommerceServer last to ensure the console shows the WebSphere Commerce messages. Atlernatively, you can switch between the console output for the servers within the Debug perspective in WebSphere Studio Application Developer V5.0.1. WebSphere Studio Application Developer V5.1 contains a new feature to switch console output directly in the console view in the J2EE and Server perspectives. 5. Launch the WebSphere Commerce Administration Console: a. Open Microsoft Internet Explorer. 386 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: Do not use the internal browser in WebSphere Studio Application Developer to log on to the WebSphere Commerce administration tools. This will not work, because each tool opens in a new window, which causes problems with the internal WebSphere Studio Application Developer browser. For more information refer to “Configure the default Web browser” on page 1027. b. Enter the following URL in the Address field (on a single line): https://localhost:9443/webapp/wcs/admin/servlet/ToolsLogon? XMLFile=adminconsole.AdminConsoleLogon 6. Click Yes if an Internet Explorer security warning is displayed. 7. Log on using the site administrator ID and password you supplied when installing WebSphere Commerce Studio (for example, wcadmin). 8. Select Site and click OK. 9. Select Store Archives -> Publish. 10.Select the check box next to ITSO.sar and click Next. 11.From the Parameters page, change the values for Store directory and Store identifier to suit your store and click Next. In our example, we accepted the default values of ITSO. 12.From the Summary page, review the parameter values and click Finish. 13.A confirmation window should appear informing you that the store archive was submitted for publishing. Click OK. 14.The Publish Status window will appear. Select the check box in the line for the store archive that was just submitted for publishing and click Details. 15.The Publish Details window will appear. This window will automatically refresh every 20 seconds. The publishing process is finished when the status changes from Publishing to Successful. 12.6.5 Verify customized store in the WebSphere Test Environment At this point, we have published a sample store model with basic customizations. Before proceeding, the store should be tested to check for any obvious errors or omissions. If a new locale has been added, it should be tested if it is possible to change to that locale, it should be tested to see if new taxes or shipping providers work as expected, and so on. Chapter 12. Create a store 387 12.7 Add the store front files to CVS Note: You can skip this section if you do not wish to use source control. In 12.3, “Import store assets into CVS” on page 350 we imported the core projects and added the files that need to be under source control to the CVS repository. At that time the Stores project did not contain the store-specific files that were published in 12.6.4, “Publish the store archive to the workspace” on page 385. To add the store front files to CVS, do the following: 1. Change to the Resource perspective in WebSphere Studio Application Developer. 2. Expand the Stores project and the Web Content folder. 3. Right-click the folder matching the store directory chosen during publish. In our case it is ITSO. 4. Select Team -> Add to Version Control. 5. Right-click the same folder and select Team -> Commit. 6. Enter a comment ,such as First time import of store directory, and click OK. WebSphere Studio Application Developer will now add the files to the repository. 7. Repeat steps 3–6 above for the folder Stores/Web Content/WEB-INF/classes/ITSO. 12.8 Set up additional team development nodes Note: This section can be skipped if you are not using source control. The previous sections have all focused on the work involved in setting up the initial store and development environment. In this section we describe how to set up additional Development nodes. The following steps are assumed to be performed on Development nodes with a pristine installation of WebSphere Commerce Studio. 388 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 12.8.1 Turn off directory pruning The projects that were put under source control contain a number of empty directories. In order to restore these empty directories on the target Development node, we need to turn off a feature of CVS that prevents empty directories from being created when checking out files from the repository. To turn off directory pruning, do the following: 1. Open WebSphere Commerce Studio. 2. Select Window->Preferences. 3. Expand Team and select CVS. 4. Ensure that the check box next to Prune empty directories is not checked. 5. Click OK. Note: The Prune empty directories feature is very useful during the regular development cycle, because CVS actually never deletes a directory from the repository. We recommend that you turn this feature back on once you have started the development cycle and added code to the two extension projects. 12.8.2 Checking out the projects The project that was added to the repository in 12.3, “Import store assets into CVS” on page 350 must be checked out on the developer machines to ensure that all the developers work on the same code base. In WebSphere Commerce Studio, this is done in a similar fashion to the original import: 1. Change to the Resources perspective in WebSphere Studio Application Developer. 2. Right-click the Stores project and select Team->Share Project. 3. The Share Project wizard opens. Enter the CVS connection details as they apply to your environment. Click Finish. 4. The Remote Project Exists window will appear, asking if you wish to synchronize with the existing remote module. Click Yes as seen in Figure 12-6 on page 390. Chapter 12. Create a store 389 Figure 12-6 Warning about existing remote project 5. The Select Tag window will open. Select HEAD and click OK as seen in Figure 12-7. Figure 12-7 Selecting the branch to synchronize with Important: We do not recommend that you check out the files using the Check Out As Project context menu item in the CVS Repository Exploring perspective when customizing WebSphere Commerce. That would replace the existing project with the contents of the projects in the repository instead of synchronizing the files. Synchronize with repository At this point, WebSphere Commerce Studio has made a link between the local Stores project and the remote Stores CVS module, but no files have been synchronized. To synchronize the files, do the following: 1. Right-click the Stores project and select Team->Synchronize with Repository. 2. This will open the Synchronize - Incoming Mode window, if it is not already open, and show the Stores directory structure. If the Synchronize window is 390 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Outgoing mode, then click the Incoming Mode button in the title bar of the window as seen in Figure 12-8. Figure 12-8 Synchronize window in Incoming Mode 3. Right-click the Stores folder in the Synchronize pane and select Override and Update to synchronize all CVS files in the project as seen in Figure 12-9. Figure 12-9 Select Override and Update to get all CVS files synchronized Repeat the above steps for the following projects: – WebSphereCommerceServerExtensionsData – WebSphereCommerceServerExtensionsLogic Chapter 12. Create a store 391 Check out the Packaging project The above steps ensure that the team members are using the source controlled versions of the customized projects in WebSphere Commerce Studio. Since the Packaging project will be needed during the build cycle, this project must also be checked out from CVS: 1. Change to the CVS Repository Exploring perspective in WebSphere Studio Application Developer by selecting Window -> Open Perspective -> CVS Repository Exploring. 2. The repository selected previously should show as a location using the following syntax: ::@:, for example: :pserver:nielsen@bottom440:/repo. 3. Expand the Repository Location. 4. Expand the node HEAD. 5. Right-click Packaging and select Check Out As Project. 12.8.3 Package and publish data-only store archive The previous steps have focused on synchronizing the local store file assets with the developer machines, but the database of the developer machine is still unchanged. To deploy the database assets of the store, we will create a special version of the store archive without any store front assets. The instructions in this section should be repeated during the build cycle whenever the developer has modified database assets for the store: 1. Change to the Resources perspective in WebSphere Studio Application Developer. 2. Expand the SARFile project. 3. Right-click build.xml and select Run Ant. 4. Ensure that the only selected target is build-sar-no-storefront. 5. Ensure that the -DSTOREDIR=ToolTech argument is not specified. 6. Click Finish. 7. A store archive called ITSO.sar is created in the root of the SARFile project (you may have to refresh the project to see the file in WebSphere Studio Application Developer). Copy this file to the directory: \Commerce\instances\\sar. 8. Publish the store archive as described in 12.6.4, “Publish the store archive to the workspace” on page 385. 392 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 13 Chapter 13. Customize a store: Price Watch example This chapter contains the technical design for the Price Watch example along with details on how to implement it. The topics covered in this chapter include the building of custom database tables, custom commands, entity and access beans, data beans, and JavaServer Pages. Also covered are building a custom e-mail message and using the WebSphere Commerce scheduler to run a command that sends e-mails to the user. Detailed steps for using WebSphere Commerce Studio to build the example are given along with many useful hints and tips to help make customizing your store more efficient and simple. Where appropriate, possible decisions that must be made are explained and guidelines are highlighted. The chapter is organized into the following sections: 1. 2. 3. 4. 5. 6. 7. 8. Overview Solution design Price Watch example pre-conditions Configuring the e-mail transport and SMTP server Creating the new database table Creating the new data access beans Creating the new commands Creating the new data bean © Copyright IBM Corp. 2003. All rights reserved. 393 9. Creating the new JavaServer Pages 10.Creating the batch e-mail command 11.Importing the e-mail template 12.Configuring the scheduler to run the batch job 13.1 Overview This chapter describes the procedure for implementing the Price Watch example. This example section is divided into the following tasks: 1. Solution Design. 2. Creating the new database table. 3. Creating the new data access beans for accessing the new database table. This involves creating an Entity bean and an Access bean. 4. Creating the new commands. Both controller commands and task commands will be used. 5. Creating the new Data beans, which will be used to pass results from the commands to the JSPs (Java Server Pages). 6. Creating the new JSPs. These will provide the user interface for the new functionality within your site. 7. Creating the batch e-mail command. This will run on a schedule to check the prices of the products selected by the users and e-mail notifications accordingly. 8. Creating the e-mail template JSP that will form the basis for the e-mail sent to the users. 9. Configuring the e-mail transport for sending outgoing e-mail and configuring a lightweight SMTP server to act as a mail gateway. 10.Configuring the WebSphere Commerce scheduler to run the batch command. 13.2 Solution design This section contains the technical design for the Price Watch example. The design in this document is not complete, but contains enough information to describe the solution for the purposes of this example. It is not intended to be a guide for writing technical design documents. 394 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 13.2.1 Use cases This section contains a summary of the use cases for the Price Watch example. Only the operational (runtime) cases are included. The use cases listed here do not represent the full set of possible use cases, only those that are sufficient to describe the scenario for our example. For example, cases that handle error conditions are not described, because they are not specific to our example. The detailed use cases can be found in 9.2.4, “Use case model” on page 301. UC-PW01 Display Price Watch list UC-PW02 Add items to Price Watch list UC-PW03 Delete item from Price Watch list UC-PW04 Delete all items from Price Watch list UC-PW05 Schedule job checks Price Watch list and e-mail customers 13.2.2 Solution overview The solution consists of the following assets: A database table – XPRICEWATCH An entity bean (and associated access bean) – XPriceWatch Controller commands – PriceWatchListDisplay – ManagePriceWatchList – CheckPriceWatchPrices Task commands – – – – PriceWatchList PriceWatchAdd PriceWatchDelete PriceWatchDeleteAll Data beans – PriceWatchBean – PriceWatchEmailBean JavaServer Pages (JSPs) – PriceWatchList.jsp – PriceWatchEmail.jsp Chapter 13. Customize a store: Price Watch example 395 13.2.3 Solution limitations This section explains the limitations of the technical solution. These limitations were not overlooked; the steps required to correct them were deemed to be out of scope for this book. Where appropriate, suggested solutions to these limitations are given, but not explained in detail. Sites with multiple catalogs are not supported. The price watch prices are assumed to be correct for the user’s current currency. No historical data regarding price watch items is retained, since entries in XPRICEWATCH are deleted when the e-mail is sent to the customer. 13.2.4 Data storage Our design requires a new table for storing price watch data. Each price watch price is associated with the user who created the watch and also the product and contract to which the price watch belongs. This new table is to be called XPRICEWATCH. Tip: It is good practice to begin the names of any new tables that you create with an X. This visually distinguishes your custom tables from the predefined WebSphere Commerce tables. When developing or maintaining code, having this visual indication helps you understand how the business logic has been implemented. An example of this would be if you needed to store more address information for a user than is catered for by default. It would be logical to create a table called XADDRESS to store this extra information. If you decide to extend the existing entity bean (see Chapter 13 in the Programming Guide and Tutorials, IBM WebSphere Commerce V5.5) for ADDRESS to include this new table, it would be clearer that the two tables are related to this naming convention. The XPRICEWATCH database table is defined in Table 13-1. Table 13-1 XPRICEWATCH table 396 Column name Column type Description MEMBERID BIGINT User that the price watch belongs to CATENTRY_ID BIGINT Item to which the price watch belongs CONTRACT_ID BIGINT Contract used to determine item price WATCHPRICE DECIMAL(20,5) Price at which user would purchase item WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: When designing new tables that have foreign key relationships with existing WebSphere Commerce tables, it is important to match the data types correctly. For the sake of continuity, it is still advisable to match the data types to those used in WebSphere Commerce even if the fields have no direct relationship. The primary key consists of the MEMBERID, CATENTRY_ID and CONTRACT_ID columns. All three of these columns are required to uniquely identify an individual watch price, since each user may have multiple entries with possibly more than one being for a single item (if more than one contract is offered). The constraints for this table are described in Table 13-2. Table 13-2 Constraints for XPRICEWATCH Column name Foreign table name Foreign column name Constraint type MEMBERID USERS USERS_ID Cascade CATENTRY_ID CATENTRY CATENTRY_ID Cascade CONTRACT_ID CONTRACT CONTRACT_ID Cascade These constraints ensure that if the user, item, or contract that this price watch belongs to is deleted, the price watch is also removed, since it is no longer valid. 13.2.5 Data access (entity bean) In order to access the XPRICEWATCH table, a CMP (Container Managed Persistence) entity bean is required. It is good practice to give the entity bean the same name as the underlying table, so it will be named XPriceWatch. The entity bean should have the mapping between the CMP fields and the database table columns shown in Table 13-3. Table 13-3 EJB to RDB mapping for entity bean CMP field name CMP field type Database column name Database column type memberId Long MEMBERID BIGINT catEntryId Long CATENTRY_ID BIGINT contractId Long CONTRACT_ID BIGINT watchPrice java.math.BigDecimal WATCHPRICE DECIMAL(20,5) Chapter 13. Customize a store: Price Watch example 397 This mapping is known as an EJB (Enterprise Java Bean) to RDB (Remote DataBase) mapping. Note that in DB2, all price data is stored using the DECIMAL(20,5) type. In order to be able to select particular rows from the table, a number of FinderHelper methods must be created (see 13.6.1, “Create the entity bean” on page 409 for more details). FinderHelpers are required that perform the following: Select a single watch price for a known user, item, and contract. Select all entries for a particular user. This is required for the purposes of displaying the Price Watch list page. Select all entries for all users. This is required for the scheduled command in order for it to process each price watch in turn. 13.2.6 Controller commands This section details the necessary controller commands that are required for implementing the solution. PriceWatchListDisplayCmd This command will be called by the user when the price watch list is to be displayed. The logic in this command corresponds to use case UC-PW01. The following is a summary of the command logic: 1. Use the PriceWatchList task command to retrieve the list for the specified user. 2. Pass the list (stored in a PriceWatchBean object; see 13.2.8, “Passing data to the JSP” on page 400) to the JSP for display. ManagePriceWatchListCmd The logic in this command corresponds to use cases UC-PW02 to UC-PW04. This command will be called by the user in order to perform one of the following actions: Add a new price watch entry to their list (PriceWatchAddTaskCmd) Update a price watch entry in their list (PriceWatchAddTaskCmd) Delete a price watch entry from their list (PriceWatchDeleteTaskCmd) Delete all the price watch entries in their list (PriceWatchDeleteAllTaskCmd) The action taken will depend on the value of the action parameter that is passed to the command when it is executed. Depending on the action to be performed, the appropriate task command will be executed by the controller command. 398 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide These task commands are shown in brackets in the above list. These task commands are detailed in 13.2.7, “Task commands” on page 399. Additionally, the PriceWatchList task command will be called to retrieve the new list before displaying the price watch list JSP, as in the PriceWatchListDisplay command. CheckPriceWatchPricesCmd The logic in this command corresponds to use case UC-PW05. This command will be executed by the scheduler at an interval set by the store administrator. This command should perform the following: 1. Acquire the list of all price watch items from the XPRICEWATCH table using the XPriceWatch bean. 2. For each item in the list: a. Find the price of the item for the given contract. The GetContractUnitPriceCmd task command can be used. This command should be passed the catEntryId and contractId for the price watch item and the item price should be retrieved. b. Find the watch price chosen for the item using the XPriceWatch bean. c. If the item price is less than the price watch price, e-mail the associated user to inform them. The AddressAccessBean can be used to retrieve the user’s name and e-mail address. d. If an e-mail was sent, delete the price watch entry from the table. 3. Exit the command without forwarding to a JSP, since the command is to be run by the scheduler. To send the e-mail, the SendMsgCmd command can be used. For more details on the use of this command, please refer to 13.10, “Creating the batch e-mail command” on page 482. 13.2.7 Task commands This section details the necessary task commands that are required for implementing the solution. PriceWatchListTaskCmd This task command should instantiate the PriceWatchBean data bean and populate it with the price watch items for the currently logged on user, or for the user ID passed to the command. The XPriceWatch bean should be used to retrieve the data from the database. Chapter 13. Customize a store: Price Watch example 399 PriceWatchAddTaskCmd This task command should add a price watch entry to the XPRICEWATCH table or update an entry if one already exists for the given user, item, and contract. The logic should be implemented as follows: 1. Check if an entry already exists in the table. This can be done by using the XPriceWatch bean and catching the FinderException that occurs when no row exists for the given key. 2. If no row exists, create a new row with the given data. 3. If a row exists, update the row using the instance of the access bean returned in step 1. Nothing is returned from this command. PriceWatchDeleteTaskCmd This command should delete a price watch entry from the XPRICEWATCH table. The entry to delete is determined by the user, contract, and item IDs passed to the command. The XPriceWatch bean can be used to first find the entry and then to remove it. PriceWatchDeleteAllTaskCmd This command should use the XPriceWatch bean to delete all entries in the XPRICEWATCH table for a specified user. This must be done by retrieving a collection of the XPriceWatch beans, one for each entry, and then deleting them in turn. 13.2.8 Passing data to the JSP This section will discuss data beans and their various forms. What is a data bean for? A data bean is an object that provides easy access to data from within a JSP. A data bean can be used to: Access data which is generated during the execution of a command Retrieve data from the database (through the use of access beans) It is possible to create a data bean that does both of the above, but it is not good practice to do so. If it seems necessary to combine database access with the storage of results from a command, you may consider using two separate data beans. For further details about data beans, please refer to 13.8, “Creating the new data bean” on page 463. 400 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide The price watch data bean For our solution, we simply require a means of passing the price watch list data from the controller commands to the JSP. A simple data bean is required to achieve this. This data bean will be called PriceWatchBean. The data bean must contain the following data: An ordered list of the catalog entry IDs An ordered list of the contract IDs An ordered list of the watch prices For any given index value, the values in these lists should correspond to the price watch entry for that index. The price watch e-mail data bean To pass the dynamic contents of the price watch customer notification e-mail to the JSP e-mail template, a data bean called PriceWatchEmailBean will be needed. The data bean must contain the following data: The first name of the user to whom the e-mail is being sent The price watch item’s catalog entry ID. This will be used to retrieve details about the item for display in the JSP. The list price of the item. Note that this could be retrieved in the JSP by using a WebSphere Commerce data bean, but the value is already retrieved in the command so it is more efficient to just pass it on to the JSP. The price watch price for the item. 13.2.9 Price watch list page JSP The page layout should consist of the header and sidebar as per the other pages. The main content should consist of: The price watch list table as shown in Table 13-4. The table shown contains sample data and the remove link for each row. Table 13-4 Layout of price watch list table SKU Product Price Watch Price 12345678 Sample Product 599.99 580.00 Remove 87654321 Another Product 450.00 400.00 Remove A Remove All button. This button will link to the ManagePriceWatchList command, passing the cmdAction=deleteall parameter. If no there are no entries in the list, a message stating this would replace the table. Chapter 13. Customize a store: Price Watch example 401 13.2.10 E-mail template JSP The layout of the e-mail will be as shown in Example 13-1. Example 13-1 Layout for the price watch notification e-mail Dear , An item in the ITSO Store has a new price that is below your price watch limit!!! Item: New Price: Your Watch Price: Visit the store now to buy this item!! The PriceWatchEmailBean should be used to retrieve all the required fields from the CheckPriceWatchPrices command. 13.2.11 Access control The command level access control policies for the user-executed commands should be set to allow access to all site users. This includes the PriceWatchListDisplay and ManagePriceWatchList commands. The CheckPriceWatchPrices command does not require an access control policy because it will only be executed by the site administrator (that is, the user assigned to the command in the scheduler). By default, the site administrator has authority to run any command. 13.3 Price Watch example pre-conditions The Price Watch example requires that the following tasks have been completed: 1. WebSphere Commerce Studio has been installed and configured. For details on setting up a team development environment, refer to Chapter 11, “Implement a team development environment” on page 323 for details. The team environment includes WebSphere Commerce Studio. 402 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: You must complete the post-install tasks for messaging found in the Installation Guide, IBM WebSphere Commerce Studio V5.5 product guide. In addition, complete the steps in technote 1114621 every time prior to restarting the WebSphere Commerce server within WebSphere Studio Application Developer. 2. Either the B2BDirect.sar (ToolTech) or the ITSO.sar has been published within the WebSphere Commerce Studio workspace. For details on creating and publishing a store to the WebSphere Commerce Studio workspace, refer to Chapter 12, “Create a store” on page 341. 13.4 Configuring the e-mail transport and SMTP server This section describes how to set up the e-mail transport in WebSphere Commerce. A new message type must be created in the database for our Price Watch example. Also, the Administration Console must be used to configure the transport. This section also describes how to set up a free SMTP server for use with the example. If you already have an SMTP server or do not wish to use the software suggested, please proceed directly to 13.4.2, “Adding the new message type to the database” on page 403. 13.4.1 Setting up the James SMTP server For details on setting up the Java Apache Mail Enterprise Server (also known as Apache James) refer to 21.7.1, “Java Apache Mail Enterprise Server (James) configuration” on page 950. 13.4.2 Adding the new message type to the database To add a new message type for our e-mail message, complete the following steps: 1. Ensure the DB2 Server is started on the development node. 2. Open the DB2 Command Center by selecting Start -> Programs -> IBM DB2 -> Command Line Tools -> Command Center. 3. Click the Interactive tab. Chapter 13. Customize a store: Price Watch example 403 4. Connect to your development database by entering the following in the Interactive window: connect to user using where – is the database name. If you created your database with a different name when you installed WebSphere Commerce Studio, substitute that name here. – is your DB2 user name. – is the password for your DB2 user. Press Ctrl + Enter or click the Execute button on the tool bar. The bottom pane should show a message confirming that the SQL ran successfully. 5. Enter the SQL shown in Example 13-2 in the Interactive window. Example 13-2 SQL to create PriceWatchNotificationEmail message type insert into msgtypes (DESCRIPTION, MSGTDIR, MSGTYPE_ID, NAME, VIEWNAME) values ( 'E-mail message for notification of Price Watch price matches', 1, 800, 'PriceWatchNotificationEmail', 'PriceWatchNotificationEmailView' ) Note: DB2 script for Price Watch example Throughout the Price Watch example, we reference DB2 command and SQL scripts that need to be run. We have included a script called db2_build.sql in the c:\6969code\pricewatch directory. Before starting to make the database changes in this chapter, you may wish to make a backup of your WebSphere Commerce instance database. This will allow you to easily return to the default state if you make a mistake. Refer to “DB2 backup and restore” on page 988 for details on how to do this. The db2_build.sql command can be run now and will execute all DB2 scripts referenced throughout the chapter. db2 connect to user using db2 -tvf db2_build.sql 404 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 6. Press Ctrl + Enter. The bottom pane should show a message confirming that the SQL ran successfully. 13.4.3 Configuring the e-mail transport To configure the e-mail transport, complete the following steps: 1. Switch to the J2EE perspective within WebSphere Commerce Studio. 2. In the Servers view, start the WebSphereCommerceServer server. 3. Open a browser window and start the Administration Console using the following address: https://localhost/webapp/wcs/admin/servlet/ToolsLogon?XMLFile=adminconsole. AdminConsoleLogon 4. Log on to the Administration Console. 5. Select Site and click OK. 6. Select Configuration -> Transports. 7. Click E-Mail in the transports table. 8. In the Host entry in the table, enter the address of the server on which your SMTP server is running. If it is running on the same machine as WebSphere Commerce Application Developer, then use localhost. 9. Click OK. 10.Confirm that the status of e-mail transport is Active. If it is not, complete these steps: a. Check the box next to E-Mail. b. Click Change Status. 13.4.4 Configuring the e-mail message type To configure the e-mail message type, do the following: 1. From the WebSphere Commerce Administration Console, click Configuration -> Message Types. 2. Click New. 3. In the Message Type list, select PriceWatchNotificationEmail. 4. In the Message Severity text boxes, enter 0 in both. 5. Select E-Mail from the Transport list. 6. Select Standard Device Format from the Device Format list. Chapter 13. Customize a store: Price Watch example 405 7. Click Next. The settings on this page will be set at command runtime, so leave all values as the default. 8. Click Finish. 9. Click Logout to exit the Administration Console. 13.5 Creating the new database table It is logical to start the implementation by dealing with the data. Before any beans can be created or any business logic can be implemented in commands, it is necessary to have somewhere to store the data we will be manipulating. Note: If you have already run the db2_build.sql script, continue to 13.6, “Creating the new data access beans” on page 408. In order to create the new table in the database, complete the following steps: 1. Open the DB2 Command Center by clicking Start -> Programs -> IBM DB2 -> Command Line Tools -> Command Center. 2. Click the Interactive tab. 3. Connect to your development database by entering the following in the Interactive window: connect to user using where – is the database name. If you created your database with a different name when you installed WebSphere Studio Application Developer, substitute that name here. – is your DB2 user name. – is the password for your DB2 user. Press Ctrl + Enter or click the Execute button on the tool bar. 406 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 13-1 Connecting to the database in DB2 The bottom pane should show a message confirming that the SQL ran successfully. 4. Create the new table called XPRICEWATCH. Enter the SQL shown in Example 13-3 on page 408 in the Interactive window. Chapter 13. Customize a store: Price Watch example 407 Example 13-3 SQL for creating the XPRICEWATCH table create table XPRICEWATCH ( MEMBERID BIGINT NOT NULL, CATENTRY_ID BIGINT NOT NULL, CONTRACT_ID BIGINT NOT NULL, WATCHPRICE DECIMAL(20,5) NOT NULL, constraint p_memberid primary key (MEMBERID, CATENTRY_ID, CONTRACT_ID), constraint f_memberid foreign key (MEMBERID) references users (users_id) on delete cascade, constraint f_catentry_id foreign key (CATENTRY_ID) references catentry (catentry_id) on delete cascade, constraint f_contract_id foreign key (CONTRACT_ID) references contract (contract_id) on delete cascade ) 5. Press Ctrl + Enter. The bottom pane should show a message confirming that the SQL ran successfully. Tip: Leave your DB2 Command Center window open because you will need it again in the following sections. 13.6 Creating the new data access beans Now that the table has been created, we can create the entity bean and access bean that we will use to access the table from within our commands. The next steps describe how to create the beans in WebSphere Commerce Studio. Note: WebSphere Commerce Studio or WebSphere Studio Application Developer In this book, and in the WebSphere Commerce product documentation, you will see references to WebSphere Commerce Studio and WebSphere Studio Application Developer. WebSphere Commerce Studio is the name of the development environment shipped with WebSphere Commerce. It consists of WebSphere Studio Application Developer and a specific workspace with additional tooling for WebSphere Commerce development. In this book, depending on context, you will see references to both. The entity bean we are about to create will henceforth be known as the XPriceWatch bean. 408 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 13.6.1 Create the entity bean In this section we will create an entity bean for the XPRICEWATCH database table. Create entity bean To create the entity bean, complete the following steps: 1. If you have not already done so, start WebSphere Commerce Studio by clicking Start -> Programs -> IBM WebSphere Commerce Studio -> WebSphere Commerce development environment. 2. Open the J2EE perspective. 3. Within the J2EE Hierarchy, expand EJB Modules. 4. Right-click the WebSphereCommerceServerExtensionsData module and select New -> (Other ->) Enterprise Bean. 5. On the Enterprise Bean Creation Select page, select WebSphereCommerceServerExtensionsData (default) and then click Next. 6. On the Create an Enterprise Bean page, do the following as seen in Figure 13-2 on page 410: a. Select Entity bean with container-managed persistence (CMP) fields. b. In the Bean name text box, enter XPriceWatch Note: The bean name should always be the same as the table name it accesses unless you have good reason to do otherwise. This makes your projects easier to maintain. Note also that the name does not require the word “Bean” on the end as this is added automatically by the wizard. c. In the Default package text box, enter com.ibm.itso.sample.ejb d. Click Next. The Enterprise Bean Details window will now be displayed. We will now add the CMP attributes to the bean. We must create one CMP attribute for each column in the XPRICEWATCH database table. Chapter 13. Customize a store: Price Watch example 409 Figure 13-2 Create an Enterprise Bean: Bean type and name 7. On the Enterprise Bean Details page, click the Add button next to the CMP Attributes box. 8. When the Create CMP Attribute window appears, do the following: a. In the Name text box, enter memberId. b. In the Type text box, enter java.lang.Long. In this case, the Java type Long is equivalent to the DB2 type BIGINT. Important: It is important to map to the correct Java type; otherwise, errors can occur when you use your beans. Also, you must always use the object type and not the primitive (for example, java.lang.Long, not long). This is important because a primitve cannot have a null value. If the database query returns a null value, it cannot be assigned to the CMP variable and will cause an error. c. The MEMBERID field in the database forms part of the primary key for the XPRICEWATCH table. Indicate this by selecting the Key Field check box. You will notice that the last three boxes will be disabled. 410 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 13-3 Create CMP Attribute for MEMBERID field d. Click Apply to add the CMP Attribute as seen in Figure 13-3. The attribute will be added to the bean. The window will clear and remain open so that you can add further attributes. 9. On the Create CMP Attribute page, do the following: a. In the Name text box, enter catEntryId. b. In the Type text box, enter java.lang.Long. c. CATENTRY_ID also forms part of the primary key, so select Key Field. d. Click Apply to add the CMP Attribute. 10.On the Create CMP Attribute page, do the following: a. In the Name text box, enter contractId. b. In the Type text box, enter java.lang.Long. c. CONTRACT_ID also forms part of the primary key, so select Key Field. d. Click Apply to add the CMP Attribute. 11.On the Create CMP Attribute page, do the following: a. In the Name text box, enter watchPrice. b. In the Type text box, enter java.math.BigDecimal. c. Make sure that Key Field is not selected. The last three check boxes should be checked as seen in Figure 13-4 on page 412. Chapter 13. Customize a store: Price Watch example 411 Figure 13-4 Create CMP Attribute for WATCHPRICE field d. Click Apply to add the CMP Attribute. e. Click Close. The window will close and you will be returned to the Enterprise Bean Details window. Note that the three CMP fields you added are displayed as seen in Figure 13-5 on page 413. 412 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 13-5 Enterprise Bean Details 12.On the Enterprise Bean Details window, leave all the other settings as their default values and click Next. 13.We now need to specify the superclass for the bean. Click Browse on the EJB Java Class Details page. 14.In the Select a class using: (any) text box, enter ECEntityBean. All Entity beans must extend this class. You will see in the Matching Types and Qualifier lists the class with the name you have entered. There is only one in the list in this case. In cases where more than one package has a class by the name you entered, you can use this to select the exact class you wish to subclass. 15.Make sure that com.ibm.commerce.base.objects.ECEntityBean is selected and click OK. Chapter 13. Customize a store: Price Watch example 413 16.We now need to specify what interfaces the remote interface should extend. Click Add. Once again, the Type Selection window will open. 17.In the Select a class using: (any) text box, enter Protectable. This interface must be implemented in order for the bean to be protected using Access Control. 18.Make sure that com.ibm.commerce.security.Protectable is selected and click OK. 19.Click Finish to create the bean. You will see that the XPriceWatch bean has now been created in the J2EE Hierarchy (see Figure 13-6). Figure 13-6 The XPriceWatch bean is now visible in the J2EE Hierarchy 414 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Bean configuration Now we need to configure the new bean so that it can be used in WebSphere Commerce Server. To do this, complete the following steps: 1. Double-click the WebSphereCommerceServerExtensionsData project. If it is not visible, open the J2EE Hierarchy and then expand EJB Modules first. The EJB Deployment Descriptor will now open as seen in Figure 13-7. Figure 13-7 EJB Deployment Descriptor 2. Click the Access tab. 3. In the Isolation Level section, click Add as seen in Figure 13-7. The Add Isolation Level window will open. 4. Make sure that Repeatable Read is selected and click Next. 5. Check the XPriceWatch bean from the Beans found list and click Next. 6. Check the XPriceWatch bean to select all of its methods. The XPriceWatch item will expand and all of the methods will turn grey. 7. Click Finish. Chapter 13. Customize a store: Price Watch example 415 Set security identity of the bean Next, we must set the security identity of the bean. This is also done on the Access tab of the Deployment Descriptor as follows: 1. Click Add next to the Security Identity list. 2. Select Use identity of EJB server from the Run as mode group and click Next. 3. Check the XPriceWatch bean in the Beans found list and click Next. 4. Check the XPriceWatch bean to select all of its methods. The XPriceWatch item will expand and all of the methods will turn grey. 5. Click Finish. 6. Make sure that the EJB Deployment Descriptor window is active and then press Ctrl+S to save your work. Remove uneeded methods At this point, we must remove some of the fields and methods that WebSphere Commerce Studio generated when the bean was created. Remember that when we created the bean earlier, we extended the ECEntityBean class. This class already has implementations of these fields and methods that we should not override. To remove these fields and methods from the XPriceWatch bean, complete the following steps: 1. Expand the WebSphereCommerceServerExtensionsData project. If it is not visible, open the J2EE Hierarchy and then expand EJB Modules first. 2. Expand the XPriceWatch bean and then double-click the XPriceWatchBean class to open the editor. You can see where the class resides in the class source editor window in Figure 13-8 on page 417. 416 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 13-8 Open the XPriceWatch bean class for editing 3. In the Outline view (see Figure 13-9 on page 418), select the following four members by clicking the first one and then holding the Ctrl key and clicking the other three: – – – – myEntityCtx getEntityContext() setEntityContext(EntityContext) unsetEntityContext() Right-click one of the selected members and select Delete from the menu. Tip: When dealing with large classes, sometimes it is not easy to locate the methods you require in the Outline view. To make it easier, you can sort the methods by clicking the sort icon in the Outline view title bar. This does not affect the source code. Chapter 13. Customize a store: Price Watch example 417 Figure 13-9 Delete the entity context members from the XPriceWatchBean class 4. Make sure that the XPriceWatchBean.java window is active and then press Ctrl+S to save your work. Create accessors for key fields By default, when an Entity bean is created, accessors (getters and setters) are not created for any CMP fields that were created as key fields. In most cases, this is acceptable, since the value of the key is usually known when a bean is used to access rows in the database. In some circumstances, for example when a bean has multiple finders and the key is not needed for one of them, you may wish to retrieve the key value(s) from the results. To achieve this, we must add a getter method for each element of our key to the bean. To do this, complete the following steps: 1. Expand the WebSphereCommerceServerExtensionsData project. If it is not visible, open the J2EE Hierarchy and then expand EJB Modules first. 2. Expand the XPriceWatch bean and then double-click the XPriceWatchBean class to open the editor. 418 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 3. In the outline view, right-click the memberId field and select Generate Getter and Setter from the menu. The Generate Getter and Setter window will open. Whichever field you right-clicked will have both the getter and setter selected in the Select Methods to Create in Type list. 4. Uncheck the setCatEntryId(Long), setContractId(Long) and setMemberId(Long) methods. 5. Check the getCatEntryId(), getContractId() and getMemberId() methods. The window should appear as in Figure 13-10. Figure 13-10 Settings for generating the getters and setters 6. Click OK. You will see that the code has been generated in the source view. This is shown in Figure 13-11 on page 420. Chapter 13. Customize a store: Price Watch example 419 Figure 13-11 Source code generated by the Generate Getters and Setters wizard Promote new methods to the remote interface Next, we need to promote our new methods to the remote interface so that they will be accessible to us when we use the bean. To do this, complete the following steps: 1. In the outline view, select the getCatEntryId(), getContractId() and getMemberId() methods. 2. Right-click one of the methods and select Enterprise Bean -> Promote to Remote Interface from the menu. You will notice that in the outline view that the two method names now have a small R next to them. This indicates that they have been promoted to the remote interface. 3. Save your work by pressing Ctrl+S. Do not close the XPriceWatchBean.java window, because you will be working on it in the step. 420 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Create a new ejbCreate method When a new row in the database table is to be added using the bean, the ejbCreate method is used. In practice we would of course use the Access bean wrapper rather that the Entity bean itself, but behind the scenes, it is this method that is called. By default, the ejbCreate method that is generated by WebSphere Studio Application Developer only has parameters for the fields that form part of the primary key. This method cannot be used in this case, since the WATCHPRICE column in our table cannot contain null values. When the method is called, the values passed for memberId and catEntry would be used when the bean inserts the row. However, the watchPrice value is not specified and so would be defaulted to null. Because this is not allowed in our table, an error would result. The next step is to create a new ejbCreate method that allows us to specify values for all of the fields in XPRICEWATCH. A corresponding ejbPostCreate method must also be added. To do this, complete the following steps in this order: 1. Make sure that the XPriceWatchBean.java window is selected. 2. Right-click the ejbCreate(Long,Long,Long) method in the Outline view and select Copy from the menu. 3. Right-click again, and select Paste. You will see that you now have two ejbCreate(Long,Long,Long) methods in the Outline view and the source code. 4. Select one of the ejbCreate(Long,Long,Long) methods from the Outline view. It doesn’t matter which one. The source code will jump to this method and the method name will be highlighted in the code. 5. In the source code for the method, add the following parameter to the method: java.math.BigDecimal watchPrice 6. Also, add the following line to set the class variable for watchPrice: this.watchPrice = watchPrice; The method should now look like Example 13-4. Example 13-4 New ejbCreate method for XPriceWatch bean public com.ibm.itso.sample.ejb.XPriceWatchKey ejbCreate( java.lang.Long memberId, java.lang.Long catEntryId, java.lang.Long contractId, java.math.BigDecimal watchPrice) throws javax.ejb.CreateException { Chapter 13. Customize a store: Price Watch example 421 _initLinks(); this.memberId = this.catEntryId this.contractId this.watchPrice return null; memberId; = catEntryId; = contractId; = watchPrice; } 7. Save your work by pressing Ctrl+S. 8. Before the new method will be accessible it must be added to the home interface. In the Outline view, right-click ejbCreate(Long,Long,Long,BigDecimal) and select Enterprise Bean -> Promote to Home Interface. You will notice that an H has appeared next to the method name in the Outline view to denote that the method has been promoted to the home interface. 9. Right-click the ejbPostCreate(Long,Long,Long) method in the Outline view and select Copy from the menu. 10.Right-click again, and select Paste. 11.Select one of the ejbPostCreate(Long,Long,Long) methods from the Outline view. It doesn’t matter which one. 12.In the source code for the method, add the following parameter to the method: java.math.BigDecimal watchPrice The method should now look like Example 13-5. Example 13-5 New ejbPostCreate method for XPriceWatch bean public void ejbPostCreate( java.lang.Long memberId, java.lang.Long catEntryId, java.lang.Long contractId, java.math.BigDecimal watchPrice) throws javax.ejb.CreateException { } 13.Save your work by pressing Ctrl+S. Remove uneeded create methods Now we have an ejbCreate method with the required parameters. Although it would cause no harm to leave it, an additional step will be to remove the ejbCreate(Long,Long,Long) method, because it should not be used for the reasons stated above. It is good practice to not provide methods in classes that will always result in an error. Complete the following steps: 1. Make sure that the XPriceWatchBean.java window is still selected. 422 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 2. In the Outline view, right-click ejbCreate(Long,Long,Long) and select Delete from the menu. Confirm the deletion when prompted. 3. Right-click ejbPostCreate(Long,Long,Long) and select Delete from the menu and confirm the deletion. 4. Save your work by pressing Ctrl+S. 5. Since the ejbCreate(Long,Long,Long) method was promoted to the home interface, we must remove the create method from the XPriceWatchHome class. Double-click the XPriceWatchHome class in the J2EE Hierarchy. The XPriceWatchHome.java source window will open. 6. In the Outline view, right-click create(Long,Long,Long) and select Delete from the menu. Confirm the deletion when prompted. 7. Save your work by pressing Ctrl+S. Create FinderHelper method At this point, we have no method of using our bean to find and return a row in the XPRICEWATCH table. Before we can do that, we need to create a FinderHelper method in the home interface of the bean. FinderHelper methods allow us to specify which of the fields to use as parameters for our database query and how those parameters should be used. The simplest form of a FinderHelper method will accept the key field(s) as a parameter and return an instance of the bean. The returned bean will be populated with the data from the row in the database that corresponds to the key value specified. To add the FinderHelper, complete the following steps: 1. Double-click the WebSphereCommerceServerExtensionsData project. If it is not visible, open the J2EE Hierarchy first. 2. Click the Beans tab. 3. Select the XPriceWatch bean from the Beans list. 4. Scroll down the pane on the right to the WebSphere Extensions section. 5. Next to the Finders list, click Add. The Add Finder Descriptor window will open. 6. Select New. 7. In the Name text box, enter findByMemberIdAndCatEntryIdAndContractId. 8. Click Add next to the Parameters list. a. In the Name text box, enter memberId. b. In the Type text box, enter java.lang.Long. Chapter 13. Customize a store: Price Watch example 423 c. Click OK. 9. To add the second key field, click Add next to the Parameters list. a. In the Name text box, enter catEntryId. b. In the Type text box, enter java.lang.Long. c. Click OK. 10.To add the third key field, click Add next to the Parameters list. a. In the Name text box, enter contractId. b. In the Type text box, enter java.lang.Long. c. Click OK. 11.From the Return Type list, select com.ibm.itso.sample.ejb.XPriceWatch and click Next. 12.From the Finder type list, select WhereClauseFinderDescriptor. 13.In the Finder statement text box, enter: T1.MEMBERID =? AND T1.CATENTRY_ID =? AND T1.CONTRACT_ID =? The Finder statement is used when the source code for the bean is generated. It forms the WHERE clause of the SQL statement used to populate the bean when the FinderHelper method is called. T1 refers to the XPRICEWATCH table in this case. The question marks are replaced at runtime with the values of the parameters passed to the FinderHelper method. This is done in the order that the parameters appear in the method definition. It is therefore important to make sure that the column names in the Finder statement are in the same order as the parameters in the FinderHelper method (findByMemberIdAndCatEntryIdAndContractId defined above). 14.Click Finish. 15.Save your work by pressing Ctrl+S. Create methods for access control You will remember earlier that in order for our bean to support access control, we had to make it implement the Protectable interface. There are two more steps to perform before access control will work properly: 1. Double-click the XPriceWatchBean class to open the source code. 2. At the bottom of the class, before the final closing brace, add the code in Example 13-6 on page 425. 424 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Example 13-6 New getOwner method for the XPriceWatch bean public java.lang.Long getOwner() throws java.lang.Exception { return getMemberId(); } 3. Under the method you just created, add the code in Example 13-7. Example 13-7 New fulfills method for the XPriceWatch bean public boolean fulfills(Long member, String relationship) throws java.lang.Exception { if (relationship.equalsIgnoreCase("creator")) { return member.equals(getMemberId()); } return false; } 4. Save your work by pressing Ctrl+S. 13.6.2 Create the EJB/RDB mapping for the entity bean Now we have completed Entity bean. The next step is to map our bean to the XPRICEWATCH table in the database. This is achieved by creating an EJB to RDB (Remote DataBase) mapping. There are three methods for doing this: Bottom Up: This method will create a new Entity bean and EJB/RDB map from an existing database table. Top Down: This method generates a database schema and EJB/RDB map from an existing bean. Meet In The Middle: This method generates an EJB/RDB map from an existing database table and an existing Entity bean. Since we have already created our table and bean, we need to use Meet-in-the-middle mapping. Create EJB to remote database mapping (RDB) To map the bean to the table, complete the following steps: 1. In the J2EE Hierarchy, right-click WebSphereCommerceServerExtensionsData and select Generate -> EJB to RDB mapping from the menu. 2. On the Create new EJB/RDB mapping window, select Meet In The Middle and then click Next. Chapter 13. Customize a store: Price Watch example 425 3. On the Database Connection window, do the following: a. In the Connection name text box, enter WebSphereCommerceServerExtensionsData. b. In the Database text box, enter , where is your database name. c. In the User ID text box, enter your DB2 user name. d. In the Password text box, enter your DB2 password. e. From the Database vendor type list, select DB2 Universal Database V8.1. f. Leave the JDBC Driver field as IBM DB2 APP DRIVER. g. Click Next. There will be a short delay while the table names are loaded. Once this complete the list of available database tables will be displayed. 4. Check the .XPRICEWATCH table and click Next. 5. Select Match By Name and Type and click Finish. The Mapping editor will now open. 6. The correct mappings between the fields should already be in place. Expand the XPriceWatch bean in the Overview pane. You should see that field names in the Enterprise Beans column should match up with the column names in the Tables column (see Figure 13-12 on page 427). This can also be seen from the list of mappings in the Outline view. Tip: If the mappings are incorrect, perform the following steps: In the Outline view, right-click the incorrect mappings and select Remove Mapping from the menu. Repeat for each incorrect mapping. In the Enterprise Beans pane (the top pane in the Map.mapxmi window), drag each unmapped field on to the corresponding field in the Tables pane as shown in Figure 13-13 on page 427. 7. Save your work by pressing Ctrl+S. 426 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 13-12 EJB/RDB Mapping for XPriceWatch Figure 13-13 Drag and drop fields to create EJB/RDB mappings Chapter 13. Customize a store: Price Watch example 427 Change schema name The next step is to change the schema name so that our new bean will be portable to other databases. To make this modification, complete the following steps: 1. In the J2EE perspective, switch to the J2EE Hierarchy view. 2. Expand Databases, then expand WebSphereCommerceServerExtensionsData. 3. Right-click the (which is the DB2 user name at the time the instance database was created) and select Rename from the menu. 4. Enter NULLID as the new schema name. We now have a completed Entity bean for our XPRICEWATCH table. 13.6.3 Create an access bean for the entity bean Now we must create a new access bean for our entity bean. The purpose of an Access bean is to provide a simple interface to our entity bean. The access bean exposes only the methods of the entity bean that belong to the remote interface, that is, the methods that we need to use to create new database rows and manipulate existing rows. To use WebSphere Studio Application Developer to generate the access bean from the existing XPriceWatch entity bean, complete the following steps: 1. In the J2EE Hierarchy, right-click WebSphereCommerceServerExtensionsData under EJB Modules and select New -> Access Bean from the menu. 2. On the Add an Access Bean window, select Copy Helper and click Next. 3. From the Enterprise Beans list, check XPriceWatch and click Next. 4. From the Constructor method drop-down list, select findByPrimaryKey(com.ibm.itso.sample.ejb.XPriceWatchKey). The method selected here determines which FinderHelper method is invoked when the refreshCopyHelper() method is called after lazy initialization of the Access bean. Additionally, this determines which setters will be provided for initialization purposes. Selecting the findByPrimaryKey() Helper will mean that setters will be provided for each field in the key. For example, in this case, the following initialization setters will be provided: – setInitKey_memberId(Long) – setInitKey_catEntryId(Long) – setInitKey_contractId(Long) 428 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 5. Select all attributes in the Attribute Helpers list (by default, all are selected). 6. Click Finish. 7. Save your work by pressing Ctrl+S. 13.6.4 Generate the deploy code and test the bean The next step is to generate the deploy code for our bean. The code generation tool automatically creates implementation classes for the home and remote interface objects. The JDBC persister and finder classes for CMP beans are also generated. For more details about what is generated, refer to the Programming Guide and Tutorials, IBM WebSphere Commerce V5.5 product guide. Generate deploy code To generate the deploy code, complete the following steps: 1. In the J2EE Hierarchy, expand WebSphereCommerceServerExtensionsData. 2. Right-click XPriceWatch and select Generate Deploy Code from the menu. Testing the bean Now everything is complete and we are ready to test the new bean. Enable Universal Test Client If you have already enabled the Universal Test Client on your server, skip the following four steps: 1. Open the Servers perspective by selecting Window -> Open Perspective -> Other -> Server and click OK. 2. Double-click the WebSphereCommerceServer server in the Server Configuration pane, and select the Configuration tab. 3. Check Enable Universal Test Client. 4. Save your changes by pressing Ctrl+S and close the view. 5. Start or restart the WebSphereCommerceServer server. Chapter 13. Customize a store: Price Watch example 429 Test the create method of the bean Since the XPRICEWATCH table is empty, the first test we should perform is to use the bean to add a new row. The following steps show how to test the create method of the bean: 1. In the J2EE Hierarchy, right-click WebSphereCommerceServerExtensionsData and select Run on Server from the menu. The Universal Test Client will appear as shown in Figure 13-14. Figure 13-14 The Universal Test Client 2. Click the JNDI Explorer icon. The JNDI Explorer allows you to find the names of the beans that run in the EJB container on the server. 3. In the JNDI Explorer, find the XPriceWatchHome interface by expanding cell -> nodes -> localhost -> servers -> server1 -> ejb -> com -> ibm -> itso -> sample -> ejb. 4. Click the XPriceWatchHome interface. A new view will open with References and Parameters panes. 430 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 5. In the References pane, select EJB References -> XPriceWatch -> XPriceWatchHome. 6. Click XPriceWatch create(Long,Long,Long,BigDecimal). The Parameters view has now changed to allow you to enter the parameters for the method call. Note that the parameter names are not shown, only their types. The parameters in the table are shown in the order that they appear in the method source. In this case the order is memberId, catEntryId, contractId and watchPrice. 7. In the Parameters view, do the following: a. In the first row, enter -1000 in the Value column. This is the Member ID for the default administrator user. b. In the second row, enter 10001 in the Value column. This is the CATENTRY_ID for one of the products in our catalog. c. In the third row, enter 10003 in the Value column. This is the CONTRACT_ID for one of the contracts. d. In the last row, enter 50.00 in the Value column. This is the price at which we wish to purchase the product. Click Invoke. The results section of the view will display that an XPriceWatch object has been created, as shown in Figure 13-15 on page 432. Note: You can verify that the row was created in the XPRICEWATCH table by executing the following in a DB2 Command Center window: select * from XPRICEWATCH Chapter 13. Customize a store: Price Watch example 431 Figure 13-15 Result of invoking the create method on the XPriceWatch bean Test the FinderHelper method Now we have a row in the XPRICEWATCH table, we can test our FinderHelper method to retrieve the row. To do this, complete the following steps. 1. In the References pane, click the XPriceWatch findByMemberIdAndCatEntryIdAndContractId method. The parameters pane will change to allow you to enter the parameters for the method. 2. In the Parameters pane, do the following: a. Enter -1000 in the first parameter value. b. Enter 10001 as the second parameter value. c. Enter 10003 as the third parameter value. d. Click Invoke. The Results section will show that a new instance of XPriceWatch has been returned. 3. Click Work with Object to add the new bean instance to the EJB References list. In the References pane you will see the new bean instance (XPriceWatch). 432 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 4. Click the new instance of the bean called XPriceWatch (com.ibm.itso.sample.ejb) in the References pane. The list will expand to show the available methods for the XPriceWatch bean. 5. Select the BigDecimal getWatchPrice() method. 6. Because this is a getter method, there are no parameters required, so just click Invoke. The result (50.00000) is shown in the Results section as shown in Figure 13-16. Figure 13-16 Testing a bean getter method in the Universal Test Client Test updating a value using the new bean instance We can now test that we can update a value in the XPRICEWATCH table. We have already found the row that we want to update in the previous step. To change the WATCHPRICE field to a new value, complete the following steps: 1. Select the setWatchPrice(BigDecimal) method from the References pane. 2. In the Parameters pane, enter the new value of 40.00 next to the BigDecimal field. 3. Click Invoke. You will see a message “The method completed successfully” in the Results section. Once again, you can check that the value has been changed in the database using the DB2 Command Center. Chapter 13. Customize a store: Price Watch example 433 Tip: If you try to use the FinderHelper on the home interface again, a message will be displayed saying that the XPriceWatch object is already in use. Before using the home interface again, you must remove the XPriceWatch bean instance you have already created. To do this, click the (Remove EJB entity bean from tree) icon next to the XPriceWatch item in the References pane. 13.6.5 Update the bean with new FinderHelpers The requirement to display a list of all products and prices for a particular user means that we will need a way to retrieve all the rows from the XPRICEWATCH table for a particular MEMBERID. In order to achieve this, we will need to add a new FinderHelper to the XPriceWatch bean, as described in 13.2, “Solution design” on page 394. Add FinderHelper for finding by memberId To add the new FinderHelper, complete the following steps: 1. Double-click the WebSphereCommerceServerExtensionsData project. If it is not visible, open the J2EE Hierarchy first. 2. Click the Beans tab. 3. Select the XPriceWatch bean from the Beans list. 4. Scroll down the pane on the right to the WebSphere Extensions section. 5. Next to the Finders list, click Add. The Add Finder Descriptor window will open. 6. Select New. 7. In the Name text box, enter findByMemberId. 8. Click Add next to the Parameters list. 9. In the Name text box, enter memberId. 10.In the Type text box, enter java.lang.Long. 11.Click OK. 12.From the Return Type list, select java.util.Collection. Note that there could be more than one row returned from the underlying query and hence we need a return type that can hold multiple instances of our bean. 434 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Tip: Unlike when developing for previous versions of WebSphere Commerce, the recommended return type for multiple rowset Finders is now java.util.Collection, not java.util.Enumeration. Using a Collection has advantages over using Enumerations, not least of which is the ability to obtain the size of a Collection without iterating through all the elements. Also, an object Array or an Iterator can be produced from the Collection. 13.Click Next. 14.From the Finder type list, select WhereClauseFinderDescriptor. 15.In the Finder statement text box, enter T1.MEMBERID =? 16.Click Finish. 17.Save your work by pressing Ctrl+S. Add FinderHelper for returning all rows In the business logic for the scheduled command to check the prices and send e-mails to customers, we will need to check every row in the XPRICEWATCH table. In order to do this, we need to add one more finder. This time, there is no where clause because we want to retrieve every row. As such, we do not want to use a WhereClauseFinderDescriptor. In this case, we can use an EjbqlFinderDescriptor and a sample finder available in WebSphere Studio Application Developer. To add the finder, complete the following steps: 1. Select the XPriceWatch bean from the Beans list. 2. Scroll down the pane on the right to the WebSphere Extensions section. 3. Next to the Finders list, click Add. The Add Finder Descriptor window will open. 4. Select New. 5. In the Name text box, enter findAll. 6. From the Return Type list, select java.util.Collection. 7. Click Next. 8. From the Finder type list, select EjbqlFinderDescriptor. 9. From the Select a sample finder list, select Find All Query. The Finder statement text box will automatically be filled with the following: select object(o) from XPriceWatchBean o 10.Click Finish. 11.Save your work by pressing Ctrl+S. Chapter 13. Customize a store: Price Watch example 435 Regenerate the access bean Now that we have added the new finders, we must regenerate the access bean to reflect the new structure. To do this, complete the following steps: 1. If you have closed the EJB Deployment Descriptor, double-click the WebSphereCommerceServerExtensionsData project to re-open it. 2. Click the Beans tab. 3. Select the XPriceWatch bean from the Beans list. 4. Scroll down the pane on the right to the Access Beans section. 5. Select the XPriceWatchAccessBean. 6. Click the Remove button next to the Access bean list. 7. Save your work by pressing Ctrl+S. 8. In the J2EE Hierarchy, right-click WebSphereCommerceServerExtensionsData and select New -> Access Bean from the menu. The Add an Access Bean window will open. 9. Select Copy Helper and click Next. 10.From the Enterprise Beans list, check XPriceWatch and click Next. 11.From the Constructor method drop-down list, select findByPrimaryKey(com.ibm.itso.sample.ejb.XPriceWatchKey). 12.Check all attributes in the Attribute Helpers list. 13.Click Finish. 14.Save your work by pressing Ctrl+S. Regenerate the deploy code for the bean The next step is to regenerate the deploy code for our bean. To generate the deploy code, complete the following steps: 1. In the J2EE Hierarchy, expand WebSphereCommerceServerExtensionsData. 2. Right-click XPriceWatch and select Generate Deploy Code from the menu. Test the new FinderHelper methods Now everything is complete, and we are ready to test the new bean by doing the following: 1. Start or restart the WebSphereCommerceServer server. 436 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: You must restart your WebSphereCommerceServer; otherwise, the new bean will not be available. 2. In the J2EE Hierarchy, right-click WebSphereCommerceServerExtensionsData and select Run on Server from the menu. The Universal Test Client will appear as shown in Figure 13-14 on page 430. 3. Click the JNDI Explorer icon. The JNDI Explorer allows you to find the names of the beans that run in the EJB container on the server. 4. In the JNDI Explorer, find the XPriceWatchHome interface by expanding cell -> nodes -> localhost -> servers -> server1 -> ejb -> com -> ibm -> itso -> sample -> ejb. 5. Expand XPriceWatch bean under EJB References and click the XPriceWatchHome interface. 6. In the References pane, click the XPriceWatch findByMemberId method. The parameters pane will change to allow you to enter the parameter for the method. 7. In the Parameters pane, enter -1000 as the parameter value. 8. Click Invoke. The Results section will show that a new java.util.Collection instance has been returned. 9. Click Work with Contained Objects. The XPriceWatch object from within the collection will be added to the References list. If more than one row is returned, an instance for each row is added. Note: If you select Work with Object, the Collection object itself is added to the References list under the Object References heading. This may be useful if you want to invoke the size() method on the Collection to see how many rows were returned before using the Work with Contained Objects option. 10.Repeat the above steps to test the findAll method. You can invoke the methods of the XPriceWatch object to obtain the results of the query in the same manner as in the previous example. Chapter 13. Customize a store: Price Watch example 437 13.7 Creating the new commands In the previous section, we created an entity bean and an access bean in order to store and manipulate our data in the database. Now we can begin to implement the business logic that uses that data. This section demonstrates the process of creating custom commands and describes how to implement the commands for the Price Watch example. When creating a custom command, it is typical to perform the following tasks: 1. Create an interface for the command. 2. Create an implementation class for the command. 3. Register the new command in the command registry. 4. Create access control policies for the command. 5. Modify server and application configuration information so the command can be run in the WebSphere Commerce application. 13.7.1 Create the command interface This section shows how to create the interface for the command. Complete the following steps: 1. Open the Java perspective by clicking the Open a Perspective button and selecting (Other) -> Java. 2. Expand WebSphereCommerceServerExtensionsLogic. 3. Right-click src and select New -> Package. 4. Enter com.ibm.itso.sample.commands in the Name field and click Finish. 5. Right-click the package you just created and select New -> Interface. The Java Interface window will open. 6. In the Name text box, enter ManagePriceWatchListCmd. Note: We recommend that the WebSphere Commerce command interface names should end with Cmd. 7. Next to the Extended interfaces list, click Add. The Extended Interfaces Selection window will open. 8. In the Choose interfaces text box, enter ControllerCommand. All command interfaces in WebSphere Commerce must be descendents of the com.ibm.commerce.command.ControllerCommand interface. That is, 438 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide they must either directly extend the ControllerCommand interface or extend another command’s interface. 9. Click OK. 10.Click Finish. A new file called ManagePriceWatchListCmd.java will be created and selected in the Package Explorer pane. A new editor will open and will contain the code shown in Example 13-8 (or similar). Example 13-8 ManagePriceWatchList interface package com.ibm.itso.sample.commands; import com.ibm.commerce.command.ControllerCommand; /** * @author Insley * * To change this generated comment edit the template variable "typecomment": * Window>Preferences>Java>Templates. * To enable and disable the creation of type comments go to * Window>Preferences>Java>Code Generation. */ public interface ManagePriceWatchListCmd extends ControllerCommand { } 11.Next, we need to add a static final String to the interface that specifies the name of the default implementation class for our command. Add the following line to the interface: static final String defaultCommandClassName = "com.ibm.itso.sample.commands.ManagePriceWatchListCmdImpl"; WebSphere Commerce will look for this String in order to determine the implementation class for the command. However, if there is an entry in the CMDREG table for this command interface, the implementation class specified in the database will override the default specified in the interface. 12.Save your work by pressing Ctrl+S. 13.7.2 Create the command implementation class The next step is to create the implementation class for our command. Remember that the class name should be that which you specified in the defaultCommandClassName String in the interface. Chapter 13. Customize a store: Price Watch example 439 Create command class To create the command class, complete the following steps: 1. Right-click com.ibm.itso.sample.commands in the Package Explorer and select New -> Class. The Java Class window will open. 2. In the Name text box, enter ManagePriceWatchListCmdImpl. Note that all WebSphere Commerce command implementation class names should end with CmdImpl. 3. Next to the Superclass text box, click Browse. The Superclass Selection window will open. 4. In the Choose a type text box, enter ControllerCommandImpl. All command classes in WebSphere Commerce must be descendents of the com.ibm.commerce.command.ControllerCommandImpl class. 5. Click OK. 6. Click the Add button next to the Interfaces list. The Implemented Interface Selection window will open. 7. In the Choose interfaces text box, enter ManagePriceWatchListCmd. 8. Select Constructors from superclass. 9. Click OK. Before continuing, make sure that the remaining options are left as default. These options are shown in Figure 13-17 on page 441. 440 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 13-17 Adding the implementation class for the ManagePriceWatchList command 10.Click Finish. A new file called ManagePriceWatchListCmdImpl.java will be created and selected in the Package Explorer pane. The source editor will open. Add business logic to command class Complete the following steps to add the command code to the class: 1. Add the import statements to the class as shown in Example 13-9 on page 442. Tip: To avoid having to manually enter the code in the remainder of this chapter, you may wish to open the source files provided in the sample and cut and paste the relevant sections as shown. Chapter 13. Customize a store: Price Watch example 441 Example 13-9 Import statements for ManagePriceWatchListCmdImpl import java.io.*; import java.math.BigDecimal; import import import import import import import import import com.ibm.commerce.ras.*; com.ibm.commerce.server.*; com.ibm.commerce.command.*; com.ibm.commerce.exception.*; com.ibm.commerce.datatype.*; com.ibm.commerce.user.objects.*; com.ibm.commerce.accesscontrol.AccessVector; com.ibm.itso.sample.databeans.PriceWatchBean; com.ibm.itso.sample.ejb.XPriceWatchAccessBean; When you enter this code into WebSphere Studio Application Developer, you will notice that some of the lines have errors. This is not a problem because they will be fixed as you add the remaining code in the chapter. 2. Add the class variables to the source code as shown in Example 13-10. Note how there is a variable for each of the parameters that will be passed to the command when it is called. Tip: It is good practice to create a private final String called CLASS_NAME in every class you create. This variable will be useful in trace statements or exception handling. Additionally, your methods should contain a private final String called METHOD_NAME. An example of when this is useful is when you need to throw an ECApplicationException or an ECSystemException. The exception, as seen in Example 13-11 on page 444, can be reused without alteration as long as the variables are available. Example 13-10 Class variables for ManagePriceWatchListCmdImpl private final String CLASS_NAME = "ManagePriceWatchListCmdImpl"; private AccessVector resources = null; /** * valid values for action are: * - add * - delete * - deleteall * * Note that using 'add' will update an existing entry if one is found. */ private String action = null; private Long memberId = null; 442 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide private Long catEntryId = null; private Long contractId = null; private BigDecimal watchPrice = null; 3. Add setter methods for the following five variables: – – – – – action memberId catEntryId contractId watchPrice a. Select the five variables in the Outline view. b. Right-click one of the variables and select Generate Getter and Setter from the menu. c. Select only the setter methods for the five variables and click OK. Five setter methods will be generated in the source. 4. Add the validateParameters method, as shown in Example 13-11 on page 444, to the class after the constructor method. The purpose of this method is to retrieve the parameters for the command from the request properties object. This method is responsible for determining whether parameters are required or optional. Required parameters should be retrieved inside a try-catch block that catches the ParameterNotFoundException. This exception is thrown if a named parameter does not exist in the request object when a typed getter is used to try and retrieve it. Hence, the single parameter getters (for example, reqProp.getLong("catEntryId")) should be used in this block. If the exception is caught, an ECApplicationException should be thrown, which will halt the execution of the command and an appropriate error page will be returned to the user. Optional parameters should be retrieved outside the try-catch block. The two parameter getters should be used. The first parameter specifies the name of the parameter to be retrieved and the second parameter specifies the default value to use should the parameter not be passed. You can see in Example 13-11 on page 444 that the memberId parameter is optional. If it is not passed, the current userId is retrieved from the command context and used instead. You may use null as the default value if your business logic then uses the presence of a null value to determine that the optional parameter was not specified. Chapter 13. Customize a store: Price Watch example 443 Example 13-11 validateParameters() method for ManagePriceWatchListCmdImpl public void validateParameters() throws ECException { final String METHOD_NAME = "validateParameters"; if (WASTrace.isTracing("WC_COMMAND")) { WASTrace.entry("WC_COMMAND", CLASS_NAME, METHOD_NAME); } TypedProperty reqProp = getRequestProperties(); // check parameters exist and set class variables try { setAction(reqProp.getString("cmdAction")); if (action.equals("add")) { setCatEntryId(reqProp.getLong("catEntryId")); setContractId(reqProp.getLong("contractId")); setWatchPrice(reqProp.getBigDecimal("watchPrice")); } else if (action.equals("delete")) { setCatEntryId(reqProp.getLong("catEntryId")); setContractId(reqProp.getLong("contractId")); } } catch (ParameterNotFoundException e) { throw new ECApplicationException(ECMessage._ERR_CMD_MISSING_PARAM, CLASS_NAME, METHOD_NAME, ECMessageHelper.generateMsgParms(e.getParamName())); } // memberId is optional. If not passed, use the ID of the currently // logged on user. setMemberId(reqProp.getLong("memberId", getCommandContext().getUserId())); if (WASTrace.isTracing("WC_COMMAND")) { WASTrace.exit("WC_COMMAND", CLASS_NAME, METHOD_NAME); } } Note that the example above uses additional logic to determine which parameters should be retrieved depending on the value of the action parameter. 5. Add the performExecute() method to the class: a. Add the code to the class as shown in Example 13-12 on page 445. 444 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Example 13-12 performExecute() method for ManagePriceWatchListCmdImpl /** * The business logic for this controller command. */ public void performExecute() throws ECException { final String METHOD_NAME = "performExecute"; if (WASTrace.isTracing("WC_COMMAND")) { WASTrace.entry("WC_COMMAND", CLASS_NAME, METHOD_NAME); } /// perform server side parameter checking super.performExecute(); TypedProperty rspProp = new TypedProperty(); /// Set the view name so the JSP can be called rspProp.put(ECConstants.EC_VIEWTASKNAME, "PriceWatchList"); setResponseProperties(rspProp); if (WASTrace.isTracing("WC_COMMAND")) { WASTrace.exit("WC_COMMAND", CLASS_NAME, METHOD_NAME); } } This forms the skeleton of the performExecute() method. This code can be used as a basis for every performExecute() method you write for your commands. However, the METHOD_NAME variable and the view task name will need to be changed for other commands. Entry and exit trace lines are included. Tip: It is good coding practice to include entry and exit trace statements in every method you write in your commands. This will help with debugging later on should it be required. If you use the isTracing() method to determine whether or not to call the trace methods, there is no significant overhead in including this code when the trace components are turned off in a production environment. To ensure that the validateParameters() method is called, the super.performExecute() method is invoked. A new TypedProperty object called rspProp is created to hold the response properties for the command. Objects added to the response properties will be available for use in the JSP. Chapter 13. Customize a store: Price Watch example 445 The following line sets the view command name that will be called in order to call the JSP that we wish to display: rspProp.put(ECConstants.EC_VIEWTASKNAME, "PriceWatchList"); For an explanation of the different ways you can call JSPs, refer to the Programming Guide and Tutorials, IBM WebSphere Commerce V5.5 product guide. Finally, the setResponseProperties(rspProp) method is called. This method is implemented in the command’s superclass. b. Remember that the command is designed to perform three functions that allow the user to manage their price watch list. These three functions are implemented in three task commands: • • • PriceWatchAddTaskCmd PriceWatchDeleteTaskCmd PriceWatchDeleteAllTaskCmd The action that the command should take will be passed to the command and stored in the action variable. The code in Example 13-13 consists of an if-else if structure that tests the value of action. Depending on its value, one of the three task commands is called. Insert the code in Example 13-13 into the performExecute() method just below the TypedProperty rspProp object is instantiated. Example 13-13 Work section of performExecute() for ManagePriceWatchListCmdImpl if (action.equals("add")) { PriceWatchAddTaskCmd pwaCmd = null; pwaCmd = (PriceWatchAddTaskCmd) CommandFactory.createCommand( "com.ibm.itso.sample.commands.PriceWatchAddTaskCmd", getStoreId()); pwaCmd.setCommandContext(getCommandContext()); pwaCmd.setMemberId(memberId); pwaCmd.setCatEntryId(catEntryId); pwaCmd.setContractId(contractId); pwaCmd.setWatchPrice(watchPrice); pwaCmd.validateParameters(); pwaCmd.execute(); } else if (action.equals("delete")) { PriceWatchDeleteTaskCmd pwdCmd = null; pwdCmd = (PriceWatchDeleteTaskCmd) CommandFactory.createCommand( "com.ibm.itso.sample.commands.PriceWatchDeleteTaskCmd", getStoreId()); pwdCmd.setCommandContext(getCommandContext()); 446 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide pwdCmd.setMemberId(memberId); pwdCmd.setCatEntryId(catEntryId); pwdCmd.setContractId(contractId); pwdCmd.validateParameters(); pwdCmd.execute(); } else if (action.equals("deleteall")) { PriceWatchDeleteAllTaskCmd pwdCmd = null; pwdCmd = (PriceWatchDeleteAllTaskCmd) CommandFactory.createCommand( "com.ibm.itso.sample.commands.PriceWatchDeleteAllTaskCmd", getStoreId()); pwdCmd.setCommandContext(getCommandContext()); pwdCmd.setMemberId(memberId); pwdCmd.validateParameters(); pwdCmd.execute(); } As you can see from the code above, the procedure for calling a task command is as follows: i. Instantiate a variable with the type of the interface of the task command. ii. Call the CommandFactory.createCommand() method with the name of the command interface, including the package name and the store ID. Cast the returned object to the command interface type and assign it to the variable created in the first step. iii. Set the command context of the task command to be the current command context for the controller command. iv. Initialize any task command variables that are required. v. Call validateParameters() on the task command to perform any parameter checking. vi. Call the execute() method on the task command. Important: You should not call the performExecute() method yourself. When execute() is called, a number of important operations are performed before the performExecute() method is invoked. This includes exception handling (non-WebSphere Commerce exceptions are wrapped in an ECSystemException) and performance monitoring tasks. Chapter 13. Customize a store: Price Watch example 447 vii. Retrieve any results from the task command using the getter methods. An example of this can be seen in Example 13-14 when the PriceWatchBean is retrieved. c. Finally, the list of price watch items must be retrieved from the database. You will see in 13.8.3, “Creating the price watch data bean” on page 467 that a data bean is used for storing the list. The PriceWatchListTaskCmd task command is used to retrieve the data from the database and to build the PriceWatchBean object that we will use in the JSP. Add the code in Example 13-14 to the performExecute() method below the if-else block you just added. Example 13-14 Retrieving the price watch list using PriceWatchListTaskCmd // Use PriceWatchListTaskCmd to get the data bean for the price watch // table display. PriceWatchBean pwBean = null; PriceWatchListTaskCmd pwlCmd = null; pwlCmd = (PriceWatchListTaskCmd) CommandFactory.createCommand( "com.ibm.itso.sample.commands.PriceWatchListTaskCmd", getStoreId()); pwlCmd.setCommandContext(getCommandContext()); pwlCmd.setMemberId(memberId); pwlCmd.validateParameters(); pwlCmd.execute(); pwBean = pwlCmd.getPriceWatchBean(); // Put the populated data bean on the response rspProp.put("pwBean", pwBean); The last line of the code above puts the data bean into the response properties object. 6. Save your work by pressing Ctrl+S. 7. Rebuild the project by right-clicking WebSphereCommerceServerExtensionsLogic and selecting Build Project. Whenever you change or add code and you are happy that the code is in a state you are ready to test, you must rebuild the project that the code belongs to. Doing this will compile the Java source and create the class files. Only at this stage will you see compile errors in your code, should there be any. For example, uncaught exceptions will be flagged in the code source view. Any 448 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide errors will be highlighted with a white cross in a red circle in the package explorer and in the code source. Warning: Do not enable the option to automatically rebuild your projects when you make changes in the WebSphere Studio Application Developer preferences. If you enable this option, there will be a significant delay (>10 minutes) every time you save your work while the projects rebuild. WebSphere Studio Application Developer recompiles every class in the workspace on every save when this option is enabled, not just the classes that have changed. 13.7.3 Add the task commands to the workspace In this section we need to create the four task commands used by the controller commands: PriceWatchList PriceWatchAdd PriceWatchDelete PriceWatchDeleteAll 13.7.4 Register the new command in the command registry Before the new command can be used, it must be registered in the command registry. This is done by adding a new entry in the URLREG database table. In the DB2 Command Center or a DB2 Command prompt, ensure you are connected to your development database and then execute the SQL shown in Example 13-15. Example 13-15 SQL for registering the ManagePriceWatchList command insert into URLREG (URL,STOREENT_ID,INTERFACENAME,HTTPS,DESCRIPTION,AUTHENTICATED) values ( 'ManagePriceWatchList', 10001, 'com.ibm.itso.sample.commands.ManagePriceWatchListCmd', 0, null, null ) Make sure you use the correct store ID in the SQL. Note that you should specify the interface name of the command, not the implementation class name. Chapter 13. Customize a store: Price Watch example 449 13.7.5 Create the PriceWatchListDisplayCmd command In this section, we will create the PriceWatchListDisplayCmd command. This command will be called when the user selects price watch from the menu bar. Create the command interface This section shows how to create the interface for the command. Complete the following steps: 1. Open the Java perspective by clicking the Open a Perspective button and selecting (Other) -> Java. 2. Expand WebSphereCommerceServerExtensionsLogic -> src -> com.ibm.itso.sample.commands. 3. Right-click com.ibm.itso.sample.commands and select New -> Interface. The Java Interface window will open. 4. In the Name text box, enter PriceWatchListDisplayCmd. 5. Next to the Extended interfaces list, click Add. The Extended Interfaces Selection window will open. 6. In the Choose interfaces text box, enter ControllerCommand. 7. Click OK. 8. Click Finish. A new file called PriceWatchListDisplayCmd.java will be created and selected in the Package Explorer pane. 9. Add the static final String to the interface as shown in Example 13-16. Example 13-16 PriceWatchList Display interface package com.ibm.itso.sample.commands; import com.ibm.commerce.command.ControllerCommand; /** * @author Insley */ public interface PriceWatchListDisplayCmd extends ControllerCommand { static final String defaultCommandClassName = "com.ibm.itso.sample.commands.PriceWatchListDisplayCmdImpl"; } 10.Save your work by pressing Ctrl+S. 450 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Create the implementation class The next step is to create the implementation class for our command. Remember that the class name should be that which you specified in the defaultCommandClassName String in the interface. To create this class, complete the following steps: 1. Right-click com.ibm.itso.sample.commands in the Package Explorer and select New -> Class. The Java Class window will open. 2. In the Name text box, enter PriceWatchListDisplayCmdImpl. 3. Next to the Superclass text box, click Browse. The Superclass Selection window will open. 4. In the Choose a type text box, enter ControllerCommandImpl. 5. Click OK. 6. Click the Add button next to the Interfaces list. The Implemented Interface Selection window will open. 7. In the Choose interfaces text box, enter PriceWatchListDisplayCmd. 8. Check Constructors from superclass. Before continuing, make sure that the remaining options are left as the default. These options are shown in Figure 13-17 on page 441. 9. Click Finish. A new file called PriceWatchListDisplayCmdImpl.java will be created and selected in the Package Explorer pane. The source editor will open. Add code to class Complete the following steps to add the command code to the class: 1. Add the import statements to the class as shown in Example 13-17. Example 13-17 Import statements for PriceWatchListDisplayCmdImpl import import import import import import import import import import java.io.*; java.math.BigDecimal; com.ibm.commerce.ras.*; com.ibm.commerce.server.*; com.ibm.commerce.command.*; com.ibm.commerce.exception.*; com.ibm.commerce.datatype.*; com.ibm.commerce.user.objects.*; com.ibm.commerce.accesscontrol.AccessVector; com.ibm.itso.sample.databeans.PriceWatchBean; Chapter 13. Customize a store: Price Watch example 451 2. Add the class variables to the source code as shown in Example 13-18. Note how there is a variable for each of the parameters that will be passed to the command when it is called. Example 13-18 Class variables for PriceWatchListDisplayCmdImpl private final String CLASS_NAME = "PriceWatchListDisplayCmdImpl"; private Long memberId = null; 3. Add a setter method for the memberId variable: a. Right-click the memberId variable in the Outline view and select Generate Getter and Setter from the menu. b. Select only the setter method for the memberId variable and click OK. The new setter method will be generated in the source. 4. Add the validateParameters method as shown in Example 13-19 to the class. Example 13-19 validateParameters() method for PriceWatchListDisplayCmdImpl public void validateParameters() throws ECException { final String METHOD_NAME = "validateParameters"; if (WASTrace.isTracing("WC_COMMAND")) { WASTrace.entry("WC_COMMAND", CLASS_NAME, METHOD_NAME); } TypedProperty reqProp = getRequestProperties(); // memberId is optional. If not passed, use the ID of the currently // logged on user. setMemberId(reqProp.getLong("memberId",getCommandContext().getUserId())); if (WASTrace.isTracing("WC_COMMAND")) { WASTrace.exit("WC_COMMAND", CLASS_NAME, METHOD_NAME); } } Note that if memberId is not passed in as a parameter to this command, the user ID from the command context is used. That is, the ID for the currently logged in user is assumed. 5. Add the performExecute() method to the class as shown in Example 13-20 on page 453. 452 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Example 13-20 performExecute() method for PriceWatchListDisplayCmdImpl /** * The business logic for this controller command. */ public void performExecute() throws ECException { final String METHOD_NAME = "performExecute"; if (WASTrace.isTracing("WC_COMMAND")) { WASTrace.entry("WC_COMMAND", CLASS_NAME, METHOD_NAME); } PriceWatchBean pwBean = null; /// perform server side parameter checking super.performExecute(); TypedProperty rspProp = new TypedProperty(); // Use PriceWatchListTaskCmd to get the data bean for the price watch // table display. PriceWatchListTaskCmd pwlCmd = null; pwlCmd = (PriceWatchListTaskCmd) CommandFactory.createCommand( "com.ibm.itso.sample.commands.PriceWatchListTaskCmd", getStoreId()); pwlCmd.setCommandContext(getCommandContext()); pwlCmd.setMemberId(memberId); pwlCmd.validateParameters(); pwlCmd.execute(); pwBean = pwlCmd.getPriceWatchBean(); // Put the populated data bean on the response rspProp.put("pwBean", pwBean); /// see how controller command call a JSP rspProp.put(ECConstants.EC_VIEWTASKNAME, "PriceWatchList"); setResponseProperties(rspProp); if (WASTrace.isTracing("WC_COMMAND")) { WASTrace.exit("WC_COMMAND", CLASS_NAME, METHOD_NAME); } } Chapter 13. Customize a store: Price Watch example 453 In this method, an instance of the PriceWatchBean is created to hold the list of price watch items to be displayed to the user. The PriceWatchList task command is used to populate the bean before it is passed into the response object. 6. Save your work by pressing Ctrl+S. 7. Rebuild the project by right-clicking WebSphereCommerceServerExtensionsLogic and selecting Build Project. Register the command in the command registry Before the new command can be used, it must be registered in the command registry. As before, add a new entry in the URLREG database table. In the DB2 Command Center or a DB2 Command prompt, ensure you are connected to your development database and then execute the SQL shown in Example 13-21. Example 13-21 SQL for registering the PriceWatchListDisplay command insert into URLREG (URL,STOREENT_ID,INTERFACENAME,HTTPS,DESCRIPTION,AUTHENTICATED) values ( 'PriceWatchListDisplay', 10001, 'com.ibm.itso.sample.commands.PriceWatchListDisplayCmd', 0, null, null ) Make sure you use the correct store ID in the SQL. 13.7.6 Create the task commands In this section, we will create the following task commands: PriceWatchList PriceWatchAdd PriceWatchDelete PriceWatchDeleteAll In order to show how to create a task command, we will show how to build the PriceWatchList task command in this section. To create the remaining task commands, you would follow a similar procedure. For the purposes of our 454 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide example, we will import the remaining three task commands into the workspace from the price watch sample code. Create the PriceWatchList task command In this section, we show how to create the task command classes and explain the code in some detail. Create the task command interface This section shows how to create the interface for the task command. Complete the following steps: 1. Open the Java perspective by clicking the Open a Perspective button and selecting (Other) -> Java. 2. Expand WebSphereCommerceServerExtensionsLogic -> src -> com.ibm.itso.sample.commands. 3. Right-click com.ibm.itso.sample.commands and select New -> Interface. The Java Interface window will open. 4. In the Name text box, enter PriceWatchListTaskCmd. 5. Next to the Extended interfaces list, click Add. The Extended Interfaces Selection window will open. 6. In the Choose interfaces text box, enter TaskCommand and click OK. 7. Click Finish. A new file called PriceWatchListTaskCmd.java will be created and selected in the Package Explorer pane. Add code to the interface To add the required code to the interface, complete the following steps: 1. Add the imports to the interface as shown in Example 13-22. 2. Add the static final String to the interface as shown in Example 13-22. Example 13-22 PriceWatchListTaskCmd interface package com.ibm.itso.sample.commands; import com.ibm.commerce.command.TaskCommand; import com.ibm.commerce.datatype.*; import com.ibm.itso.sample.databeans.PriceWatchBean; /** * @author Steve Insley */ public interface PriceWatchListTaskCmd extends TaskCommand { Chapter 13. Customize a store: Price Watch example 455 static final String defaultCommandClassName= "com.ibm.itso.sample.commands.PriceWatchListTaskCmdImpl"; } 3. Add the abstract class variable definitions to the interface, as shown in Example 13-23, on the line before the defaultCommandClassName variable. Example 13-23 Abstract class variable definitions for the interface public void setMemberId(Long newMemberId); public int getNoOfWatches(); public PriceWatchBean getPriceWatchBean(); 4. Save your work by pressing Ctrl+S. Create the implementation class The next step is to create the implementation class for the task command. Remember that the class name should be that which you specified in the defaultCommandClassName String in the interface. To create this class, complete the following steps: 1. Right-click com.ibm.itso.sample.commands in the Package Explorer and select New -> Class. The Java Class window will open. 2. In the Name text box, enter PriceWatchListTaskCmdImpl. 3. Next to the Superclass text box, click Browse. The Superclass Selection window will open. 4. In the Choose a type text box, enter TaskCommandImpl and click OK. 5. Click the Add button next to the Interfaces list. The Implemented Interface Selection window will open. 6. In the Choose interfaces text box, enter PriceWatchListTaskCmd, select the interface from the list, and click OK. 7. Check Constructors from superclass. 8. Uncheck Inherited abstract methods. In this case we do not want to automatically generate the methods as defined in the interface, because they would not be generated as we require. We will manually add the getters and setters for the variables in a later step. 456 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 9. Click Finish. A new file called PriceWatchListTaskCmdImpl.java will be created and selected in the Package Explorer pane. The source editor will open. Add code to class Complete the following steps to add the command code to the class: 1. Add the import statements to the class as shown in Example 13-24. Example 13-24 Import statements for PriceWatchListTaskCmdImpl import import import import java.math.BigDecimal; java.rmi.Naming; java.rmi.RemoteException; java.util.*; import javax.ejb.CreateException; import javax.ejb.FinderException; import javax.naming.NamingException; import import import import import import com.ibm.commerce.catalog.objects.CatalogEntryDescriptionAccessBean; com.ibm.commerce.command.TaskCommandImpl; com.ibm.commerce.exception.*; com.ibm.commerce.ras.*; com.ibm.commerce.rules.util.NoOpOutputStream; com.ibm.itso.sample.ejb.XPriceWatchAccessBean; import com.ibm.itso.sample.databeans.PriceWatchBean; 2. Add the class variables to the source code as shown in Example 13-25. Note how there is a variable for each of the parameters that will be passed to the command when it is called. Example 13-25 Class variables for PriceWatchListTaskCmdImpl private final String CLASS_NAME = "PriceWatchListTaskCmdImpl"; private Long memberId = null; private PriceWatchBean pwDataBean = new PriceWatchBean(); private int noOfWatches = 0; 3. Add a setter method for the memberId variable: a. Right-click the memberId variable in the Outline view and select Generate Getter and Setter from the menu. b. Select only the setter method for the memberId variable and click OK. The new setter method will be generated in the source. Chapter 13. Customize a store: Price Watch example 457 4. Add the getter methods to the end of the class as shown in Example 13-26. Example 13-26 Getter methods for noOfWatches and pwDataBean public int getNoOfWatches() { return noOfWatches; } public PriceWatchBean getPriceWatchBean() { return pwDataBean; } 5. Add the validateParameters method as shown in Example 13-27 to the class. Example 13-27 validateParameters() method for PriceWatchListTaskCmdImpl public void validateParameters() throws ECException { final String METHOD_NAME = "validateParameters"; if ( memberId == null ) { throw new ECApplicationException(ECMessage._ERR_CMD_MISSING_PARAM, CLASS_NAME, METHOD_NAME, "The memberId must be set."); } } The validateParameters() method in a task command varies from how you would implement it in a controller command. We are not retrieving the parameters from the request object in this case. The parameters must be set by the calling command before the task command is executed. As a result, the logic to validate the parameters is slightly different. You will see that we simply test the value of the memberId parameter and if it is null, we throw an ECApplicationException. We do this because the memberId is a required parameter. At this point, you could perform further validation on your parameters, such as range checking or illegal character checking. 6. Add the performExecute() method to the class as shown in Example 13-28. Example 13-28 performExecute() method for PriceWatchListTaskCmdImpl public void performExecute() throws ECException { final String METHOD_NAME = "performExecute"; Vector cCatEntryIds = new Vector(); Vector cContractIds = new Vector(); Vector cWatchPrices = new Vector(); 458 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide super.performExecute(); try { Collection pwaBeans = new XPriceWatchAccessBean().findByMemberId(memberId); noOfWatches = pwaBeans.size(); if (!pwaBeans.isEmpty()) { Iterator beans = pwaBeans.iterator(); while ( beans.hasNext() ) { XPriceWatchAccessBean pwaBean = (XPriceWatchAccessBean) beans.next(); pwaBean.refreshCopyHelper(); cCatEntryIds.add(pwaBean.getCatEntryId()); cContractIds.add(pwaBean.getContractId()); cWatchPrices.add(pwaBean.getWatchPrice()); } pwDataBean.setCatEntryIds((Long[]) cCatEntryIds.toArray(new Long[0])); pwDataBean.setContractIds((Long[]) cContractIds.toArray(new Long[0])); pwDataBean.setWatchPrices((BigDecimal[]) cWatchPrices.toArray(new BigDecimal[0])); } } catch (CreateException e) { throw new ECSystemException(ECMessage._ERR_CREATE_EXCEPTION, CLASS_NAME, METHOD_NAME, e.getMessage()); } catch (javax.naming.NamingException e) { throw new ECSystemException(ECMessage._ERR_NAMING_EXCEPTION, CLASS_NAME, METHOD_NAME, e.getMessage()); } catch (java.rmi.RemoteException e) { throw new ECSystemException(ECMessage._ERR_REMOTE_EXCEPTION, CLASS_NAME, METHOD_NAME, e.getMessage()); } catch (FinderException e) { throw new ECSystemException(ECMessage._ERR_FINDER_EXCEPTION, CLASS_NAME, METHOD_NAME, e.getMessage()); } } In this method the XPriceWatchAccesBean is used to retrieve all of the price watch items for the given member ID. These are returned by the findByMemberId() method as a Collection. Chapter 13. Customize a store: Price Watch example 459 Each XPriceWatchAccessBean is retrieved from the Collection object in turn and the price, contract ID, and watch price are obtained and stored in vectors. When alll the rows have been retrieved, the vectors are converted to arrays and added to the instance of the data bean. This will in turn be used in the JSP when displaying the price watch list. 7. Save your work by pressing Ctrl+S. 8. Rebuild the project by right-clicking WebSphereCommerceServerExtensionsLogic and selecting Build Project. The PriceWatchList task command is now complete. If you were to create the remaining task commands yourself, you would follow a process similar to that which you have just completed. Import the remaining task commands to the workspace In this section, we will import the remaining three task commands to the workspace: 1. From the Java perspective, expand WebSphereCommerceServerExtenstionsLogic -> src -> com.ibm.itso.sample.commands. 2. Right-click com.ibm.itso.sample.commands and select Import. 3. Select File system and click Next. 4. Click Browse and navigate to the sample code directory, for example: c:\6969code\pricewatch\code\WebSphereCommerceServerExtensionsLogic\ src\com\ibm\itso\sample\commands. 5. Click OK. 6. Check the following files: – – – – – – PriceWatchAddTaskCmd.java PriceWatchAddTaskCmdImpl.java PriceWatchDeleteTaskCmd.java PriceWatchDeleteTaskCmdImpl.java PriceWatchDeleteAllTaskCmd.java PriceWatchDeleteAllTaskCmdImpl.java 7. Click Finish. 8. Rebuild the project by right-clicking WebSphereCommerceServerExtensionsLogic and selecting Build Project. 460 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 13.7.7 Create access control policies for the commands This section explains how to create an access control policy XML document and load the policy using the acpload tool. In order to allow customers to execute the price watch commands, we must create and load an access control policy file. The PriceWatchListDisplay and ManagePriceWatchList commands are to be run by the users of the store and so need to be included. The CheckPriceWatchPrices command is intended to be run only by the scheduler, which in turn uses the site administrator user ID, and so does not require an access control policy. The steps in this section are for loading the policies in the WebSphere Studio Application Developer environment. For details on loading access control policies, refer to the Programming Guide and Tutorials, IBM WebSphere Commerce V5.5 product guide. Creating an access control policy XML file To create the file, complete the following steps: 1. Open an Explorer window and navigate to tC:\WebSphere\CommerceStudio55\Commerce\xml\policies\xml, where C:\WebSphere\CommerceStudio55 is your WebSphere Studio Application Developer installation directory. 2. Create a new text file called PriceWatchACPolicy.xml. 3. Add the XML as shown in Example 13-29 to the file. Example 13-29 PriceWatchACPolicy.xml Chapter 13. Customize a store: Price Watch example 461 This file defines one action, Execute, that a user can perform on the commands. Two resource categories are defined that associate the commands’ interfaces with the action. Finally, the resources are bound to the AllSiteUserCmdResourceGroup group in order to specify that all users can execute these commands. 4. Save and close the file. Load the access control policy file with acpload The next step is to load the policy file using the acpload command-line tool. To do this, complete the following steps: 1. Click Start -> Run. 2. Enter Cmd and click OK. A command line window will open. 3. Enter the command as shown below: acpload PriceWatchACPolicy.xml Where: – is the name of your development database – is your DB2 administrator user – is the DB2 password If the command runs correctly, you will see the following output: Running XMLTransform... Running Id Resolver... Running MassLoader... For these changes to take effect, you must restart the WebSphereCommerceServer server. 462 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 13.7.8 Enable component tracing in development environment To test that the trace code is working correctly, the component tracing in WebSphere Commerce Studio Application Developer must be enabled. Refer to the Appendix of the Programming Guide and Tutorials, IBM WebSphere Commerce V5.5 product guide for details of how to do this. For the example in this book, you must enable the com.ibm.websphere.commerce.WC_COMMAND component. For a full list of tracing components that you may wish to enable, refer to the Administration Guide, IBM WebSphere Commerce V5.5 product guide. The output from the trace statements in the command code is written to the activity.log file in \\.metadata\.plugins\com.ibm.etools.server.co re\tmp0\logs. This file is a binary file and should be read using the Activity Log tool. The output is also written to a plain text file called trace.log. This file is in the \\.metadata\.plugins\com.ibm.etools.server.co re\tmp0\logs\server1 directory. 13.8 Creating the new data bean The next step is to create a data bean to hold the information that we want to display in our JSP. This section explains the various ways in which you can implement data beans, and then shows our example implementation in detail. A data bean is simply a class that stores data. A data bean should use private class-wide variables for the data storage and public accessors (getters) in order to make the data externally available. The simplest form of data bean contains no business logic at all. 13.8.1 Data bean types Before deciding on how best to implement a data bean, it is important to consider the scenario in which it will be used. The following is a list of possible scenarios in which a data bean could be employed: To make data from a Controller command available to a JSP To make data from the database available to a JSP To make data from a Controller command and the database available to a JSP Chapter 13. Customize a store: Price Watch example 463 The first two scenarios are the most common. While it is certainly possible to implement a bean for the third scenario, you may wish to consider the alternative, which is to create two beans instead of one in order to separate the two different functions that the bean would provide. It will become clear from the following explanations as to why this is preferable. A data bean to hold data from a command This is the simplest form of a data bean. While it is possible to simply add results as name-value pairs to the response properties within the command, it is good programming practice to use a data bean. This allows for logical grouping of results and the structure can be more easily reused if necessary. It also simplifies the retrieval of parameters. When using the TypedProperty.getParameter() method, the returned value must be cast to the correct type before it can be used. This is avoided when using data beans, because each getter method returns the value in the correct type. The bean class must have the following properties: Private variables to hold the data Public accessors (getters and setters) to allow external access to the data Implement the com.ibm.commerce.beans.DataBean interface The com.ibm.commerce.beans.DataBean interface extends from java.io.Serializable. This allows the bean and the data contained within it to be cached along with the JSP if desired. To use the bean, an instance of the bean class should be created in the Controller command. The results from the business logic in the command that are required for display in the JSP should be stored in the data bean using the setter methods of the bean. In the controller command, a TypedProperty object is used to store name-value pairs that are to be added to the response properties. To make the data available to the JSP, the bean instance should be added to this object. This object in turn is passed to the setResponseProperties() method in the performExecute() method of the command. In the JSP, the bean can be retrieved as follows: Values can then be retrieved from the bean using the getter methods. For example: String someVal = beanVar.getSomeValue(); 464 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide or: Vector someVector = beanVar.getSomeVector(); The values can also be written directly to the JSP output if the data type returned implements the toString() method. For example: would write the contents of the variable returned by getSomeValue() to the JSP. A data bean to retrieve data from the database This type of data bean is designed to be self populating. The values available for display in the JSP are retrieved within the data bean and do not need to be calculated or retrieved in a Controller command. The bean class should have the following properties: Private variables to hold the data. Public accessors (getters) to allow external access to the data. Public accessors (setters) for setting initialization variables. Implement the com.ibm.commerce.beans.SmartDataBean interface. Implement the populate() method. Optionally, the class can extend another class that provides the data access, such as an Access bean. The data bean must implement the populate() method. When the data bean is activated using the DataBeanManager in the JSP, the command context and request properties are passed to the bean and the populate() method is called. When creating the bean, the populate() method should be implemented. You should add code to this method that populates the data bean. This can be done by instantiating and using access beans or session beans or by whatever method is appropriate. If it is known that all the required data can be retrieved using an existing access bean, the data bean can extend the access bean class, giving access to its methods. In this case, before activating the data bean in the JSP, the setInitKey_xxx() methods of the bean (inherited method from the access bean) should be called with the initialization values. The populate() method should call the refreshCopyHelper() method and handle all the necessary exceptions. The data from the bean can be accessed in the JSP using the getter methods provided by the parent access bean class, or the developer can implement getters in the bean class to provide access to the data if necessary. Chapter 13. Customize a store: Price Watch example 465 Note: It is good coding practice to implement smart data beans that extend access bean classes rather than using access beans directly in the JSP code. Using access beans in the JSP code does not fit with the programming model for WebSphere Commerce and there are issues surrounding access control when this is done. In order to retrieve the required data from the database, sometimes an initialization value is required (this could be multiple values). For example, the ItemDataBean bean that is provided with WebSphere Commerce needs to know the item ID for the item you wish to retrieve the data for. In this case, the bean provides a setter method called setItemId(), which you should invoke with the item ID before activating the bean. When the bean is activated, the code in the populate() method of the bean uses the itemId value as the key when retrieving the data from the database. An example of how you instantiate a bean that needs initializing is shown in Example 13-30. Example 13-30 Code for instantiating a smart data bean requiring initialization parameters Sometimes, the data bean will not need any initialization values. For example, the bean may retrieve data from a database table for which the key is known and is constant. In some cases, the initialization data may be retrievable from the request properties, which is already available to the bean. For example, the only data required may be the user ID of the currently logged-on user, which is always available. An example of how you instantiate a bean that does not need initializing is shown in Example 13-31. Example 13-31 Code for instantiating a smart data bean not requiring initialization SomeSmartDataBean sdBean = new SomeSmartDataBean(); com.ibm.commerce.beans.DataBeanManager.activate(sdBean, request); 13.8.2 Further considerations When the use of data beans is necessary, it is important to consider which type of data bean is appropriate. It is generally better practice to retrieve all the necessary data for the display in the controller command. Should errors occur during the database access, it is easier to handle the errors in the command than 466 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide at JSP code runtime. If an error occurs at the end of a large JSP, some display HTML may have been flushed from the buffer and the user’s browser will have a partial response. At this point it is too late to redirect to an error page and very strange results can occur. If the error is trapped at command runtime, the user can be redirected to an appropriate error page. This being the case, most data beans will be data beans that hold data from a command. The data bean will be instantiated in the command and passed to the JSP. There are some cases where this is not appropriate, for example, when there are items of data in the database that are to be displayed on every page on the site. It is not practical to implement the code to retrieve this data in every controller command and pass on the populated bean. In cases such as this, it is logical to use a smart data bean. The bean can be instantiated in each JSP in order to retrieve the data for display. Important: When using self-populating smart data beans in your JSPs, be very careful to avoid situations where runtime errors may occur, because the user may experience strange and unpredictable output as a result. To give an example of using smart data beans, let’s assume that in our Price Watch example we want to display the user’s current price watches in a box on every page. A data bean that extends the XPriceWatchAccessBean, retrieves the current user ID from the request properties, and populates itself would be appropriate. 13.8.3 Creating the price watch data bean First, we need to create a new package for the data bean. It is good practice to keep data beans in a separate package from the commands and EJBs, etc. Create package for data beans Complete the following steps to create the package: 1. Switch to the Java perspective. 2. In the Package Hierarchy, expand WebSphereCommerceServerExtensionsLogic. 3. Right-click src and select New -> Package from the menu. 4. In the Name text box, enter com.ibm.itso.sample.databeans. 5. Click Finish. Chapter 13. Customize a store: Price Watch example 467 Create the data bean Now we can create the data bean as follows: 1. Right-click the com.ibm.itso.sample.databeans package and select New -> Class from the menu. 2. In the Name text box, enter PriceWatchBean. 3. Clear the contents of the Superclass text box. 4. Next to the Interfaces list, click Add. 5. In the Choose interfaces text box, enter DataBean. Select the DataBean interface in the Matching types list that is a member of the com.ibm.commerce.beans package and click OK. 6. Check Constructors from superclass and Inherited abstract methods. 7. Click Finish. The PriceWatchBean class will be created and the source editor for the class will open. Add code to the data bean Complete the bean by completing the following steps: 1. Add the following to the class source: import java.math.BigDecimal; 2. Add the class variables shown in Example 13-32 to the class. Insert the code above the constructor. Example 13-32 Class-wide variables for the PriceWatchBean private Long[] catEntryIds = null; private Long[] contractIds = null; private BigDecimal[] watchPrices = null; These variables are arrays. A particular numbered element of each array represents a row in the price watch list. 3. Create setter methods for the three variables: a. In the Outline view, select catEntryIds, contractIds and watchPrices. b. Right-click one of the selected variables and select Generate Getter and Setter from the menu. The Generate Getter and Setter window will open. c. Select only the setter methods for the three variables. Do not select the getter methods at this stage. We will create them later. d. Click OK. 468 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 4. Add the getter methods to the source as shown in Example 13-33. Example 13-33 Getter methods for PriceWatchBean variables public Long getCatEntryId(int idx) { try { return catEntryIds[idx]; } catch (IndexOutOfBoundsException e) { return null; } } public Long getContractId(int idx) { try { return contractIds[idx]; } catch (IndexOutOfBoundsException e) { return null; } } public BigDecimal getWatchPrice(int idx) { try { return watchPrices[idx]; } catch (IndexOutOfBoundsException e) { return null; } } As you can see, the getter methods include some error checking code. The getters each accept a parameter of type int, which correspond to an element of the relevant array. The error case in which an index that is outside of the bounds of the array is passed is handled and null is returned by the getter. This ensures that a runtime error will not occur in this case when the JSP is used. 5. Add the two additional methods shown in Example 13-34 to the source. Example 13-34 Convenience methods for PriceWatchBean public int getNoOfWatches() { int noOfWatches = 0; if (catEntryIds != null) { noOfWatches = catEntryIds.length; } return noOfWatches; } public boolean isListEmpty() { return (catEntryIds == null || catEntryIds.length == 0); } Chapter 13. Customize a store: Price Watch example 469 The getNoOfWatches() method provides an easy way to retrieve the number of price watch items that are stored in the bean. This method will return 0 if bean has not been initialized, that is, if the three arrays have not been correctly set. This method is coded to protect against NullPointerExceptions occurring when the method is called. The isListEmpty() method provides a way of easily testing if the bean contains any data. 6. Save your work by pressing Ctrl+S. 13.9 Creating the new JavaServer Pages This section contains details about the price watch JSP. In support of the JSP file, updates must be made to the properties files that contain the text to be displayed to the user. This section describes, at a fairly high level, the steps that were taken to create the sample, along with the theory and decisions involved. If you wish to follow these steps, ignore the following Import sample JSP section. Import sample JSP If you do not wish to build this JSP, you can import the finished JSP into your workspace as follows: 1. Open the Java perspective. 2. Expand Stores -> Web Content -> ToolTech. Note: You may recall, there are two different starting points for the customization example, either ToolTech or the ITSO store. This section will refer to ToolTech. If you published the ITSO store, use ITSO inplace of ToolTech within the procedure. 3. Right-click the ToolTech folder and select New -> Folder from the menu. 4. In the Folder name text field, enter PriceWatch and click Finish. 5. Right-click the new folder and select Import from the menu. The Import window will open. 6. Select File System from the list of sources. 7. Click Next. 8. Next to the Directory list, click Browse. 470 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 9. Navigate to the c:\6969code directory where you extracted the redbook sample code containing the price watch samples (for example, c:\6969code\pricewatch\code\Stores\Web Content\ToolTech\PriceWatch). 10.Click OK. The selected folder and its contents will be displayed in the Import window. 11.Select the PriceWatchList.jsp file from the right-hand pane. 12.Ensure that Create selected folders only is the only selected option in the Options frame. 13.Click Finish. The JSP will now be added to your workspace. The following sections explain this JSP. You may wish to open the source of this JSP now as a reference while reading the remainder of this section. 13.9.1 Globalization In order to support multiple languages in our store, all of the displayed text is stored in properties files and referenced by the JSP, depending on the language selected by the user when they log on to the site. The properties files in the ToolTech example must be replaced with the files provided in the price watch sample. Changes to properties files The following properties files must be updated with the changes shown in this section: tooltechtext.properties tooltechtext_en_US.properties The default file, tooltechtext.properties, is used when the language-specific properties file cannot be determined. The tooltechtext_en_US.properties file is the file used when United States English is chosen when logging on to the store. The lines shown in Example 13-35 should be changed in the #Header section of the file. Example 13-35 Lines changed in Header section of properties file Header_Title = ITSO Store Header_Welcome = Welcome to the ITSO store Chapter 13. Customize a store: Price Watch example 471 Add the following line to the #Header section: Header_PriceWatchList = Price Watch Add the lines shown in Example 13-36 to the #Item Display section: Example 13-36 Lines changed in Item Display section of properties file ItemDisp_AddLabel = Add Price Watch ItemDisp_AddPriceWatch = Add Add the lines shown in Example 13-37 to the end of the file. This introduces a new section that contains the text for our new JSP, PriceWatchList.jsp Example 13-37 New price watch section in properties file # Price Watch PriceWatch_Title = Price Watch List PriceWatch_Message = The products you currently have a Price Watch for are listed below. If you wish to remove a watch, click Remove next to the product you wish to remove. PriceWatch_NoItems = You have no products in your Price Watch list. PriceWatch_SKU = SKU PriceWatch_Product = Product PriceWatch_Price = Price PriceWatch_WatchPrice = Watch Price PriceWatch_Remove = Remove PriceWatch_RemoveAll = Remove All If you wish to use additional languages in your store, be sure to add all of the lines shown above to the appropriate properties file. Important: Only the files mentioned above have been modified in our example and as a result, errors will occur if you select a language other than United States English when logging on to the store. Of course, if you add the appropriate entries yourself, the sample would work. Note that when modifying a language properties file, the server must be restarted before the changes will take effect. This is because the values are cached by the server for performance reasons when the server is started. 13.9.2 Creating the JSP file Typically, the easiest way to create a new JSP file is to use one of the sample store JSPs as a template. Once you have customized one JSP with the format of 472 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide your new store, you can then use that as a template for future JSPs. It is possible to create a JSP from scratch, but it is far quicker and less error prone to reuse an existing JSP. Here are some general tips for choosing which JSP to use as a starting point: Choose a JSP with a simple layout and minimal data. If you will be displaying the same data on your page as on one of the sample pages, use that as a starting point, because the bean declarations will already be in place. If you require a layout similar to an existing page, use the one that is the best match. Starting point for the JSP For the Price Watch example JSP, the StoreCatalogDisplay.jsp JSP was used as the starting point since it had little content. To create the minimal template for the new JSP, the StoreCatalogDisplay.jsp code was stripped down to the bare minimum that was required for our new JSP. This new JSP template can be seen in Example 13-38. Example 13-38 Starting point for the new JSP Chapter 13. Customize a store: Price Watch example 473 marker. Example 13-41 Main content of the PriceWatchList.jsp file This code achieves the following: – The RemoveItem form passes the necessary parameters to the ManagePriceWatchList command to delete an item. – A check is made to see if there are any items in the list. If not, a message indicating this is displayed,. Otherwise, the main list table is displayed. – The NumberFormat class is used to format the prices. Chapter 13. Customize a store: Price Watch example 479 – A loop is created to display each item in the list in turn. The loop bounds are determined from the values in the pwBean object. – For each item, the price is found using the ItemDataBean class. As this is a smart data bean, the catEntryId for the item (as retrieved from pwBean) is set in the ItemDataBean and the bean is activated using the DataBeanManager class. This in turn calls the populate method of the data bean in order to retrieve the item data from the database. For details on this, see 13.8.1, “Data bean types” on page 463. – The details on the item and the price watch price are displayed in the table row. – A Remove All button is included with a link to the ManagePriceWatchList command, passing the cmdAction=deleteall parameter. The remaining code is concerned with the formatting of the page. 9. Save your work by pressing Ctrl+S. This JSP is now complete. You may close the editor if you wish. Remember that you can view the layout of the page using the Page Designer or an external editor. 13.9.3 Registering a new view for the price watch list page Now that we have the new JSP, a new view must be added for the price watch list page. This is done by adding a new entry in the VIEWREG database table. In the DB2 Command Center or a DB2 Command prompt, ensure you are connected to your development database and then execute the SQL shown in Example 13-42. Example 13-42 SQL for registering PriceWatchList insert into viewreg (viewname,devicefmt_id,storeent_id,interfacename,classname, properties,description,https,lastupdate) values ( 'PriceWatchList', -1, 10001, 'com.ibm.commerce.command.ForwardViewCommand', 'com.ibm.commerce.command.HttpForwardViewCommandImpl', 'docname=PriceWatch/PriceWatchList.jsp', null, 0, null ) 480 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Make sure you use the correct store ID in the SQL. 13.9.4 Using an external editor It is possible to launch an external editor for editing JSPs and other store front assets from within WebSphere Studio Application Developer. While it is useful to use the built-in source editor for adding code that accesses data beans or performs looping, for example, you may prefer an external editor for editing the look and feel of the pages. The main advantage of the built-in editor is the ability to use the code assist feature (Ctrl + Space) to complete method names or class names, etc. In order to use an external editor, you must make sure that the appropriate file extensions (.jsp, .css, etc.) are registered to that editor. Please refer to the instructions included with your editor for details on how to ensure this. To launch the external editor and edit a file, do the following: 1. Right-click the file you wish to edit, for example, a JSP file. 2. Select Open With -> System Editor from the menu. The system default editor for the file will open and load the selected file. 3. Edit the file in the external editor and save your work. 4. To ensure that WebSphere Studio Application Developer is aware of the changes, you must refresh the view. To do this, right-click the file in the Package Explorer and select Refresh from the menu. Note that once you have used an external editor for a particular file, this method of editing becomes the default. When you double-click that file, the external editor will open. To use the internal editors again, select the desired editor from the Open With menu option. 13.9.5 Changes to the item display page In order for the user to be able to add a price watch price to their list, the CachedItemDisplay.jsp file must be updated. A new form must be added that calls the ManagePriceWatchList command with an action of add. A new text box for the user to add the price watch price must also be added. Finally, a JavaScript function to handle the submission of the form is required. Replace the CachedItemDisplay.jsp file in the workspace with the version included with the sample in order to add the necessary code. Chapter 13. Customize a store: Price Watch example 481 To import the modified CachedItemDisplay.jsp, do the following: 1. In the Java perspective, select and expand Stores -> Web Content -> ToolTech -> ShoppingArea -> CatalogSection -> CatalogEntrySubsection. 2. Right-click CatalogEntrySubsection and select Import. 3. Select File system and then click Next. 4. Click Browse and navigate to the c:\6969code\pricewatch\code\Stores\Web Content\ToolTech\ShoppingArea\CatalogSection\CatalogEntrySubsection directory and click OK. 5. Check CachedItemDisplay.jsp and click Finish. 6. Confirm that you want to overwrite the existing file. 13.9.6 Changes to the site header page As part of the example, we updated the CachedHeaderDisplay.jsp in order to add a link to the price watch list page to the menu bar. The link executes the PriceWatchListDisplay command which in turn forwards the user to the price watch list page. Replace the CachedHeaderDisplay.jsp file in the workspace with the version included with the sample. To import the modified CachedHeaderDisplay.jsp, do the following: 1. In the Java perspective, select and expand Stores -> Web Content -> ToolTech -> inlcude. 2. Right-click include and select Import. 3. Select File system and then click Next. 4. Click Browse and navigate to the c:\6969code\pricewatch\code\Stores\Web Content\ToolTech\include directory and click OK. 5. Check CachedHeaderDisplay.jsp and click Finish. 6. Confirm that you want to overwrite the existing file. 13.10 Creating the batch e-mail command In this section, you will see how to create the CheckPriceWatchPrices command in WebSphere Studio Application Developer. In the following sections you will complete the following tasks: 1. Create an interface for the command. 482 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 2. Create an implementation class for the command. 3. Register the new command in the command registry. 13.10.1 Create the command interface This section shows how to create the interface for the command. Complete the following steps: 1. Open the Java perspective by clicking the Open a Perspective button and selecting (Other) -> Java. 2. Expand WebSphereCommerceServerExtensionsLogic -> src. 3. Right-click the com.ibm.itso.sample.commands package and select New -> Interface. The Java Interface window will open. 4. In the Name text box, enter CheckPriceWatchPricesCmd. 5. Next to the Extended interfaces list, click Add. The Extended Interfaces Selection window will open. 6. In the Choose interfaces text box, enter ControllerCommand. 7. Click OK. 8. Click Finish. A new file called CheckPriceWatchPricesCmd.java will be created and selected in the Package Explorer pane. A new editor will open. 9. Next, we need to add a static final String to the interface that specifies the name of the default implementation class for our command. Add the following line to the interface: static final String defaultCommandClassName = "com.ibm.itso.sample.commands.CheckPriceWatchPricesCmdImpl"; 10.Save your work by pressing Ctrl+S. 13.10.2 Create the command implementation class The next step is to create the implementation class for our command. Remember that the class name should be the one you specified in the defaultCommandClassName String in the interface. Chapter 13. Customize a store: Price Watch example 483 Create the class To create the class, complete the following steps: 1. Right-click com.ibm.itso.sample.commands in the Package Explorer and select New -> Class. The Java Class window will open. 2. In the Name text box, enter CheckPriceWatchPricesCmdImpl. 3. Next to the Superclass text box, click Browse. The Superclass Selection window will open. 4. In the Choose a type text box, enter ControllerCommandImpl. 5. Click OK. 6. Click the Add button next to the Interfaces list. The Implemented Interface Selection window will open. 7. In the Choose interfaces text box, enter CheckPriceWatchPricesCmd. 8. Click OK. 9. Check Constructors from superclass. Before continuing, make sure that the remaining options are left as the default. These options are shown in Figure 13-17 on page 441. 10.Click Finish. A new file called ManagePriceWatchListCmdImpl.java will be created and selected in the Package Explorer pane. The source editor will open. Add command code to the class Complete the following steps to add the command code to the class: 1. Add the import statements to the class as shown in Example 13-43. Example 13-43 Import statements for CheckPriceWatchPricesCmdImpl import java.io.*; import java.math.BigDecimal; import java.util.Collection; import java.util.Iterator; import import import import import 484 java.rmi.RemoteException; javax.ejb.CreateException; javax.ejb.FinderException; javax.ejb.RemoveException; javax.naming.NamingException; WebSphere Commerce V5.5 Handbook Customization and Deployment Guide import import import import import import import import import import import import import com.ibm.commerce.messaging.commands.SendMsgCmd; com.ibm.commerce.price.commands.GetContractUnitPriceCmd; com.ibm.commerce.price.utils.MonetaryAmount; com.ibm.commerce.ras.*; com.ibm.commerce.server.*; com.ibm.commerce.command.*; com.ibm.commerce.exception.*; com.ibm.commerce.datatype.*; com.ibm.commerce.user.objects.*; com.ibm.itso.sample.databeans.PriceWatchEmailBean; com.ibm.itso.sample.ejb.XPriceWatchAccessBean; com.ibm.commerce.accesscontrol.AccessVector; com.ibm.commerce.command.ControllerCommandImpl; 2. Add the following class variable to the source code after the opening brace of the class: private final String CLASS_NAME = "CheckPriceWatchPricesCmdImpl"; 3. Add the performExecute() method to the class as shown in Example 13-44. Example 13-44 performExecute() method for ManagePriceWatchListCmdImpl /** * The business logic for this controller command. */ public void performExecute() throws ECException { final String METHOD_NAME = "performExecute"; if (WASTrace.isTracing("WC_COMMAND")) { WASTrace.entry("WC_COMMAND", CLASS_NAME, METHOD_NAME); } BigDecimal itemPrice = null; BigDecimal watchPrice = null; String email = null; PriceWatchEmailBean pweBean = new PriceWatchEmailBean(); /// perform server side parameter checking super.performExecute(); try { Collection pwaBeans = new XPriceWatchAccessBean().findAll(); if (!pwaBeans.isEmpty()) { Iterator beans = pwaBeans.iterator(); while ( beans.hasNext() ) { XPriceWatchAccessBean pwaBean = (XPriceWatchAccessBean) beans.next(); Chapter 13. Customize a store: Price Watch example 485 pwaBean.refreshCopyHelper(); watchPrice = pwaBean.getWatchPrice(); GetContractUnitPriceCmd gcupCmd = null; gcupCmd = (GetContractUnitPriceCmd) CommandFactory.createCommand( GetContractUnitPriceCmd.NAME, getStoreId()); gcupCmd.setCommandContext(getCommandContext()); gcupCmd.setCatEntryId(pwaBean.getCatEntryId()); gcupCmd.setTradingIds(new Long[] {pwaBean.getContractId()}); gcupCmd.validateParameters(); gcupCmd.execute(); itemPrice = gcupCmd.getPrice().getValue(); if (watchPrice.compareTo(itemPrice) >= 0) { AddressAccessBean aaBean = new AddressAccessBean().findSelfAddressByMember( pwaBean.getMemberId()); aaBean.refreshCopyHelper(); email = aaBean.getEmail1(); pweBean.setFirstName(aaBean.getFirstName()); pweBean.setListPrice(itemPrice); pweBean.setWatchPrice(watchPrice); pweBean.setCatEntryId(pwaBean.getCatEntryId()); // the sendEmail method uses the messaging subsystem // to send the email to the user sendEmail(email, pweBean); // Once the email is sent, remove the price watch // from the list. pwaBean.getEJBRef().remove(); } } } } catch (CreateException e) { throw new ECSystemException(ECMessage._ERR_CREATE_EXCEPTION, CLASS_NAME, METHOD_NAME, e.getMessage()); } catch (NamingException e) { throw new ECSystemException(ECMessage._ERR_NAMING_EXCEPTION, CLASS_NAME, METHOD_NAME, 486 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide e.getMessage()); } catch (RemoteException e) { throw new ECSystemException(ECMessage._ERR_REMOTE_EXCEPTION, CLASS_NAME, METHOD_NAME, e.getMessage()); } catch (FinderException e) { throw new ECSystemException(ECMessage._ERR_FINDER_EXCEPTION, CLASS_NAME, METHOD_NAME, e.getMessage()); } catch (RemoveException e) { throw new ECSystemException(ECMessage._ERR_REMOVE_EXCEPTION, CLASS_NAME, METHOD_NAME, e.getMessage()); } if (WASTrace.isTracing("WC_COMMAND")) { WASTrace.exit("WC_COMMAND", CLASS_NAME, METHOD_NAME); } } A new instance of the PriceWatchEmail data bean is instantiated in order to pass the details to be included in the e-mail to the e-mail template JSP. The following line shows how to retrieve multiple rows from a database table using an access bean: Collection pwaBeans = new XPriceWatchAccessBean().findAll(); The findAll() method of the XPriceWatchAccessBean returns a collection object. This in turn will contain an XPriceWatchAccessBean for each row in the table. If the collection is not empty, an Iterator is created from the access bean and each access bean in the collection is accessed in turn. Note that the returned object from the Iterator’s next() method must be explicitly cast to the access bean type (XPriceWatchAccessBean). The watch price is retrieved from the access bean. An instance of the GetContractUnitPriceCmd is used to retrieve the price of the item for the item and contract specified in the XPRICEWATCH table. This command was chosen because it accepts the catalog entry ID and the contract ID as parameters and then allows access to the best price. For more information about this command, refer to the online help in WebSphere Studio Application Developer. If the e-mail should be sent, the AddressAccessBean is used to retrieve the first name and e-mail address of the user to which the price watch belongs. The private method, sendEmail(), is called to send the e-mail. Chapter 13. Customize a store: Price Watch example 487 Finally, the row in the database table is deleted. This is done by obtaining a reference to the underlying entity bean instance of the XPriceWatchAccessBean and calling the remove() method upon it as follows: pwaBean.getEJBRef().remove(); 4. Add the sendEmail() method to the class as shown in Example 13-45. Example 13-45 sendEmail() method for CheckPriceWatchPricesCmdImpl private void sendEmail(String email, PriceWatchEmailBean pweBean) throws ECException { SendMsgCmd smCmd = (com.ibm.commerce.messaging.commands.SendMsgCmd) CommandFactory.createCommand(SendMsgCmd.NAME, getStoreId()); smCmd.setMsgType("PriceWatchNotificationEmail"); smCmd.setStoreID(getStoreId()); String viewName = new String("PriceWatchNotificationEmailView"); TypedProperty tp = new TypedProperty(); tp.put("pweBean", pweBean); smCmd.compose(viewName, getCommandContext(), tp); // Set the subject, recipient and sender information using Configurable // message data services smCmd.setConfigData("subject","Price Watch Alert!!"); smCmd.setConfigData("recipient", email); smCmd.setConfigData("sender","admin@localhost"); // Send out the message using sendImmediate send service. smCmd.sendImmediate(); // Set the command context obtained from the controller command. smCmd.setCommandContext(getCommandContext()); // Run the outbound messaging system services smCmd.execute(); } The SendMsgCmd command is used to send the e-mail to the customer. The CommandFactory is used to get an instance of the command. The message type is set to PriceWatchNotificationEmail, which is the type that was created in 13.4.2, “Adding the new message type to the database” on page 403. The store ID is also set. The e-mail template to use is chosen by setting the 488 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide appropriate view, in this case PriceWatchNotificationEmailView, which was created in the same section as the message type. A new TypedProperty object is created to hold the values to be passed to the JSP e-mail template. The PriceWatchEmail bean that contains the values is added to this object. The compose() method of the command is used to set the TypedProperty object to be used in the JSP, the current command context, and the view name that points to the JSP template. When this is invoked, the JSP code is executed to compose the contents of the e-mail message. The subject field of the e-mail, the sender e-mail address, and the recipient’s e-mail address are set using the setConfigData() method of the SendMsgCmd command. The sendImmediate() method is called to set the sending mode to send the message immediately to the recipients. The command context of the SendMsgCmd command is set with the current command context. This ensures that all the necessary parameters are passed on to the SendMsgCmd command. Finally, the execute() method is invoked. Note that the execution of this method halts here until the message is sent or an exception is thrown. In this case, if an exception is thrown, the method passes back to the command, which eventually passes it back to the Web controller. At this point, the error will be logged and the command will halt execution with an error. 5. Save your work by pressing Ctrl+S. 13.10.3 Import the data bean for the e-mail command In this section, we will import PriceWatchEmailBean.java to the workspace: 1. From the Java perspective, expand WebSphereCommerceServerExtenstionsLogic -> src -> com.ibm.itso.sample.databeans. 2. Right-click com.ibm.itso.sample.databeans and select Import. 3. Select File system and click Next. 4. Click Browse and navigate to the sample code directory, for example c:\6969code\pricewatch\code\WebSphereCommerceServerExtensionsLogic\ src\com\ibm\itso\sample\databeans. 5. Click OK. 6. Check the PriceWatchEmailBean.java file and click Finish. Chapter 13. Customize a store: Price Watch example 489 7. Rebuild the project by right-clicking WebSphereCommerceServerExtensionsLogic and selecting Build Project. Note that you can test this command from a browser if you wish. To do this, log onto the sample site as the administrator user and then enter the following URL into the address bar of the browser: https://localhost/webapp/wcs/stores/servlet/CheckPriceWatchPrices?langId=-1 &storeId=10001 Note: You will not be able to run this command until the rest of the steps in this chapter have been completed. Remember to substitute the storeId and langId appropriate to your store and to restart your server before running the command. If a blank page is returned, the command ran successfully. No JSP will be displayed as a view name was not specified in the response properties. Remember that this is not necessary, because the command will be run by the scheduler. 13.10.4 Register the new command in the command registry Before the new command can be used, it must be registered in the command registry. This is done by adding a new entry in the URLREG database table. In the DB2 Command Center or a DB2 Command prompt, ensure you are connected to your development database and then execute the SQL shown in Example 13-46. Example 13-46 SQL for registering the ManagePriceWatchList command insert into URLREG (URL,STOREENT_ID,INTERFACENAME,HTTPS,DESCRIPTION,AUTHENTICATED) values ( 'CheckPriceWatchPrices', 0, 'com.ibm.itso.sample.commands.CheckPriceWatchPricesCmd', 0, null, null ) Make sure you use the correct store ID in the SQL. Note that you should specify the interface name of the command, not the implementation class name. 490 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 13.11 Importing the e-mail template This section shows how to import the e-mail template into your workspace. The contents of the JSP are also discussed. 13.11.1 Adding the JSP to your workspace This section details how to import the price watch notification e-mail into the workspace. The source of the file is also described. To import the template, complete the following steps: 1. Open the Java perspective. 2. Expand Stores -> Web Content -> ToolTech. 3. Right-click the PriceWatch folder and select Import from the menu. The Import window will open. 4. Select File System from the list of sources. 5. Click Next. 6. Next to the Directory list, click Browse. 7. Navigate to the directory where you extracted the price watch sample (for example, c:\6969code\pricewatch\code\Stores\Web Content\ToolTech\PriceWatch). 8. Click OK. The folder you selected and its contents will be displayed in the Import window. 9. Select the PriceWatchEmail.jsp file from the right-hand pane. 10.Ensure that Create selected folders only is the only selected option in the Options frame. 11.Click Finish. The JSP will now be added to your workspace. 13.11.2 JSP content An e-mail template JSP is not very much different from a regular JSP page that is intended for display in a browser. Chapter 13. Customize a store: Price Watch example 491 Note: You may wish to look at the PriceWatchEmail(readable).jsp file included with the sample. The PriceWatchEmail.jsp is formatted to minimize the number of leading blank lines in the generated e-mail. This is described later in this section. The first section of the source contains the standard imports and the page-specific imports. The PriceWatchEmail bean is retrieved using the tag. The ItemDataBean is used to retrieve the description of the item as in the PriceWatchList.jsp. An instance of the NumberFormat class is used to format the prices for display. The following line of code sets the content type of the e-mail message. This particular implementation specifies an HTML format e-mail. You can, of course use the MIME type to specify a plain text e-mail. The String passed to this method will be inserted into the Content Type entry in the e-mail header. response.setContentType("text/html;charset=UTF-8"); If you want to know more about this topic, please refer to: http://www.w3.org/Protocols/rfc1341/4_Content-Type.html The remainder of the code that is outside the scriptlet tags () forms the body of the e-mail. Blank lines in the e-mail If you were to use the readable version of the JSP, you would notice a number of empty lines in the e-mail. This is a result of the fact that every CR-LF (Carriage Return - Line Feed) character that exists in the JSP source and is outside of scriptlet tags will form part of the message body. The way to avoid this is to remove these extraneous CR-LFs from the source. For example, lines that appear as in Example 13-47 should be reformatted to appear as in Example 13-48. Example 13-47 Example of code that will result in extraneous blank lines Example 13-48 Code shown in above example with CR-LFs removed Removing the CR-LFs that lie outside of the tags will result in unreadable code in some cases. It is advisable to keep an original copy of your JSP before removing the offending characters. This will make maintaining the JSP much simpler. 13.11.3 Registering a new view for the e-mail template As with the price watch list JSP, we must also create a new view for the e-mail template. This is done by adding a new entry in the VIEWREG database table. In the DB2 Command Center or a DB2 Command prompt, ensure you are connected to your development database and then execute the SQL shown in Example 13-49. Example 13-49 SQL for registering PriceWatchNotificationEmailView insert into viewreg (viewname,devicefmt_id,storeent_id,interfacename, classname,properties,description,https,lastupdate) values ( 'PriceWatchNotificationEmailView', -3, 10001, 'com.ibm.commerce.messaging.viewcommands.MessagingViewCommand', 'com.ibm.commerce.messaging.viewcommands.MessagingViewCommandImpl', 'docname=PriceWatch/PriceWatchEmail.jsp', null, 0, null ) Make sure you use the correct store ID in the SQL. In this case, the devicefmt_id field contains -3. This specifies that the view is an e-mail template. This value refers to the entry in the DEVICEFMT table that defines the various types of view that can be registered. 13.12 Configuring the scheduler to run the batch job This section describes how to set up a scheduled command. Before a command can be scheduled, it must be registered in the SCHCMD database table. If the scheduled task is to run at store level, it must also be associated with a task command that checks if the task needs to run. This is not required if the Chapter 13. Customize a store: Price Watch example 493 command is to be scheduled at store level. In our example, we do not require a task command. The Administration Console can then be used to schedule the command for execution. 13.12.1 Make the command schedulable In order to make the command schedulable, an entry must be added to the SCHCMD table. The entries in this table are used by the Administration Console to populate the scheduler pages. The following information must be added to the table: The command name The store ID of the store that the command will be associated with A unique ID for this table entry If you intend to schedule the command at site level, the store ID should be set to 0 (zero). Note: If you do not wish to use the Administration Console to schedule your commands, you do not need to add an entry to SCHCMD. For example, you may wish to use a database script to manually create the necessary entries in SCHCONFIG and SCHSTATUS in order to schedule your commands. If your command is to be scheduled at store level, then you must associate your command with a check command. This is done by creating an entry in the CHKARRANG table. The unique ID assigned to your command in SCHCMD and the ID of the check command should be inserted as a row in this table. To make the CheckPriceWatchPrices command schedulable, complete the following steps: 1. Open the DB2 Command Center by clicking Start -> Programs -> IBM DB2 -> Command Line Tools -> Command Center. 2. Click the Interactive tab. 3. Connect to your development database by entering the following in the Interactive window: connect to user using Where: – is the database name. If you created your database with a different name when you installed WebSphere Studio Application Developer, substitute that name here. 494 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – is your DB2 user name. – is the password for your DB2 user. Press Ctrl + Enter or click the Execute button on the tool bar. The bottom pane should show a message confirming that the SQL ran successfully. 4. Enter the SQL shown in Example 13-50 in the Interactive window. Example 13-50 SQL to add CheckPriceWatchPrices to schedulable commands insert into schcmd (PATHINFO, SCHCMD_ID, STOREENT_ID) values ( 'CheckPriceWatchPrices', 1000, 10001 ) SCHCMD_ID must be a unique number not yet used in the SCHCMD table. In the default installation, 1000 is not used. 5. Press Ctrl + Enter. The bottom pane should show a message confirming that the SQL ran successfully. 6. Enter the SQL shown in Example 13-51 in the Interactive window. Example 13-51 SQL to associate the command with a task command insert into CHKARRANG (chkcmd_id, schcmd_id) values (-1, 1000) where -1 is the chkcmd_id of the Always Run task command and 1000 is the schcmd_id used in the SQL in Example 13-50. 7. Press Ctrl + Enter. The bottom pane should show a message confirming that the SQL ran successfully. The command will now be available in the scheduler configuration section of the Administration Console. 13.12.2 Configure the scheduler The next step is to use the Administration Console to add the scheduled job. For our example, we will be adding the scheduled job at store level. This is necessary because the command relies on having the storeId of our example store in the command context when it is executed. Chapter 13. Customize a store: Price Watch example 495 To configure the scheduler to run the CheckPriceWatchPrices command, complete the following steps: 1. Switch to the J2EE perspective. 2. In the Servers view, restart the WebSphereCommerceServer server. 3. Open a browser window and start the Administration Console using the following address: https://localhost/webapp/wcs/admin/servlet/ToolsLogon?XMLFile=adminconsole. AdminConsoleLogon 4. Log on to the Administration Console. 5. Select Store. 6. Make sure that our sample store is selected and click OK. The console window will open. 7. Select Configuration -> Scheduler. The scheduler should open and show that there are no scheduled commands. 8. Click New. 9. Select CheckPriceWatchPrices from the Job command list. 10.Enter a start date and time. Choose a time within five minutes or so of the current time. Enter the time in HH:mm format (24 hour). 11.In the Associated user text box, enter the administrator user name, that is, the name you logged on to the Administration Console with. This will ensure that the scheduler has the access rights to run the command. 12.Leave the Allowed host text box empty. This is used in a multi-host environment when the command is to be restricted to just one host. In the WebSphere Test Environment or a single host system, this is not required. 13.In the Schedule interval text box enter a suitable interval for running the command in seconds. Note, this interval needs to be long enough to avoid overlapping execution, since no attempt has been made to avoid this in our sample code. For test purposes with small amounts of data, five minutes is appropriate. Enter 300. 14.Leave the Job attempts and Seconds to retry text boxes empty. These define the number of retries and interval between retries the scheduler will attempt if the command fails. 15.Select Run only once from the Scheduler policy list. With this setting, if the command fails (after retries) then the job is abandoned and rescheduled for the next interval. With the Recover all missed runs option, the store job runs as many times as is necessary to recover all the missed runs. 496 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 16.Leave Job priority as 5, the default. 17.Leave the Application type option blank. This setting is used to constrain resource intensive jobs to a set number of threads. The default value is null (blank). 18.Set the Task to check if processing needed option to Always Run The Command. This option can be used to tell the scheduler to run a task command to perform some business logic to decide whether the scheduled command should be executed. For our example, we implemented a task command to check if there are any price watch list items for which the item price is lower than the watch price. The result of this check would determine whether to run the command. To implement such a task command, you should extend the CheckForWorkCmd interface instead of TaskCommand. This interface defines a method called checkProcessingNeeded(), which returns a boolean value. You should implement the checking logic in this method in the implementation class for the command. For more details, refer to the online help in WebSphere Studio Application Developer and search for CheckForWorkCmd. 19.Click OK. 20.Note that you can use the Administration Console to make your scheduled command active or inactive as you require. Important: Remember that the command that you wish to schedule at store level must be registered in the URLREG table as a site level command, that is, with a STOREENT_ID of 0 (zero). Chapter 13. Customize a store: Price Watch example 497 13.13 Testing the Price Watch example This section explains how to test the Price Watch example in the WebSphere Studio Application Developer environment. 13.13.1 Testing the new functionality The first thing to do is to make sure that you have saved all open files and rebuilt all the projects if you have used external editors. If the WebSphereCommerceServer server is running, you will need to restart it before your changes and new code will take effect. Starting the server for testing To start the server for testing, complete the following steps: 1. Click the Servers tab to open the Servers view. If this is not yet visible, click Window -> Show View -> (Other) -> Servers. 2. If the server is already running, right-click WebSphereCommerceServer and select Stop from the menu. 3. Right-click WebSphereCommerceServer and select Start from the menu. The Console view should open and you will see the trace output while the server is starting. When the server is started you will see the following line of trace: [7/22/03 11:23:59:750 EDT] 5e0a1212 WsServer server1 open for e-business A WSVR0001I: Server Tip: To expand a particular pane to fill the whole work area, double-click the pane’s title bar. To restore the pane to its original position, double-click the title bar again. It is useful to do this when looking at the Console view, since the lines of text are frequently longer than can be displayed normally. To confirm that the server has started, switch back to the Servers pane and you will see that the status will have changed to Started. 4. Complete steps for Technote 1114621 as documented in the post-install tasks of the Installation Guide, IBM WebSphere Commerce Studio V5.5 product guide. Clear the XPRICEWATCH table before testing When testing the XPriceWatch entity bean earlier in the chapter, we used arbitrary values. Prior to testing the price watch functionality within the store, we need to clear the XPRICEWATCH table of these values. 498 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide In a DB2 command window, ensure you are connected to the database and then run the following command: db2 delete from XPRICEWATCH The table will now be empty and ready for testing. Opening the store for testing The store can be tested in the WebSphere Studio Application Developer environment or in an external browser. To test in the development environment, complete the following: 1. If you are not already in the Java perspective, switch to it by clicking the Java Perspective icon on the left-hand toolbar. 2. Expand Stores -> Web Content -> ToolTech. 3. Right-click index.jsp and select Run on Server from the menu. A new view will open for browsing the store. You may be asked to confirm that you accept the SSL certificate for the store page, in which case, click Yes. The store logon page will be displayed as shown in Figure 13-18. Figure 13-18 Store logon page in the development environment Chapter 13. Customize a store: Price Watch example 499 Remember that you can expand the Web browser pane to fill the window by double-clicking on the title bar tab. As an alternative to using the integrated Web browser, you can use an external browser and enter the following address: http://localhost:9080/webapp/wcs/stores/servlet/ToolTech/index.jsp Add e-mail address to user profile After logging in to the store, update the e-mail address of the user by which you have logged into the store. The e-mail address must match the account you created in the James server in 13.4.1, “Setting up the James SMTP server” on page 403 (for example, admin@localhost). Important: At the time of writing this redbook, we discovered that the ToolTech sample did not preserve the currency setting for the user profile when updating other information for the user. For example, when updating the e-mail address, we found that the currency (was USD) was reset to Taiwanese, which is first in the list. To work around this issue, ensure that you select the proper currency when updating any user profile information. Adding a new price watch item The first test is to add a new price watch item. This will test the commands for adding a new watch price and displaying the price watch list. Also, the XPriceWatchBean will be tested, since rows will be added and read from the XPRICEWATCH table. Complete the following steps: 1. Log on to the store as the administrator user that you created when installing WebSphere Commerce Studio. 2. Click the Catalog option on the menu bar at the top of the page. 3. Click one of the product categories. 4. Click one of the products. 5. Click one of the items in the list. 6. On the item display page, click the radio button next to the contract description. 7. Choose a watch price that is less than the price of the item for the contract you selected. Enter that price in the Add Price Watch text box and click Add. You should now see the Price Watch List page as shown in Figure 13-19 on page 501. 500 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 13-19 Price Watch List page of the ITSO store Deleting from the price watch list To test that you can remove a single item from the list, click the Remove link next to the item. You should see the page refresh and a message stating that you have no items in your list. Repeat the steps to add an item to your price watch list twice. While on the Price Watch List page, click the Remove All button. All items in your list should be removed and you will, once again, see the message stating that your list is empty. Testing the scheduled job Next, we must test that the scheduled job is working correctly. To do this we must add a new price watch item to our list and then change the price of the item so that it is lower than the watch price. This will simulate a store manager changing the price of the item, which would trigger the price watch e-mail being sent to a customer. Chapter 13. Customize a store: Price Watch example 501 Important: Before continuing, be sure that the user you are logged in as has a valid e-mail address specified for the local test SMTP server. If it is not set up correctly, you may not receive the price watch e-mail. However, this would not prevent the example from running correctly, but the e-mail sending would obviously fail. To test that an e-mail is sent to a user when a price watch price criteria is met for the particular item, complete the following steps: 1. Add an item to your price watch list as above and make a note of the product, item, and watch price you used. 2. Open the WebSphere Commerce Accelerator using by entering the following address into your browser: https://localhost/webapp/wcs/tools/servlet/ToolsLogon?XMLFile=common.mcL ogon 3. Log on to the Commerce Accelerator. 4. Select the sample store from the list and click OK. A new browser window will open for the store you selected. 5. Select Products -> Product Management from the menu bar across the top of the page. 6. From the second menu bar, select Search. 7. In the Name text box, enter the name of the product for which you added the watch price. 8. Click Find. A list of matching products should be displayed, including the product that you chose. 9. Select the product by checking the box next to the product code. 10.On the second menu bar, select Actions -> Show SKUs. A list of all items that belong to the product you selected will be displayed. 11.Select the item for which you added the watch price (identify the correct one by the SKU or the part number) by checking the box in the appropriate row in the table. 12.From the second menu bar, select Prices -> Set Prices. 13.Change the price for the item to a new price that is less than the watch price you selected earlier for the item. 502 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 14.Click OK. You should see a window stating that the price was saved successfully. Click OK on that window. Restriction: When changing prices in the Commerce Accelerator as described above, you can only change the prices for the default contract. This does not matter in this example, because no additional contracts are defined. However, be aware that in a real-life environment, you are likely to encounter multiple contracts. You will now be returned to the items list page of the Accelerator. You should now log out of the Accelerator by clicking Logout in the screen flow diagram in the top right-hand corner of the page as shown in Figure 13-20. Figure 13-20 Log out of the Commerce Accelerator At this point, the next time the scheduler starts the CheckPriceWatchPrices job, the price change will be detected and compared to the watch price you chose. If it is lower (which it should be) then it will send an e-mail to the address specified in the user profile. If you set up an SMTP server and tested it using Outlook Express as described in 13.4.1, “Setting up the James SMTP server” on page 403, you should see the e-mail appear within the next scheduled interval. Chapter 13. Customize a store: Price Watch example 503 504 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 14 Chapter 14. Build and deployment This chapter describes how to build and package the ITSO working example application assets archive (JAR) and store archive (SAR) in the development environment. In addition, we provide a detailed procedure for deploying the application assets archive and store archive to the WebSphere Commerce runtime environment. The chapter is organized into the following sections: Build and deployment overview Build procedure Deployment procedure Note: The procedures documented in this chapter for build and deployment require that you have completed the procedures outlined in the following ITSO working example appendix/chapters: Appendix E, “WebSphere Commerce Studio implementation” on page 1005 Chapter 12, “Create a store” on page 341 Chapter 13, “Customize a store: Price Watch example” on page 393 © Copyright IBM Corp. 2003. All rights reserved. 505 14.1 Build and deployment overview Figure 14-1 shows an overview of the steps involved in building and deploying the store and application assets. Team Environment Stand-alone Environment Check out from CVS Modify build scripts Modify build scripts build store archive build deploy tool archive build store archive build deploy tool archive check in store archive to CVS check in deploy tool archive to CVS tag files in CVS execute deploy tool publish store archive execute deploy tool publish store archive Figure 14-1 Overview of the build and deploy steps There are a few key points to make regarding the build and deployment process. 506 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide First, as mentioned earlier in this redbook, we recommend using store archives for a means of packaging and deploying store front-end assets and for populating store-level WebSphere Commerce database values. Second, when the Packaging project was created in 12.2.2, “Create the Packaging project” on page 344, a special deployment tool for the use of deploying other assets, such as customized commands and EJBs, was added to the development workspace. Third, the deployment tool, known as DeployTool, is necessary to deploy Java application assets packaged in JARs. These Java application assets are not packaged within the store archive. Note: Although this is a limitation of the store publishing process, we recommend using store archives for the deployment of store front assets and store-level WebSphere Commerce database content. The reason for this is that although the deployment tool could be customized to deploy these assets, the Accelerator Store Publish tool does contain capabilities that extend beyond those of the deployment tool. These include the ability to publish contracts and configure WebSphere Commerce Payments information for the store. Finally, not all steps defined in Figure 14-1 on page 506 are required for the build and deployment process. For example, a customer engagement may only require that assets within the store archive be modified. In this case, the deploy tool steps would be omitted. 14.2 Build procedure In this section we will show how to build and package a new version of a store archive and Java application assets JAR from the source files. The build procedure outlined is for the ITSO B2B working example within a team development environment on the Build and SCM node. Note: The build procedure described will also work in a stand-alone development environment by omitting the CVS instructions (see Figure 14-1 on page 506). This build procedure for a team development environment is organized as follows: Check out source from CVS to Build and SCM node Modify store archive build script and unpack descriptor Chapter 14. Build and deployment 507 Modify database SQL scripts and XML files Build application assets archive (JAR) Build store archive (SAR) Build verification test (BVT) Source configuration management (SCM) of build files 14.2.1 Check out source from CVS to Build and SCM node The first step is to ensure that the correct versions of the files have been checked out of the CVS repository to the file system on the Build and SCM node. In some cases, you might want to check out specific versions of the files. In our example, we will check out the latest versions of all the files. 1. Change to the Resource perspective in WebSphere Commerce Studio. 2. Select the following projects: – – – – Packaging Stores WebSphereCommerceServerExtensionsData WebSphereCommerceServerExtensionsLogic 3. Right-click one of these projects and select Team -> Update. Repeat this step for each of the projects listed. 14.2.2 Modify store archive build script and unpack descriptor Before the customized code can be built and packaged, the build.xml Ant script and unpack.xml descriptor will need to be modified. This operation only needs to be done the first time a store archive is packaged for deployment, or if the store directory has been changed. Modify build.xml script We have supplied a sample build.xml Ant script for building a store archive. This script can build a full store archive or an archive that only contains the database assets for the store. The full store archive is used to deploy a store to a WebSphere Commerce runtime, such as a test or production system. The database-assets-only archive is used in a development environment to seed or update the development database. For details, see 12.8.3, “Package and publish data-only store archive” on page 392. Note: This step is not required if you chose to use ITSO as your store directory name. 508 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide The build script (build.xml) should be modified such that the property STOREDIR matches the store directory of your store. Alternatively, you can specify the following parameter when executing the Ant build script: -DSTOREDIR= -DARCHIVE_NAME= Where: is your store directory’s name. The build.xml file included with redbook sample code is set to use ITSO as the default store directory. is the WebSphere Commerce store archive name without the .sar file extension. If not specified, the store archive name will default to ITSO. Modify store archive unpack descriptor The file unpack.xml, located in the SARFile/SAR-INF folder of the Packaging project, is a control file used by the store publishing process to determine where to unpack the files from the store archive. The unpack.xml file refers to the locations of the files in the store archive. The unpack directory for the B2BDirect.sar is ToolTech. When we repackage the files later in this chapter, the files will be in different directories from the ones specified by the unpack.xml file. Important: The B2BDirect store archive sample was designed to have the unpack directory be renamed from ToolTech to the target store directory name after the files had been unpacked on the target WebSphere Commerce runtime file system as part of the publishing process. In our example, we first modified the unpack.xml to specify ITSO as the unpack directory. When the store archive is packaged, it will contain the proper value for the unpack directory in preperation for publishing. To update the unpack.xml file to include the proper directories, replace all occurrences of the string ToolTech in the unpack.xml file with the string ITSO (store directory name). A modified unpack.xml file can be seen in Example 14-1. Example 14-1 Example SAR-INF/unpack.xml with the new store directory Chapter 14. Build and deployment 509 Important: We found that if you do not modify the unpack.xml file, as described in Example 14-1, the Store Publish wizard may hang after clicking Finish on the summary page. If it does hang, a NullPointerExceptions may be listed in the \logs\WC_\SystemErr.log file. 14.2.3 Modify database SQL scripts and XML files This section describes the modifications that need to be made to the database SQL scripts used by the DeployTool and XML file updates found in the store archive. Modify database SQL and XML used by the DeployTool When deploying customized application assets, it is often a requirement that you perform updates to the WebSphere Commerce instance database such as the following: Add new database table(s) Add new entries for commands in URLREG, VIEWREG, CMDREG tables Modify site level database table entries, such as SCHCMD and MSGTYPES The DeployTool provides SQL scripts found in the DeployTool/wcs/schema folder that can be modified to include database changes as part of the deployment process when using the DeployTool. 510 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide For the ITSO B2B working example price watch customizations, we made the following updates to the DeployTool SQL scripts in preperation for deployment: 1. Modify deploy.createdb.sql. In order to create a new XPRICEWATCH table for the price watch example, we modified the DeployTool/wcs/schema/db2/deploy.createdb.sql to contain the SQL statements as seen in Example 14-2 Example 14-2 ITSO example deploy.createdb.sql create table xpricewatch ( memberid bigint not null, catentry_id bigint not null, contract_id bigint not null, watchprice decimal(20,5) not null, constraint p_memberid primary key (MEMBERID,CATENTRY_ID,CONTRACT_ID), constraint f_memberid foreign key (memberid) references users (USERS_ID) on delete cascade, constraint f_catentry_id foreign key (catentry_id) references catentry (catentry_id) on delete cascade, constraint f_contract_id foreign key (contract_id) references contract(contract_id) on delete cascade ); Note: The ITSO modified deploy.createdb.sql can be found in the c:\6969code\pricewatch\data\DeployTool\wcs\schema\db2 directory. 2. Modify deploy.populatedb.commerce.xml. The deploy.populatedb.commerce.xml is used to populate the site level database changes that cannot be updated using the store archive XML files. We modified the DeployTool/wcs/schema/xml/deploy.populatedb.commerce.xml file to contain the elements listed in Example 14-3 on page 512. Chapter 14. Build and deployment 511 Example 14-3 ITSO example deploy.populatedb.commerce.xml Note: The ITSO modified deploy.populatedb.commerce.xml can be found in the c:\6969code\pricewatch\data\DeployTool\wcs\schema\xml directory. Modify database XML file for store archive When creating the ITSO store, as documented in Chapter 12, “Create a store” on page 341, we modified many store level data XML files. Example 14-4 lists the elements we added to the command.xml file for the Price Watch customized views and commands. Example 14-4 ITSO example command.xml additions Note: The ITSO modified command.xml can be found in the c:\6969code\pricewatch\data\SARFile\WEB-INF\stores\BusinessDirect\data\T oolTech\data directory. Notice, that this path includes ToolTech. We were unable to devise a simple method of updating the data directory within the store archive to match the store directory name. We did not find this to have an adverse effect to the functionality of the store. Chapter 14. Build and deployment 513 14.2.4 Build application assets archive (JAR) The DeployTool supplied with the ITSO samples is used to build, package, and deploy the application assets. The applications assets include site-level database assets, database schema changes, customized commands, and EJBs. To build the application assets archive (JAR) using the DeployTool, do the following: 1. Ensure you have met the prerequisites for using the DeployTool. a. Prepare the DeployTool. For details refer to 10.2, “Prepare DeployTool files” on page 321. If you have not completed this step prior to importing the deploy tool, you will need to import the files into the Packaging project. b. The DeployTool requires that the application assets to be built and packaged are in the following projects with WebSphere Commerce Studio (WebSphere Commerce workspace): • • 514 WebSphereCommerceServerExtensionsData WebSphereCommerceServerExtensionsLogic WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: If you have completed Chapter 13, “Customize a store: Price Watch example” on page 393, the Price Watch customized application assets will be in the above-mentioned projects within WebSphere Commerce Studio. There are some application assets that have been updated within the c:\6969code\pricewatch directory for deployment to the runtime, such as the deploy.createdb.sql that are not mentioned in Chapter 13, “Customize a store: Price Watch example” on page 393. For the purposes of understanding how the DeployTool works, you can import the Price Watch application assets from the c:\6969code\pricewatch directory as follows: 1. From WebSphere Commerce Studio, select the WebSphereCommerceServerExtensionsData project and right-click Import. 2. Select File system and click Next. 3. Enter the path to the build directory of the additional material supplied with this redbook in the Directory field, for example: c:\6969code\pricewatch\code\WebSphereCommerceServerExtensionsData 4. Ensure that the check box next to the WebSphereCommerceServerExtentionsData folder is checked. Click Finish. 5. When asked if you want to overwrite existing files, click Yes To All. 6. Select the WebSphereCommerceServerExtentionsData folder, and right-click Build Project to ensure the project source is compiled. 7. Repeat the steps above for the WebSphereCommerceServerExtentionsLogic project, and by substituting the following directory: c:\6969code\pricewatch\code\WebSphereCommerceServerExtensions Logic 8. From WebSphere Commerce Studio, change to the Resource perspective. 9. Expand the project Packaging. 10.Expand the folder DeployTool. 11.Right-click the file build.xml and select Run Ant. 12.Ensure that the only selected target is driver (Default) and click Finish. 13.Within WebSphere Studio Application Developer, you must right-click the DeployTool folder and select Refresh for the deploy-.jar to be visible. Chapter 14. Build and deployment 515 The script will execute and in the DeployTool folder you should see a file with the name deploy-.jar, where is the current date. Note: The execution of the build.xml script for the DeployTool can involve the compilation of a large number of files, and thus the execution may take some time. Also, because many of the files being compiled are generated Java code, the compiler may issue a large number of compilation warnings while the build script is being run. 14.2.5 Build store archive (SAR) In this step, we will build the store archive. The store archive is used to deploy the store front assets, and database assets for the store. To build the store archive, do the following: 1. Change to the Resource perspective in WebSphere Commerce Studio. 2. Expand the project Packaging. 3. Expand the folder SARFile. 4. Right-click the file build.xml and select Run Ant. 5. Ensure that the target build-sar-full is the only selected target. 6. Ensure that the Arguments field is empty, or contains the argument as mentioned in “Modify build.xml script” on page 508. 7. Click Finish. Tip: After the build.xml Ant script has been run once, it can be easily re-run by selecting Run -> External Tools -> /Packaging/SARFile/buils.xml from the main menu. The script will be executed and a file with the name of the store identifier and extension .sar will be created in the SARFile folder. In our example, the file is called ITSO.sar. Within WebSphere Studio Application Developer, you must right-click the SARFile folder and select Refresh for the ITSO.sar to be visible. 14.2.6 Build verification test (BVT) Before proceeding to the next step, we recommend that you do a build verification test on the output of the build. The testing is performed by deploying the generated build files (see 14.3, “Deployment procedure” on page 519 for 516 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide details about deployment procedures) to a test runtime environment. This is done to ensure that a faulty package is not added to version control in the next section, and that the build is working properly by executing basic usage tests. 14.2.7 Source configuration management (SCM) of build files This step is optional, but we do recommend using the configuration management facilities of your source control system to enable access to historical builds. In CVS this is done by marking the revisions of the source files with a tag. We also recommend that deployed build files are checked back into the source control management system. Check in packaged deployment assets It is a good idea to store the packaged deployment assets in a separate CVS project to keep a history of deployed assets. To create a project for storing deployment assets, do the following for the initial setup. 1. Open the Resource perspective in WebSphere Studio Application Developer. 2. Select File -> New -> Project. 3. In the left pane, select Simple. Select Project in the right pane and click Next. 4. Enter BuildFiles as the Project name and click Finish. 5. Right-click the BuildFiles project and select Team -> Share Project. 6. Select the CVS repository location, or configure a new location and click Finish. To check-in the packaged deployment assets into CVS, do the following each time a new package is deployed: 1. Open the Resource perspective in WebSphere Studio Application Developer. 2. Right-click the file you wish to check in, for example Packaging/SARFile/ITSO.sar, and select Copy. 3. Right-click the BuildFiles project and select Paste. 4. If the file already exists in the BuildFiles project, WebSphere Studio Application Developer will prompt for confirmation. Click Yes. 5. If this is the first time the build file is checked into CVS, the file must be added by right-clicking the file in the BuildFiles project and selecting Team -> Add to Version Control. 6. Right-click the file in the BuildFiles project and select Team -> Commit. Chapter 14. Build and deployment 517 7. Enter a description of the build and click OK. 8. Repeat the check-in process for the file Packaging/DeployTool/driver-.jar. Tip: We recommend that you check in the deployment package each time it will be deployed. Mark the source and build files We recommend that the build files, as well as the source files that make up the build files, be marked or tagged in CVS terms so that they can be identified later if needed. For example, file A is level 1.1, and file B is level 1.5. The selection of A and B for the build at the levels stated is the build level. The files can be marked as follows: 1. Open the Resource perspective in WebSphere Studio Application Developer. 2. Highlight the projects that contain the source files. In our working example, we highlighted the following projects: – – – – – SARFile Stores WebSphereCommerceServerExtensionsData WebSphereCommerceServerExtensionsLogic BuildFiles 3. Right-click one of the highlighted projects and select Team -> Tag as Version. Repeat this step for each of the projects listed. 518 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: If you have any uncommitted files in any of the selected projects, WebSphere Studio Application Developer will show the following confirmation dialog: This should not occur, since this means that either the build modules have been created using locally modified source files or that the build files have not been committed as described in the previous section. Click Cancel and resolve the problem. 14.3 Deployment procedure This section describes the procedure for deploying the artifacts that were built in 14.2, “Build procedure” on page 507. The deployment procedure is split into two steps: Publish the store archive (SAR) In this step, the store archive, containing store front assets and store-specific database assets, are deployed. Deploy application assets archive (JAR) In this step, the assets defining EJBs, commands, database schema modifications, loading of data to custom tables, and store-independent data are deployed to the target node. Note: In our example, the sequence of deployment for the store archive or application assets archive can be interchanged. There are some situations that you may be required to deploy the application assets archive before the store archive. For example, if you have added a new language to the application assets archive. The bootstrap data for the language may be contained in the application assets archive. Chapter 14. Build and deployment 519 14.3.1 Publish the store archive (SAR) This section describes the steps needed to publish a store archive to the WebSphere Commerce runtime environment. Prepare environment for store publish To prepare the environment for the publishing of the store archive, do the following: 1. Back up the WebSphere Commerce instance database and the WebSphere Commerce Payments database. We recommend that the database be backed up before publishing, so that you will be able to restore the database to its previous clean state before publishing in the event of a publishing failure. For details refer to “DB2 backup and restore” on page 988 for information about how to back up and restore DB2 databases. 2. Start application servers. Ensure the WebSphere Commerce application server and WebSphere Commerce Payments application server are started (including IBMPayServer). 3. Copy the SAR file (for example, ITSO.sar) to the target node. For example, copy the ITSO.sar from the Development node to the WebSphere Commerce runtime node as follows: From: \Packaging\SARFile\ITSO.sar Where is the install path of the WebSphere Commerce Studio workspace. To: \instances\\sar Where is the install path of WebSphere Commerce, and is the WebSphere Commerce instance name. 520 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Tip: For custom store archives, we recommend that you copy the customized store archive to a subdirectory called sar within the instance directory. If WebSphere Commerce is installed in the directory and the instance is called , the store archive must be put in the following directory: \instances\\sar Note: As an alternative, you can update the SARRegistry.xml as described in “Register a store archive” on page 101. If you wish to publish a store archive to a WebSphere Commerce Studio instance installed in , the store archive must be copied to: \Commerce\instances\\sar You may need to create the sar directory if it does not exist on your system. Publish store archive To publish the store archive, do the following: 1. Start the WebSphere Commerce Administration Console by entering the following URL in the Microsoft Internet Explorer Web browser. https://:8002/adminconsole Where is the host name of the WebSphere Commerce node, 8002 is the virtual host port defined in the httpd.conf and WebSphere Application Server, adminconsole is the alias defined in the httpd.conf and https is used (SSL enabled). Note: The WebSphere Commerce administration tools required Microsoft Internet Explorer V5.5 or higher. In our example, we used Internet Explorer V6 + Service Pack 1. 2. Log on with the site administrator ID (for example, wcadmin). 3. Select Site and click OK. 4. From the menu, select Store Archives -> Publish. 5. From the Store Archives page, the view is set to Default, which lists the composite (full-featured store archives) for each business model supplied with WebSphere Commerce. Check ITSO.sar and then click Next. 6. On the Parameters page, click Next. Chapter 14. Build and deployment 521 7. When the Summary page appears, click Finish to begin the publishing process for the store archive. 8. Store publishing will schedule a job, since this is a long-running task. You can monitor the store publish on the Publish Status page by clicking Store Archives -> Publish Status. If successful, the publishing status will change to Successful. 9. After the Publish Status changes to Successful, check the check box for the given publishing job, and click Details. 10.Click Launch Store, and click OK for the application Web path for the store. 11.Add the URL of the store to Favorites and then close the Web browser window. Compiling JSPs for tools and store We recommend that you precompile your JSPs for the WebSphere Commerce tools and store. For details refer to “Compiling JSPs for tools and store” on page 578. Create test shopping transaction Register a new user and complete a shopping transaction to verify the newly published store. For details refer to “Create a test shopping transaction” on page 581 Verify payment After the order is completed, the order should be awaiting payment approval within WebSphere Commerce Payments, assuming you used the default offline cassette. For details refer to “Verify payment” on page 581. 14.3.2 Deploy application assets archive (JAR) Important: In order to deploy EJB assets developed in WebSphere Commerce Studio V5.5, you must upgrade to WebSphere Application Server V5.0.1 (Fix Pack 1) or higher in the WebSphere Commerce runtime environment. In our scenario, we installed WebSphere Application Server V5.0.1 (Fix Pack 1) as documented in 16.2, “Single-tier implementation” on page 559. 522 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide The following steps detail the usage of the deployment tool to deploy non-store front assets, such as EJBs, commands, etc.: 1. Stop application servers. Ensure the WebSphere Commerce application server and WebSphere Commerce Payments application server are stopped (including IBMPayServer). 2. Create the directory \instances\\deploy. 3. Copy the application assets archive (JAR) file that was built in 14.2.4, “Build application assets archive (JAR)” on page 514 to the \instances\\deploy directory. 4. Open a commmand window, and change to the \instances\\deploy directory. 5. Execute the following command from that directory: \java\jre\bin\java -jar driver-.jar Where is the path where WebSphere Application Server is installed and is the time stamp of the driver file. 6. The deployment tool will prompt you for some information about the environment. We entered the following values: – Target environment: WAS – Root directory for WebSphere Commerce Server: c:\ibm\wc – Password for the WebSphere Commerce database user: Important: When the deployment script runs, it prints out the commands that it is executing to the console. Unfortunately this includes the password specified above. Consequently, for security reasons, you should not leave the machine unattended while this script is running on a production system. 7. When the Deploy Tool has finished, you should see output in the command window similar to Example 14-5. Example 14-5 DeployTool sample output in command window Enter the target environment. Either WAS or WSAD. WAS The root directory for WebSphere Commerce Server was not found at: C:\Program Files\WebSphere\CommerceServer55 Specify the root directory for WebSphere Commerce Server. c:\ibm\wc Specify the password that should be used with user "admin". password Installing files Installing EJBs Chapter 14. Build and deployment 523 Generating deployed code "c:\ibm\wc\bin\deployEJB.bat" C:\ibm\was\installedApps\wcwin1\WC_wc1.ear WebSphereCommerceServerExtensionsData.jar Fixing datasource Installing commands Installing web assets Creating Custom tables "c:\ibm\wc\bin\deployCreatedb.db2.bat" wc1 admin password ADMIN Populating Database "c:\ibm\wc\bin\deployPopulatedb.db2.bat" wc1 admin password ADMIN "c:\ibm\wc/instances/wc1/logs" "c:\ibm\wc/instances/wc1/xml/loader/WCALoggerConfig.xml" Installation complete 8. Review the DeployTool log files listed in Table 14-1. Table 14-1 describes the purpose of the deployment-related log files that can be found in the \logs directory. Table 14-1 Description of DeployTool logs stored in \logs Log file Purpose deploy.populatedb.log Output from running the populate scripts deploy.createdb.log Output from running the database scripts deploy.ejb.log Output from running the ejbDeploy tool Table 14-2 describes the purpose of the deployment-related log files that can be found in the directory \instances\\logs. Table 14-2 Description of logs stored in \instances\\logs Log file Purpose trace.txt Trace messages from mass loading messages.txt Error messages from mass loading deploy.populatedb.custom.error.xml Error messages from loading the custom bootstrap data. The former contains error messages resulting from the attempt to run the ID resolver, while the latter contains errors from the mass loader. deploy.populatedb.custom.BootStrap.error.xml deploy.populatedb.commerce.error.xml deploy.populatedb.commerce.BootStrap.error.xml 524 Error messages from loading the commerce bootstrap data. The former contains error messages resulting from the attempt to run the ID resolver, while the latter contains errors from the mass loader. WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 14.3.3 Load access control policies To load the access control policy file developed in 13.7.7, “Create access control policies for the commands” on page 461, do the following: 1. Copy the c:\6969code\pricewatch\PriceWatchACPolicy.xml to the \xml\policies\xml directory. 2. Open a command window, and change to the \bin directory. 3. Enter the following command to load the access control policy: acpload PriceWatchACPolicy.xml Where: – is the name of the WebSphere Commerce instance database. – is your DB2 administrator user – is the DB2 password If the command runs correctly, you will see the following output: Running XMLTransform... Running Id Resolver... Running MassLoader... 4. Review the \xml\policies\xml directory for the PriceWatchACPolicy*.error.xml for error messages. 5. For these changes to take effect, you must restart the WebSphere Commerce application server. The access control policies are stored in the WebSphere Commerce instance database and then cached. As an alternative to server restart after loading the access control policies, refresh the access control registry from the WebSphere Commerce Administration Console. a. From the WebSphere Commerce Administration Console, select Configuration -> Registry. b. Check Access Control Policies and click Update. c. Check Access Control Resources and click Update. d. Click Refresh. The status should change to Updated. 14.3.4 Configure e-mail for Price Watch In order to fully test the Price Watch customizations in the runtime environment, the e-mail transport and scheduler must be configured. 1. Install and configure e-mail server. For example, we set up James. For details see 21.7.1, “Java Apache Mail Enterprise Server (James) configuration” on page 950. Chapter 14. Build and deployment 525 2. Enable e-mail transport for WebSphere Commerce. See 21.7.2, “Enable the e-mail transport” on page 954 for details. 3. Configure the e-mail message type for Price Watch. See 13.4.4, “Configuring the e-mail message type” on page 405. 4. Configure scheduler for Price Watch. See 13.12, “Configuring the scheduler to run the batch job” on page 493. 14.3.5 Verify the runtime and store At this stage the application assets archive and store archive have been deployed. You will need to restart the WebSphere Commerce application server if you have not done so already for the deployment changes to take effect. Test the runtime and store functionality to validate the deployment. For details on testing Price Watch, refer to 13.13.1, “Testing the new functionality” on page 498. 526 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 15 Chapter 15. Manage the ITSO store This chapter includes administration tasks performed on the ITSO store. We have selected the following tasks to highlight some key features of WebSphere Commerce and provide details for the use cases identified in Chapter 9, “Requirements analysis and solution design” on page 291. The chapter is organized into the following topics: Product management Create organizations Create a business account Create a contract Note: Refer to the IBM WebSphere Commerce V5.5 online documentation for more information on product management, organizations, business accounts and contracts. © Copyright IBM Corp. 2003. All rights reserved. 527 15.1 Product management For the purposes of demonstrating how to use the WebSphere Commerce Accelerator Product Management tooling, we will create a new category and add a new product. 15.1.1 Add a category For the ITSO working example, we will add the Rational software and Rational redbook categories to the respective software and redbook parent categories. 1. Start the WebSphere Commerce Accelerator. The majority of the task can be performed by the product manager. For simplicity we will log on as the site administrator, as follows: https://:8000/accelerator 2. From the Accelerator menu, select Products -> Categories. 3. From the right-hand navigational options, click New. 4. When the General page of the add new category appears, we entered the following and then clicked Next: – Category Code (required): Rational-Software – Name (required): IBM Rational Software – Description: The IBM Rational software provides a development platform that integrates software engineering best practices, tools, and services. – Check Display to customers. – Check To be used in contracts. 5. When the Parent page appears, select the category that you would like the category you are adding to be under and then click Finish. For example, we selected the Software category as defined in 9.3.4, “ITSO store catalog hierarchy” on page 317. 6. Repeat this process to create the Rational-Redbook category. 15.1.2 Add a product In this example, we will add new products for IBM Rational XDE™ Developer, Java Edition V2003.06 to the Rational software category, and the IBM Rational XDE Developers Guide, SG24-9999 redbook to the Rational redbook category. This example requires that you have already created categories for Rational-Software and Rational-Redbook. 528 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide To add a product, complete the following tasks: Add product Add defining attributes Add SKU Add a price to a product Verify product page displays product Add redbook product for ITSO example Add product To add a product, do the following: 1. Start the WebSphere Commerce Accelerator. The majority of the task can be performed by the product manager. For simplicity, we will log on as the site administrator, as follows: https://:8000/accelerator 2. From the Accelerator menu, select Products -> Product Management. The empty Product Management dynamic table page appears. If you do not see this menu, then your logon ID does not have the appropriate authority to perform this task. 3. Select Actions -> New Product. 4. When the General page displays to add a new product, we entered the following values for the ITSO example and then clicked Next: – Code (required): rational-xde-java-2003 The product uniquely identifies the product within the WebSphere Commerce catalog. – Name (required): IBM Rational XDE Developer, Java Edition V2003.06 This is the descriptive name of the product. – Announcement date: we left this blank In the Announcement Date field, add the year, month, and day that the product becomes available to customers (informational only). – Withdrawal date: we left this blank In the Withdrawal Date field, add the year, month, and day that the product is removed from the catalog and is unavailable for customers to purchase (informational only). – Check Display to customers. – Check For purchase. Chapter 15. Manage the ITSO store 529 5. When the Description page appears, we entered the following and then clicked Next: – Short description: IBM Rational XDE Developer, Java Edition V2003.06 – Long description 1: IBM Rational XDE Developer, Java Edition V2003.06 provides a complete visual design and development environment and allows users to work in a single environment, thereby avoiding the need to switch between numerous tools. It is so flexible that it can be implemented three ways: alone via the included Eclipse IDE, installed into the IBM WebSphere Studio Application Developer or installed into the Microsoft Visual Studio .NET. – Long description 2: we left this blank – Long description 3: we left this blank 6. When the Category page appears, select the desired category to list the product under and then click Next. In our example, we selected the IBM Rational Software category (under the Software category) for the ITSO store. 7. When the Images page appears, enter the following and then click Next: – Full size image file and location: – Thumbnail image file and location: 8. For the purposes of this example we clicked Finish at this point. We do not complete the following settings pages: – – – – – – Manufacturer Sales Tax Shipping Tax Units of Measure Fulfillment Advanced. You may need to update the settings on these pages for your needs. 9. You should see a message “The product has been successfully created”. Click OK. Add defining attributes To add defining attributes to a product, do the following: 1. From the WebSphere Commerce Accelerator, select Products -> Find Catalog Entries. 2. When the Catalog Entry Search page appears, enter the code to find the product you have created. For example, we entered rational-xde-java-2003 for the code and then clicked Find. 530 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 3. Check the product code in the product (for example, rational-xde-java-2003). 4. From the menu bar, select Tools -> Defining Attributes. 5. When the list of available defining attributes for the product appears, click New. 6. When the New Attribute page appears, we entered the following: – Language: we selected English – Name (required): Media – Description: Media type (CD or Zip) – Type: we selected Text (possible options include Text, Whole Number, Decimal Number) – Click Add Value 7. When the Value text field appears to add a value to the defining attribute, we entered CD and then clicked Add. 8. We then clicked Add Value again, entered Zip for the value, and then clicked Add. 9. Click OK to save the attribute. 10.You should see a message “Attribute created successfully”. Click OK. Add SKU At this stage we have a product and a defining attribute with two values. The SKU is used to represent the product and defining attribute value to create a unique item to be purchased. You can add the SKU by manually typing the SKU code, or by clicking Generate SKU. In either case, the SKU must be unique. To add a SKU to the product by adding the SKU manually, do the following: 1. From the WebSphere Commerce Accelerator, select Products -> Find Catalog Entries. 2. When the Catalog Entry Search page appears, enter the code to find the product you have created. For example, we entered rational-xde-java-2003 for the code and then clicked Find. 3. Check the product code in the product (for example, rational-xde-java-2003). 4. From the menu bar, select Tools -> Defining Attributes. 5. Click New under the SKUs heading. 6. When the General page appears, enter the following then click Next: – SKU code (required): rational-xde-java-2003-cd Chapter 15. Manage the ITSO store 531 – Name (required): IBM Rational XDE Developer, Java Edition V2003.06 (name value should exist by default) – We accepted defaults for remaining options 7. When the Description page appears, we accepted the values for the description, and clicked Next. 8. When the Attributes page appears, we selected the value CD from the Media drop-down list for our example and then clicked Finish. 9. You should see a message “The SKU has been successfully created”. Click OK. 10.For our example, we created a SKU code for rational-xde-java-2003-zip for the Zip download media type of the software. Add a price to a product To add a price to the product, do the following: 1. From the WebSphere Commerce Accelerator, select Products -> Find Catalog Entries. 2. When the Catalog Entry Search page appears, enter the code to find the product you have created. For example, we entered rational-xde-java-2003 for the code and then clicked Find. 3. Check the product code in the product (for example, rational-xde-java-2003). 4. From the menu bar, select Prices -> Set Prices. 5. When the Pricing page appears, enter the following: – Currency: we selected USD -- Preferred – List Price: 5000 (informational only) – Offer Price: click Add Price Range When asked to enter the offer Price of Start Unit 1 and up, we entered 5000 and then clicked OK. 6. You should see a message “Prices saved successfully”. Click OK. Verify product page displays product Now that you have added a product, we recommend that you verify that the new product is displayed under the desired category and product page by navigating to your store. 532 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Add redbook product for ITSO example When done, repeat the process to add the IBM Rational XDE Developers Guide, SG24-9999 redbook product to the Rational-Redbook category. The product code is rational-xde-developers-redbook. The defining attribute is media type and the attribute values for the redbook are PDF or hardcopy. The item SKUs are rational-xde-developers-redbook-pdf and rational-xde-developers-redbook-hardcopy. The price of the redbook is $40. 15.2 Create organizations This section describes how to create the seller and buyer organizations for the ITSO example in support of creating a business account and contract. 15.2.1 Organizations in ITSO store archive There are several methods in which organizations are created. The Root Organization and Default Organization are created during the WebSphere Commerce instance creation process. In addition, organizations are created using XML files, which are contained in the store archive, or by using the WebSphere Commerce Organization Administration Console. As part of our store customization, we created a Buyer Organization to be used as a container organization for new buyer organizational units to be created under. In addition, we configured dynamic role assignment for the buyer organizations, and configured the business entity flag. For details, refer to 12.5.3, “Organizations” on page 373 on the customizations made to XML files found in the ITSO store archive (ITSO.sar). 15.2.2 Create seller organization This section describes the high-level steps for creating the seller organization using the WebSphere Commerce Organization Administration Console: Create seller organization Define approval tasks for seller organization Assign roles to seller organization Create seller organization administrator user Assign roles seller organization administrator user Verify seller administrator logon to tools Create seller organization The organization can be created from the WebSphere Commerce Organization Administration Console. Chapter 15. Manage the ITSO store 533 In our example, we created the Seller Organization and B2B Organization as part of the store archive and have been published. Define approval tasks for seller organization This step is optional (includes approvals, order processing, etc.). In our example, the defined tasks are included in the ITSO store archive and have been published. Assign roles to seller organization Roles can be assigned from the WebSphere Commerce Organization Administration Console. In our example, the defined roles were assigned and included in the ITSO store archive. Create seller organization administrator user To create a user from the WebSphere Commerce Organization Administration Console to be used by the seller organization, do the following: 1. Start the WebSphere Commerce Organization Administration Console. For simplicity we will log on as the site administrator, as follows: https://:8004/orgadminconsole 2. From the menu, select Access Management -> Users. 3. Click New to create a new organization. 4. When the Details page appears, we entered the following for our example and then clicked Next: – – – – – – – – – – Title: Mr. First name: Max Middle name: M. Last name (required): Capitalist Logon ID (required): maxcap Password (required): Password confirmation (required): Challenge question: Answer to challenge question: Account policy: Select Administrator Based on this selection (Shopper or Administrator), there are different password policies. – Account status: Select Enabled 534 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 5. When the Business Profile page appears, we entered the following and then clicked Next: – – – – – – – Employee ID: 10001 Employee type: Manager Department number: 2112 Manager’s Name: Yes Man Secretary’s Name: Who’s Frieda (she’s my secretary) Preferred language: we selected United States English Parent organization (required): B2B Organization 6. When the Address page appears, we entered the following and then clicked Next: – – – – – Street Address (required): 101 Yellow Brick Road City (required): Oz State: KS Zip/Postal Code: 66109 Country (required): US 7. When the Contact Information page appears, we entered the following and then clicked Finish: – – – – – Preferred method of communication: Select Phone1 E-mail address 1: [email protected] Phone number 1: 919-999-9999 Fax number 1: 919-999-0000 Best time to call: Select Daytime Assign roles seller organization administrator user After creating the user, we need assign roles to the newly created user. 1. From the Organization Administration Console menu, select Access Management -> Users. 2. From the Users page, check the newly created user (for example, maxcap) and click Roles. 3. From the Roles pages, we did the following and then clicked OK: – Organization: Select B2B Organization – Role: Select the desired roles for the user from the drop-down list and click Add. For example, we added the following roles: • • • • Seller Seller Administrator Store Administrator Registered Customer (This is only required if the seller needs to access the store as a registered user) Chapter 15. Manage the ITSO store 535 4. Click OK. Verify seller administrator logon to tools Verify that the seller organization administrator user can log on to the WebSphere Commerce tools. 1. Log on to the WebSphere Commerce Organization Administration Console as the seller organization administrator user (for example, maxcap), as follows: https://:8004/orgadminconsole 2. Select Access Management -> Organizations. Notice that only the organization listed is the seller organization. 3. Log out of the WebSphere Commerce Organization Administration Console. 4. Log on to the WebSphere Commerce Accelerator as the seller organization administrator user (for example, maxcap), as follows: https://:8000/accelerator 5. Verify access to menu options, and then log out of the WebSphere Commerce Accelerator. 15.2.3 Create a buyer organization This section describes the tasks involved in creating a buyer organizational unit (for example, BigCo Buyer Organization) under the Buyer Organization container organization created in 12.5.3, “Organizations” on page 373. The high-level tasks to create a new buyer organization are as follows: Create BigCo Buyer Organization Assign roles to BigCo Buyer Organization Enable approval group for BigCo Buyer Organization Create buyer organization administrator user Assign roles to buyer organization administrator user Enable approval group for buyer organization administrator Verify buyer admin logon to Organization Admin Console Verify buyer admin logon to the ITSO store Create BigCo Buyer Organization In our example, we will create the BigCo Buyer Organization for the BigCo large business customer that buys direct from the ITSO store. This organizational unit will be created under the Buyer Organization we created in the store customization in 12.5.3, “Organizations” on page 373. 1. From the Organizational Administration Console menu, select Access Management -> Organizations. 536 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 2. Click New to create a new organization. 3. When the Details page appears, we entered the following for our example: – – – – – Short name (required): BigCo Buyer Organization Description: BigCo Buyer Organization Business category: Business direct Organization type: Select Organization (default) Parent organization (required): click Find, check Buyer Organization, click Select When done, click Next. 4. When the Address page appears, we entered the following and then clicked Next: – – – – – Street Address (required): 1 BigCo Way City (required): Beverly Hills State/Province (required): CA Zip/Postal code (required): 90210 Country/Region (required): US 5. When the Contact page appears, we entered the following and then clicked Finish: – – – – – Preferred method of communication: Select Phone1 E-mail address 1: [email protected] Phone number 1: 919-111-1234 Fax number 1: 919-111-0000 Best time to call: Select Daytime Assign roles to BigCo Buyer Organization After creating the BigCo Buyer Organization, assign the appropriate roles to the organization. Note: The list of available roles for the child organization is based on the roles defined for the parent organization. To assign roles to the BigCo Buyer Organization, do the following: 1. From the Organization Administration Console menu, select Access Management -> Organizations. 2. Check the check box next to BigCo Buyer Organization, and click Roles. 3. From the Available Roles, we selected the following by clicking Add: – Procurement Buyer – Procurement Buyer Administrator – Buyer (buy-side) Chapter 15. Manage the ITSO store 537 – Buyer Approver – Buyer Administrator 4. Click OK. Enable approval group for BigCo Buyer Organization At this stage we can choose whether or not we want to enable approvals for the new organization (for example, BigCo Buyer Organization). Adding approvals in this case will mean that any new registered user in the new organization (for example, BigCo Buyer Organization) will need to be approved before they can shop at the store. By default approvals are enabled. However, the approval group (user with authority to approve/reject new customer registrations for the buyer organization) will only be the site administrator until you configure this otherwise. For our scenario, we want the user with the buyer administrator or buyer approver role, which we will create in the next section, to approve customer registration requests for the buyer organization. To enable the User Registration Approvals approval group for the BigCo Buyer Organization, complete the following steps: 1. From the Organization Administration Console, select Access Management -> Organizations. 2. Check BigCo Buyer Organization (organizational unit under Buyer Organization), and click Approvals. 3. Select User Registration Approvals - Seller Administration, and click Add. Note: The name User Registration Approvals - Seller Administrator is somewhat misleading, but the important point to note is that you are configuring User Registration Approvals for the buyer organization (for example BigCo Buyer Organization). By clicking OK in the next step, we will create a member group for the users we want to act as approvers for the buyer organization. When a user registers with the system, the registration request will be in the Pending Approval state until the user with the role buyer approver or buyer administrator for the buyer organization approves the registration request. 4. Click OK. Although the approach in this section is likely the most frequent, it is worth noting that there are some additional configuration options available because of the way that user approvals are inherited. 538 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide You can disable approvals site-wide by removing User Registration Approvals from the Root Organization. Alternatively, you can disable User Registration Approvals for all of your buyer organizations by adding the Disable Inherited User Registration Approvals to the Buyer Organization container organization. Yet another option is that if you want a single group of approvers to approve all users registering to any buyer organization, then you can simply enable approvals to the Buyer Organization container organization. This way any user registering to any descendent organizations will be approved using the same approval group. Note: To disable approvals, follow the same process, but select Disable Inherited User Registration Approvals. Create buyer organization administrator user This section describes how to create a user that will be used as an administrator to approve registration requests for the BigCo Buyer Organization. The role assignment for the user is defined in the next section. 1. From the Organization Administration Console menu, select Access Management -> Users. 2. Click New to create a new user. 3. When the Details page appears, enter the following and click Next: – – – – – – – – – – – Title: Mr. First name: Joe Middle name: Last name (required): Smith Logon ID (required): jsmith1 Password (required): Password confirmation (required): Challenge question: Answer to challenge question: Account policy: Select Shopper Account status: Select Enabled 4. When the Business Profile page appears, enter the following and click Next: – – – – – – Employee ID: 20001 Employee type: Manager Department number: 101 Manager’s Name: Kelly Smith Secretary’s Name: Peter Smith Preferred language: we selected United States English Chapter 15. Manage the ITSO store 539 – Parent organization (required): BigCo Buyer Organization 5. When the Address page appears, enter the following and click Next: – – – – – Street Address (required): 1 BigCo Way City (required): Beverly Hills State: CA Zip/Postal Code: 90210 Country (required): US 6. When the Contact Information page appears, enter the following and click Finish: – – – – – Preferred method of communication: Select Phone1 E-mail address 1: [email protected] Phone number 1: 919-111-9999 Fax number 1: 919-111-0000 Best time to call: Select Daytime Assign roles to buyer organization administrator user After creating the user, you will need to define the roles for the user that will give this user the authority to approve/reject customer registration requests in the BigCo Buyer Organization. 1. From the Organization Administration Console menu, select Access Management -> Users. 2. Check the user that you have created (for example, jsmith1) and then click Roles. 3. From the Roles page do the following for the BigCo Buyer Organization: a. Select the BigCo Buyer Organization (buyer organization). b. For each of the following roles, select the role and click Add. • • • • • Procurement Buyer Procurement Buyer Administrator Buyer (buy-side) Buyer Approver Buyer Administrator c. Click OK when done. 4. Check the user that you have created (for example, jsmith1) and then click Roles. 5. From the Roles page, do the following for the B2B Organization. This is required so that the buyer contact can log on to the ITSO store. a. Select the B2B Organization (seller organization). b. Select the Registered Customer role and click Add. 540 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide c. Click OK when done. Enable approval group for buyer organization administrator This section describes how to make the buyer administrator user a member of the new buyer organization’s approval group. Note that the approval group is the list of users who get an e-mail notification when a new user tries to register to the buyer organization, and who has the rights and roles defined to approve/reject user registration requests for the buyer organization. Also note that the approval group for the new buyer organization was created when the user registration approvals were enabled for the organization in “Enable approval group for buyer organization administrator” on page 541. To enable the approval group for the buyer administrator user for the BigCo Buyer Organization, do the following: 1. From the Organization Administration Console menu, select Access Management -> Users. 2. Check the user that you have created (for example, jsmith1) and then click Member Groups. 3. On the Include page, select UserRegistrationApprovalGroup - BigCo Buyer Organization, and then click Add. 4. Click OK. 5. Log out of the WebSphere Commerce Organization Administration Console. Verify buyer admin logon to Organization Admin Console This section describes how to verify that the new buyer organization administrator user can access the WebSphere Commerce Organization Administration Console. For example, we verified that the jsmith1 user ID was able to use the WebSphere Commerce Organization Administration Console: 1. Start the WebSphere Commerce Organization Administration Console: https://:8004/orgadminconsole 2. Log on as the user for the BigCo Buyer Organization (for example, jsmith1). 3. From the menu, select Access Management -> Organizations. Notice that only the BigCo Buyer Organization is listed. 4. Log out of the WebSphere Commerce Organization Administration Console. Chapter 15. Manage the ITSO store 541 Verify buyer admin logon to the ITSO store In our example, we added the registered customer role to the jsmith1 buyer administrator user for the BigCo Buyer Organization. Verify this user can log on to the ITSO store. 1. Verify, the user (for example, jsmith1) can log on to the ITSO store. http:///webapp/wcs/stores/servlet/ITSO/index.jsp 2. The buyer administrator user should have a link, Go to Approval Tool, in the ITSO store. This is displayed as a result of assigning the role(s) buyer administrators or buyer approvers to the user. 15.3 Create a business account This section describes how to create a business account for the ITSO store. 15.3.1 Business accounts in ITSO store archive The businessaccount.xml file packaged with the store archive is used to create business account and relationship to the buyer organizations (customer). In our example, the businessaccount.xml will create business accounts for the Buyer A and B organizations respectively. We chose to leave these accounts for the purposes of demonstrating how this can be done using the XML files. We will not use these business accounts. We will explain how to create a business account for our example using the WebSphere Commerce Accelerator. 15.3.2 Create a business account To create a business account using the WebSphere Commerce Accelerator for the ITSO B2B working example, do the following: 1. Start the WebSphere Commerce Accelerator. For simplicity we will log on as the site administrator. https://:8000/accelerator 2. From the Accelerator menu, select Sales -> Accounts. 3. When the Account page appears, click New. 4. When the Account Customer page appears, we entered the following for each tab: Customer: – Customer organization (required): Select BigCo Buyer Organization 542 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – Contact (required): we selected jsmith1 User logon ID created in “Create buyer organization administrator user” on page 539. – Contact information: Knock twice and proceed to the green room. – Check Customers can purchase under the terms and conditions of store’s default contract. Representative: – Department (required): Select B2B Organization Department is the organizational units under the seller organization. In our example, we have only defined B2B Organization. – Representative: Select maxcap In our example, maxcap is the contact user created for the B2B Organization. Purchase Order: The purchase order may be specified at the time of ordering if the check box is checked. We chose to add a new purchase order for example purposes. i. Click Add. ii. Enter purchase order number 12345. iii. We checked Spending Limit (optional). iv. Amount (required if spending limit checked): 10000 v. Select USD for currency vi. Click OK. Invoicing: Invoice deliver method. Select one of the following (we selected Included with shipment): • • • E-mail Included with shipment Regular mail Credit Line: • We left this blank. Remarks • Enter remark, and click OK. You should see the new business account listed. Chapter 15. Manage the ITSO store 543 15.4 Create a contract This section describes how to create a contract for the ITSO store. Thus far we have created organizations and a business account in support of creating a contract. Figure 15-1 highlights the relationship between organizations, users, business accounts, and contracts for the ITSO working example. Buyer Organization Seller Organization B2B Organization BigCo Buyer Organization Buyer contact: John Smith (jsmith) Seller contact: Max M. Capitalist (maxcap) Account Contract Figure 15-1 Relationship of organizations, users, accounts, and contracts 15.4.1 Contracts in ITSO store archive The contract.xml packaged with the store archive is used to create contracts. While creating the ITSO store, we modified the contract.xml in 12.5.5, “Contracts” on page 380. We removed two contracts and updated the default contract for the ITSO store. It is possible to create contracts using the contract.xml and package it as part of the store archive. 544 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 15.4.2 Create contract using the Accelerator To create a new contract using the WebSphere Commerce Accelerator, do the following: 1. Start the WebSphere Commerce Accelerator. For simplicity we will log on as the site administrator. https://:8000/accelerator 2. From the Accelerator menu, select Sales -> Accounts. 3. When the Account page appears, check the account (customer) for the organization you wish to create a new contract for and click New Contract. For example, we checked the BigCo Buyer Organization. 4. We entered the following to create a new contract. Select the General tab. – – – – – – Contract name (required): BigCo Contract Short description (required): BigCo Contract Description: BigCo Contract is the ticket We checked Start immediately for our example. We checked No expiry date for our example. Refer to contract: We selected Do not refer to a contract 5. Select the Customers tab. Select from Available customers (for example, BigCo Buyer Organization) and then click Add. 6. Select and expand the Products and Prices tab. Select either Percentage Pricing or Fixed Pricing. a. For our example, we selected Percentage Pricing and clicked Add. b. When the Add Percentage Pricing page appears, select Apply an adjustment on the entire master catalog c. Adjustment (required, measure by %): we entered 50 for our example. d. From the drop-down list for adjustment, we selected Markdown. e. Click OK. 7. Select the Selection Constraints tab. This allows you to exclude/include for sale categories or products in this contract. We did not use this feature. 8. Select and expand the Shipping tab. a. Select the Providers tab. For our example, we selected Shipping policy for A1, A2, A3 (default) and clicked Add. b. Select the Charge Type tab. Select either Shipping charged by carrier or Shipping charged by seller. For our example, we selected Shipping charged by seller. Chapter 15. Manage the ITSO store 545 c. Select the Addresses tab. We selected the BigCo Buyer Organization for the available shipping addresses and clicked Add. 9. Select the Payment tab. Click Add. We entered the following and then clicked OK: – Payment method (required): we selected Credit Card Offline - VISA – Description (required): BigCo Visa Payment – Credit card number: We used 4111111111111111 (4, followed by fifteen 1’s) for test purposes. – Expiry month: Select – Expiry year: Select – Billing address: Select BigCo Buyer Organization 10.Select and expand Returns. a. Select Policies and do the following: • Returns charge policy: Select either No returns policy selected or No charges for returned goods. For our example, we selected No charges for returned goods. • Returns approval policy: Select either No returns policy selected or Auto approved if returned within 30 days, refund approved always. For our example, we selected Auto approved if returned within 30 days, refund approved always. b. Select Refund. You can configure the refund using the original payment method, or refund using credit line. You must select one of the options. We checked Refund using original payment method. 11.Select Order Approval tab. Check Approval required if you would like to enable an order approval process. We accepted the default (not checked). 12.Select the Attachments tab. This allows you to specify a URL to an attachment such as a terms.pdf, which details the terms and conditions of the contract. We left this blank. 13.Select the Remarks tab. This can be used to enter any comments specific to the contract. We left this blank. 14.When done, click OK to save contract settings. 15.You should see a message “The contract was successfully created”. Click OK. 546 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: When you add products or categories to the Percentage Pricing page of the Contracts notebook, WebSphere Commerce automatically makes all products in the master catalog available in the contract at standard prices. 15.4.3 Activate contract After creating the contract, it is in draft state and must be deployed to become active. Note: As stated, after creating the contract it is in draft state. For this reason, validation of required settings is not performed until the contract is submitted to become active. If you get an error message as a result of clicking Submit, address the problem and try again. 1. From the Accelerator, select Sales -> Accounts. 2. Check the account for the BigCo Buyer Organization and click Contracts. 3. Select the BigCo Contract, and click Submit. 4. Notice that during the submit operation, the status will change to Deploying. Click Refresh. When done, the status should be listed as Active. 5. Log out from the WebSphere Commerce Accelerator. 15.4.4 Verify the contract is enabled After creating a contract is completed, we recommend that you verify that the contract is working properly by logging into the store as the registered user. Verify that you can complete a shopping transaction. For example, are the categories and products listed as specified? Are the prices for the products as they should be? Create a registered customer in BigCo Buyer Organization Create a registered customer in the BigCo Buyer Organization, by doing the following: 1. Enter the ITSO store home page URL. For example: http:///webapp/wcs/stores/servlet/ITSO/index.jsp 2. Click Register and enter the information for the test user (for example, bigcouser1). Ensure you enter the BigCo Buyer Organization/Buyer Organization in the Buyer organization text field. 3. You should see the following message after registering: Chapter 15. Manage the ITSO store 547 Your registration request has been received. Your account is waiting your approval. Unitl your account has been approved, you cannot log in. Approve user registration request After the user has registered, the user must be approved by the buyer organization administrator user (for example, jsmith from the BigCo Buyer Organization) from within the WebSphere Commerce Organization Administration Console. 1. Start the WebSphere Commerce Organization Administration Console. https://:8004/orgadminconsole 2. Log on as the BigCo Buyer Organization administrator user jsmith1. 3. From the menu, select Approvals -> Approval Requests. 4. Check the pending registration request, and click Approve. 5. Enter a remark and click OK. 6. Log out of the WebSphere Commerce Organization Administration Console. Verify contract in ITSO store for BigCo customer To verify that the BigCo registered customer can now log in and that they have the proper contract products and pricing for the ITSO store, do the following: 1. Enter the ITSO store home page URL. For example: http:///webapp/wcs/stores/servlet/ITSO/index.jsp 2. Enter the logon ID of the user created in “Create a registered customer in BigCo Buyer Organization” on page 547 (for example, bigcouser1). 3. Navigate to the ITSO store and complete the purchase of some products. You should see products listed at 50% off the original price (see Figure 15-2 on page 549). 4. Go through the order process and notice that the only available payment method is VISA, that the credit card number is predefined as part of the contract, and that you must specify the purchase order number as defined in 15.3.2, “Create a business account” on page 542 (12345). 548 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 15-2 ITSO store - contract validation Chapter 15. Manage the ITSO store 549 550 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Part 4 Part 4 Runtime deployment scenarios This part of the redbook provides procedures for implementing advanced multi-tiered runtime scenarios on Windows, Solaris, AIX, and OS/400. The scenarios highlight best practices and advanced multi-tier configurations, such as remote Web server, database, and payment nodes. © Copyright IBM Corp. 2003. All rights reserved. 551 552 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 16 Chapter 16. Windows: Migrate a single-tier to a multi-tier This chapter describes techniques for migrating from a Windows 2000 single-tier installation of WebSphere Commerce to a two tier (also called 2-tier) remote Web server, two-tier remote Database server, and a three-tier (also called 3-tier) runtime environment. The starting point for the scenarios is a fully installed and tested single-tier WebSphere Commerce node runtime environment. The procedures documented include best practices, tips, and fix packs beyond the original IBM WebSphere Commerce V5.5 release, such as IBM DB2 UDB V8.1 Fix Pack 3, IBM WebSphere Application Server V5.0 Fix Pack 1, and the IBM WebSphere Commerce V5.5.0.2 Fix Pack. The chapter is organized into the following sections: Scenario overview and planning Single-tier implementation Add a remote Database Server node Add remote Web Server node Migrate a single-tier to a three-tier runtime environment © Copyright IBM Corp. 2003. All rights reserved. 553 16.1 Scenario overview and planning This section describes common reasons for migrating from a single-tier to a multi-tier runtime environment, and the sample migration scenarios we have detailed in this chapter. 16.1.1 Common reasons for migrating to multi-tiers Once a runtime environment has been installed, there are many reasons that a customer will need to migrate runtime components of the runtime environment to a distributed solution: Scalability The WebSphere Application Server architecture is designed to offer many runtime configuration options for scalability needs. WebSphere Commerce can leverage the base WebSphere Application Server infrastructure to achieve scalability and performance objectives. This chapter describes some of the fundamental techniques for migrating from a single-tier to multi-tier runtime environment. Security To enhance the security of the WebSphere Commerce runtime environment, a remote Web Server node can be used. Often customers will implement the remote Web server in a demilitarized zone (DMZ), which allows for an additional firewall between the remote Web Server node and the WebSphere Commerce node. Software compatibility Because of software compatibility restrictions, it may be necessary to run components of the runtime environment solutions on separate nodes. Best practices Even in a scenario where your endpoint may be a three-tier or enterprise three-tier configuration, it may be desirable to install WebSphere Commerce and supporting software on a single-tier first, and then migrate the configuration to a remote Web Server node and remote Database Server node. For example, it is much easier to configure the remote Web Server when first creating a WebSphere Commerce instance using the WebSphere Commerce Configuration Manager. The Configuration Manager updates the IBM HTTP Server httpd.conf with all the proper aliases and directives for WebSphere Commerce. Once the remote Web Server is installed, the httpd.conf can be copied from the single-tier WebSphere Commerce node, and easily updated 554 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide to change the ServerName and VirtualHost host name. The alternative is a manual update of all directives in the httpd.conf. 16.1.2 Migration scenarios Before describing the details on how to migrate, we define three runtime environment migration scenarios to which the procedures in this chapter can be applied: Add a remote Database Server node Add a remote Web Server node Migrate a single-tier to a three-tier runtime environment Add a remote Database Server node In this scenario, a single-tier or two-tier remote Web Server WebSphere Commerce runtime environment has been installed and configured. Figure 16-1 depicts the WebSphere Commerce two-tier remote Database Server runtime environment and product mapping for the Windows platform. W ebSphere Commerce 5.5 BE + Fix Pack 2 IBM HTTP Server 1.3.26.1 W ebSphere Commerce Payments 5.5 W ebSphere Application Server 5 + Fix Pack 1 DB2 8.1 Enterprise Client + Fix Pack 3 W indows 2000 Server + SP4 DB2 8.1 Enterprise Server Edition + Fix Pack 3 W indows 2000 Server + SP4 DB2 Server node (db2w in1) WebSphere Commerce node (w cw in1) W C instance database W C Payments database Figure 16-1 WebSphere Commerce two-tier remote Database Server configuration Add a remote Web Server node In this scenario, a single-tier WebSphere Commerce runtime environment has been installed and configured. Figure 16-2 on page 556 depicts the WebSphere Commerce two-tier remote Web Server runtime environment and product mapping for the Windows platform. Chapter 16. Windows: Migrate a single-tier to a multi-tier 555 WebSphere Commerce 5.5 BE + Fix Pack 2 WebSphere Commerce Payments 5.5 WebSphere Application Server 5 + Fix Pack 1 DB2 8.1 Enterprise Server + Fix Pack 3 Windows 2000 Server + SP4 IBM HTTP Server 1.3.26.1 WebSphere V5 plug-in + Fix Pack 1 Windows 2000 Server + SP4 WebSphere Commerce node (wcwin1) Web Server node (webwin1) Figure 16-2 WebSphere Commerce two-tier remote Web server runtime Migrate a single-tier to a three-tier runtime environment This scenario is a combination of adding a remote Web Server node and adding a remote Database Server node to an existing single-tier configuration to construct a three-tier runtime environment. Figure 16-3 depicts the WebSphere Commerce thee-tier remote Web Server node and remote Database Server node product mapping for the Windows platform. DMZ Outside world Internal network 80/443 80/443 Web Server Web node Server (webwin1) IBM HTTP Server 1.3.26.1 WebSphere V5 plug-in + Fix Pack 1 Windows 2000 Server + SP4 Domain Firewall User I N T E R N E T Protocol Firewall WebSphere Commerce 5.5 BE + Fix Pack 2 WebSphere Commerce Payments 5.5 WebSphere Application Server V5 + Fix Pack 1 DB2 UDB 8.1 Client + Fix Pack 3 Windows 2000 Server + SP4 WebSphere Commerce node (wcwin1) DB2 UDB 8.1 Enterprise Server Edition + Fix Pack 3 Windows 2000 Server + SP4 DB2 Server node (db2win1) WC instance database WC Payments database Figure 16-3 WebSphere Commerce three-tier product mapping for Windows 556 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 16.1.3 Hardware and software perquisites For detailed information on WebSphere Commerce V5.5 hardware and software requirements, refer to the Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000 product guide. 16.1.4 Hardware used in the ITSO runtime environment We used the following hardware within the ITSO runtime environment for a single-tier WebSphere Commerce node: WebSphere Commerce node – IBM ^ xSeries® 230 (8658-61Y) • 1 CPU, Intel PIII 1 GHz • 1152 MB main memory • 18 GB DASD • 1 IBM Ethernet adapter • Host name: wcwin1.itso.ral.ibm.com We used the following hardware within the ITSO runtime environment for the multi-tiered configuration: Web Server node – IBM ^ xSeries 230 (8658-61Y) • 1 CPU, Intel PIII 1 GHz • 1152 MB main memory • 18 GB DASD • 1 IBM Ethernet adapter • Host name: webwin1.itso.ral.ibm.com WebSphere Commerce node – IBM ^ xSeries 230 (8658-61Y) • 1 CPU, Intel PIII 1 GHz • 1152 MB main memory • 18 GB DASD • 1 IBM Ethernet adapter • Host name: wcwin1.itso.ral.ibm.com DB2 Server node – IBM ^ xSeries 230 (8658-61Y) • 1 CPU, Intel PIII 1 GHz • 1152 MB main memory • 18 GB DASD • 1 IBM Ethernet adapter • Host name: db2win1.itso.ral.ibm.com Chapter 16. Windows: Migrate a single-tier to a multi-tier 557 16.1.5 Software used in the ITSO runtime environment The ITSO runtime environment was implemented using the software levels listed in Table 16-1 for the single-tier configuration. Table 16-1 WebSphere Commerce node single-tier Software Version Microsoft Windows 2000 Server 2000 + Service Pack 4 Microsoft Internet Explorer 6 + Service Pack 1 IBM DB2 UDB, Enterprise Server Edition 8.1.3.132 (8.1 + Fix Pack 3) IBM HTTP Server 1.3.26.1 (1.3.26 + WAS 5 FP1) WebSphere Application Server 5.0.1 (5.0 + Fix Pack 1 + Fixes) WebSphere Commerce, Business Edition * including WebSphere Commerce Payments * WebSphere Commerce store 5.5.0.2 (5.5 + Fix Pack 2) The ITSO runtime environment was implemented using the software levels listed in Table 16-2,Table 16-3, and Table 16-4 on page 559 for the multi-tier configuration. Table 16-2 Web Server node Software Version Microsoft Windows 2000 Server 2000 + Service Pack 4 IBM HTTP Server 1.3.26.1 (1.3.26 + WAS 5 FP1) WebSphere Application Server plug-in 5.0.1 (5.0 + Fix Pack 1 + Fixes) Table 16-3 WebSphere Commerce node 558 Software Version Microsoft Windows 2000 Server 2000 + Service Pack 4 Microsoft Internet Explorer 6 + Service Pack 1 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Software Version IBM DB2 UDB, Enterprise Server Edition Client 8.1.3.132 (8.1 + Fix Pack 3) WebSphere Application Server 5.0.1 (5.0 + Fix Pack 1 + Fixes) WebSphere Commerce, Business Edition * including WebSphere Commerce Payments * WebSphere Commerce store 5.5.0.2 (5.5 + Fix Pack 2) Table 16-4 DB2 Server node Software Version Microsoft Windows 2000 Server 2000 + Service Pack 4 IBM DB2 UDB, Enterprise Server Edition 8.1.3.132 (8.1 + Fix Pack 3) Software installation paths and variables Table 16-5 lists the software installation paths and variables used to implement the WebSphere Commerce node, remote Web Server node, and the Database Server node. Table 16-5 Software installation paths and variables Software ITSO install path Variable DB2 UDB Enterprise Edition c:\ibm\sqllib IBM HTTP Server c:\ibm\ihs WebSphere Application Server c:\ibm\was WebSphere Commerce c:\ibm\wc 16.2 Single-tier implementation The precondition for adding a remote Web server or remote database server documented in this chapter is that a single-tier WebSphere Commerce node must have been installed. For details on installing a single-tier WebSphere Commerce node, please refer to the Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000 product guide. Chapter 16. Windows: Migrate a single-tier to a multi-tier 559 We completed the following high-level tasks to implement the single-tier WebSphere Commerce runtime environment as a prerequisite for the migration scenarios found in this chapter: Windows installation WebSphere Commerce V5.5 installation DB2 UDB V8.1 Fix Pack 3 installation WebSphere Application Server V5 Fix Pack 1 installation WebSphere Commerce V5.5.0.2 Fix Pack 2 installation WebSphere Commerce instance creation WebSphere Commerce Payments instance creation Database backup Start servers Verify the runtime environment and store functionality Note: In the procedure documented in this section, we installed the IBM WebSphere Application Server V5 Fix Pack 1, IBM DB2 UDB Fix Pack 3, and IBM WebSphere Commerce V5.5.0.2 Fix Pack before the WebSphere Commerce instance creation. If you have already created the WebSphere Commerce instance, you will need to refer to the WebSphere Commerce V5.5 Fix Pack Readme file to apply the fixes to the WebSphere Commerce instance (application server and enterprise application) that have already been deployed. 16.2.1 Windows installation This section only highlights the key issues such as needing Windows 2000 Service Pack level 3 or higher, and user rights assigned to the administrator user needed later for DB2. Windows 2000 Service Pack 4 In our example, we installed Windows 2000 Server Service Pack 4. Create admin user and assign user rights To assign user rights to the administrator ID used by the WebSphere Commerce DB2 owner during instance creation, do the following: 1. Log on to Windows as an administrator. 2. Create a user ID and add the user to the administrators group (for example, we created a user called admin). Alternatively, use an existing administrator user. 3. Click Start -> Settings -> Control Panel -> Administrative Tools -> Local Security Policy. 560 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 4. From the Local Security Settings window, select and expand Local Policies -> User Rights Assignment. 5. Ensure the administrator user ID (for example, admin) has user right assignments for the following Windows Local Security Policies needed for DB2: – – – – – Act as part of the operating Create a token object Increase quotas Log on as a service Replace a process level token 6. Log on as the administrator user ID created with the assign rights needed for DB2. Verify network configuration Prior to installing WebSphere Commerce and supporting software components, it is important that you verify that your network is configured properly. We recommend that you use a static TCP/IP address and verify that the host name can be resolved with the name server. 16.2.2 WebSphere Commerce V5.5 installation For details on how to install WebSphere Commerce V5.5 on a single node using the IBM HTTP Server and DB2, refer to the Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000 product guide. We accepted the default settings for most options. We used the WebSphere Commerce InstallShield to install WebSphere Commerce, WebSphere Application Server, IBM HTTP Server, and WebSphere Commerce Payments. The following are the key steps and options we entered during the installation: We ran setup from the IBM WebSphere Commerce V5.5 CD 1. We selected the Typical install. We installed the software components to the following directories: – – – – IBM DB2 UDB: c:\ibm\sqllib IBM HTTP Server: c:\ibm\ihs IBM WebSphere Application Server: c:\ibm\was IBM WebSphere Commerce: c:\ibm\wc We used the admin user ID added to the administrator group and rights assigned for DB2 in “Create admin user and assign user rights” on page 560. Chapter 16. Windows: Migrate a single-tier to a multi-tier 561 16.2.3 DB2 UDB V8.1 Fix Pack 3 installation We installed IBM DB2 UDB V8.1 Fix Pack 3 for 32-bit Windows. The internal DB2 level is 8.1.3.132 after the installation of Fix Pack 3. In our example, we do not have any existing databases at this stage. If you do have existing databases, refer to the FixpackReadme.txt for details. 1. IBM DB2 UDB V8.1 Fix Pack 3 can be downloaded at: ftp://ftp.software.ibm.com/ps/products/db2/fixes/english-us/db2winIA32v8/fi xpak/FP3_WR21324/ 2. We downloaded the FP3_WR21324_ESE.exe, which is for the IBM DB2 Universal Database V8.1, Enterprise Server Edition. Note: For a full description and listing of download files, refer to the FixpackReadme.txt. 3. Stop all DB2 services in the Windows services. The services include dependencies. We stopped the DB2 services, and worked our way through the services list from bottom to top. 4. Install the IBM DB2 Universal Database V8.1, Enterprise Server Edition Fix Pack 3. – Run setup to start the fix pack installer. – We accepted the default installation options. 5. You will need to restart your system before the fixes will take effect. 562 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Tip: If you have created databases before you installed Fix Pack 3, you will need to rebind the DB2 utilities to the databases. In our example, we do not have any database created at this stage of the procedure. 1. After the system has restarted, open a DB2 command window and enter the following DB2 command: db2level It should return 8.1.3.132 after Fix Pack 3 has been installed. 2. You need to rebind your DB2 utilities with all databases after the fix pack installation. This step is necessary for the fixes to become effective. The binding procedure needs to be performed only once per database. To rebind existing DB2 UDB databases after installing Fix Pack 3, enter the following commands from a DB2 command window for each database: db2 db2 db2 db2 db2 terminate CONNECT TO BIND \BND\@db2ubind.lst GRANT PUBLIC BIND \BND\@db2cli.lst GRANT PUBLIC terminate Where represents the name of a database to which the utilities should be bound, and represents the directory where you have installed DB2. The db2ubind.lst and db2cli.lst contain lists of required bind files used by IBM DB2 UDB V8.1. 16.2.4 WebSphere Application Server V5 Fix Pack 1 installation This section describes the steps needed to install IBM WebSphere Application Server V5 Fix Pack 1 and interim fixes required for the WebSphere Application Server V5.0.1 to be used with WebSphere Commerce V5.5.0.2. As part of the procedure, we will download and install the WebSphere Update Installer V5.0.x. The WebSphere Update Installer will be used to uninstall WebSphere Application Server fixes installed by the WebSphere Commerce Installer, and install WebSphere Application Server V5 Fix Pack 1 and interim fixes. This section includes the following tasks: Install WebSphere Update Installer V5.0.x Uninstall WebSphere Application Server Fixes Install WebSphere Application Server V5 Fix Pack 1 Install WebSphere Application Server V5.0.1 fixes Verify the WebSphere Application Server Chapter 16. Windows: Migrate a single-tier to a multi-tier 563 Install WebSphere Update Installer V5.0.x The WebSphere Update Installer V5.0.x is the tool used to install updates (fix packs and interim fixes) to WebSphere Application Server V5.0.x. We will use the Update Installer to install WebSphere Application Server V5 Fix Pack 1 (V5.0.1), and other fixes beyond the V5.0.1 level. The IBM WebSphere Application Server V5.0.x Update Installer can be downloaded from the following URL: http://www.ibm.com/software/webservers/appserv/was/support/ Note: Do not use the WebSphere Application Server Update Installer found on WebSphere Commerce CD 2. In a nutshell, we did the following to download and run the WebSphere Application Server V5 Update Installer: 1. Ensure each WebSphere Application Server base node and application server are stopped. For example, from a command window enter the following in the \bin directory: stopServer.bat server1 stopNode.bat 2. Ensure the IBM HTTP Server is stopped from Windows services. 3. Create a download directory for the WebSphere Update Installer (for example, c:\ibm\was\update). 4. Download Update Installer - Windows and Readme file (updateInstaller.zip, readme_updateinstaller.html) to the c:\ibm\was\update directory from the following: http://www.ibm.com/support/docview.wss?rs=180&tc=SSEQTP&uid=swg24001908 5. Unpack the updateInstaller.zip to the c:\ibm\was\update directory. 6. To run the Update Installer wizard, enter updateWizard.bat from the c:\ibm\was\update directory where you have unpacked the Update Installer. Uninstall WebSphere Application Server Fixes During the WebSphere Commerce V5.5 installation, many WebSphere Application Server V5.0 fixes are installed. Prior to installing WebSphere Application Server V5 Fix Pack 1, the V5.0 fixes must be uninstalled to ensure the newest level of the files are installed and active. 1. Stop all WebSphere Application Server, application servers and nodes. 2. Stop the IBM HTTP Server Windows service (WebSphere plug-in fixes). 3. Start the Update Installer as described in the previous section. 4. When the Welcome window appears, click Next. 564 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 5. The Update Installer wizard will detect the WebSphere Application Server installation path (for example, c:\ibm\was). We accepted the default and clicked Next. 6. Select Uninstall fixes, and click Next. 7. In our case, the WebSphere Commerce InstallShield installed many WebSphere Application Server V5 fixes, so many fixes are displayed. Check all fixes in the list (uninstall) and then click Next. 8. You should see a window with the fixes listed to be uninstalled. Click Next to begin uninstalling fixes. 9. When done, click Finish. Install WebSphere Application Server V5 Fix Pack 1 For the majority of the time spent writing this redbook, we used the WebSphere Commerce V5.5 GM product, which includes WebSphere Application Server V5.0 + fixes. Just prior to completing the redbook, we updated the Windows runtime implementation procedure to include IBM WebSphere Application Server V5 Fix Pack 1. We did so because of the many critical fixes contained in Fix Pack 1 and to address an EJB deployment issue we had with WebSphere Application Server V5.0 and DB2 UDB V8.1 metadata. To install the IBM WebSphere Application Server V5 Fix Pack 1, do the following: 1. Stop all WebSphere Application Server, application servers, and nodes. 2. Stop the IBM HTTP Server Windows service (WebSphere plug-in fixes). 3. Prior to installing WebSphere Application Server V5 Fix Pack 1, run the backupConfig script to back up configuration files. The backupConfig.bat can be found in the \bin directory. 4. The IBM WebSphere Application Server V5 Fix Pack 1 can be downloaded at: http://www.ibm.com/support/docview.wss?rs=180&context=SSEQTP&q=&uid=swg2400 4576&loc=en_US&cs=utf-8&lang=en 5. In our case, we downloaded Windows 2000/NT Base (was50_fp1_win.zip). 6. We unpacked the was50_fp1_win.zip to the c:\ibm\was\update\fp1 directory. After unpacking the zip file, you may delete the file to save space. 7. Change to the directory where you have unpacked the WebSphere Update Installer V5.0.x (for example, c:\ibm\was\update). 8. Start the WebSphere Application Server Update Installer wizard by entering updateWizard.bat. 9. When the WebSphere Update Installer language window appears, select the appropriate language for the wizard (for example, English) and then click OK. Chapter 16. Windows: Migrate a single-tier to a multi-tier 565 10.When the Welcome window appears, click Next. 11.The WebSphere Update Installer will detect your currert WebSphere Application Server version and installation directory. Click Next. 12.Select Install fix packs and then click Next. 13.Enter the directory where you have unpacked the fix pack. After the unpack you should see the fixpacks directory in the directory you have unpacked the Fix Pack 1. For example, we entered c:\ibm\was\update\fp1\fixpacks in the Fix pack directory text field, and then clicked Next. 14.Select the was50_fp1_win fix pack (default) and then click Next. 15.You will be prompted for the directories for the IBM HTTP Server and the WebSphere Application Server Embedded Messaging. In our example, we accepted the following paths and then clicked Next. – IBM HTTP Server: c:\ibm\ihs – Embedded Messaging: c:\ibm\was\MQ Note: The WebSphere Commerce V5.5 installer by default installs nearly all options of the WebSphere Application Server including embedded messaging. Embedded messaging is not supported by WebSphere Commerce. 16.Review the fix pack settings and then click Next to begin the fix pack installation of files. 17.When the WebSphere Application Server V5 Fix Pack 1 installation is complete, click Finish. Install WebSphere Application Server V5.0.1 fixes After installing WebSphere Application Server V5 Fix Pack 1 (V5.0.1), we installed the fixes listed in Table 16-6, which lists the WebSphere Application Server V5.0.1 fixes to be installed, a brief description of the problem addressed, and the location where the fix can be found. Table 16-6 WebSphere Application Server V5.0.1 fixes Fix Description PQ71950 * This fix addresses a memory leak problem common to WebSphere Application Server V5.0 and V5.0.1. * The fix and more information can be found at: http://www.ibm.com/support/docview.wss?rs=180&context=SSEQTP&q=pq719 50&uid=swg24004567&loc=en_US&cs=utf-8&lang=en+en * The fix can also be found on WebSphere Commerce V5.5 CD 2 in the \Software_Patches\WAS\repository directory. 566 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Fix Description PQ72451 * This fix addresses a prepared statement not properly closed causing the JVM footprint to continue to grow, and is common to WebSphere Application Server V5.0 and V5.0.1. * The fix and more information can be found at: http://www.ibm.com/support/docview.wss?rs=180&context=SSEQTP&q=pq724 51&uid=swg24004565&loc=en_US&cs=utf-8&lang=en * The fix can be found on WebSphere Commerce V5.5 CD 2 in the \Software_Patches\WAS\repository directory. PQ74316 * This fix addresses a problem with stored response of a JSP (Dynacache) and is common to WebSphere Application Server V5.0 and V5.0.1. * The fix and more information can be found at: http://www.ibm.com/support/docview.wss?rs=180&context=SSEQTP&q=pq743 16&uid=swg24004786&loc=en_US&cs=utf-8&lang=en * The fix can be found on WebSphere Commerce V5.5 CD 2 in the \Software_Patches\WAS\repository directory. WebSphere Plug-in Cumulative Fix * This cumulative fix addresses problems with the WebSphere Plug-in and is common to WebSphere Application Server V5.0, V5.0.1, and V5.0.2. * The fix and more information can be found at: http://www.ibm.com/support/docview.wss?rs=180&context=SSEQTP&q=cumul ative+plugin&uid=swg24004524&loc=en_US&cs=utf-8&lang=en WebSphere Connection Manager Cumulative Fix * This cumulative fix addresses problems with the WebSphere Application Server Connection Manager and is common to V5.0.1 and V5.0.2. * The fix and more information can be found at: http://www.ibm.com/support/docview.wss?rs=180&context=SSEQTP&q=cumul ative&uid=swg24005601&loc=en_US&cs=utf-8&lang=en To install the fixes, use the WebSphere Update Installer as follows: 1. Ensure all WebSphere Application Server, application servers, and nodes are stopped. 2. Ensure the IBM HTTP Server Windows service is stopped. 3. Download the fixes listed in Table 16-6 on page 566 to the c:\ibm\was\update\fixes directory. 4. Start the WebSphere Application Server Updat Installer wizard. For details refer to “Install WebSphere Update Installer V5.0.x” on page 564. 5. Specify the directory where you have downloaded the fix. For example, c:\ibm\was\update\fixes. 6. Select Install fixes and then click Next. 7. Check the fixes listed in Table 16-6 on page 566, and click Next (see Figure 16-4 on page 568). Chapter 16. Windows: Migrate a single-tier to a multi-tier 567 Figure 16-4 WebSphere Application Server V5.0.1 fixes 8. Review the summary of fixes to be installed and then click Next to begin installing the fixes. You should see a message that the fixes were successfully installed. 9. When done, click Finish. Verify the WebSphere Application Server To verify the functionality of the WebSphere Application Server after installation, do the following: 1. Ensure the IBM HTTP Server Windows service has been started. 2. Start the server1 application server with the WebSphere Administration Console enterprise application is installed: cd \ibm\was\bin startServer server1 568 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: Review the status of the server startup in the startServer.log as follows: # tail -f c:\ibm\was\logs\server1\startServer.logs You should see the following message: Server server1 open for e-business The server1 directory will not get created until the first time the application server is started. 3. Start the WebSphere Application Server Administration Console, by entering the following URL in a Web browser: http://:9090/admin 4. Log on to the WebSphere Administration Console (for example, as admin). 5. When done verifying the WebSphere Administration Console, log out, close the Web browser, and stop server1 as follows: cd \ibm\was\bin stopServer.bat server1 16.2.5 WebSphere Commerce V5.5.0.2 Fix Pack 2 installation This section describes the steps required to install IBM WebSphere Commerce V5.5.0.2 (Fix Pack 2). The fix pack can be installed silently or using a GUI. In our example, we will use the GUI installer. The WebSphere Commerce V5.5.0.2 Fix Pack contains two installable fix pack modules, depending on whether you have already created a WebSphere Commerce instance. If you have not created an instance, you only need to install the wc module. If you have created an instance, you must install both modules (wc and was). In our scenario, we have not created an instance at this stage. For more detailed information on the contents of the fix pack and installation, refer to the Installation Guide for IBM WebSphere Commerce V5.5.0.2 Fix Pack product guide included with the fix pack, found at: http://www.ibm.com/support/docview.wss?rs=494&uid=swg24005628 Note: In our example, we have not created a WebSphere Commerce or WebSphere Commerce Payments instance at this stage. If you have already created an instance prior to installing Fix Pack 2, you will need to follow additional instructions found in the Installation Guide for IBM WebSphere Commerce V5.5.0.2 Fix Pack on how to update existing instances with the fix pack. Chapter 16. Windows: Migrate a single-tier to a multi-tier 569 To install the WebSphere Commerce V5.5.0.2 Fix Pack, do the following: 1. Log on to the WebSphere Commerce node Windows system with a user that is a member of the Administrators group. 2. Ensure the following servers have been stopped: – IBM HTTP Server and Administration Server Windows services – IBM WebSphere Commerce Configuration Manager Windows service – Any WebSphere Application Servers, such as WebSphere Commerce that may have been created (not the case in our example) 3. The WebSphere Commerce V5.5.0.2 Fix Pack can be downloaded from: http://www.ibm.com/support/docview.wss?rs=494&uid=swg24005628 In our example, we downloaded the fix pack (WC_5502_WIN_BE.jar) to the c:\temp\wc55.fp2 directory on the WebSphere Commerce node. 4. After unpacking the fix pack to the c:\temp\wc55.fp2 directory, start the fix pack installation GUI by entering updateWizard.bat from the directory where you have unpacked the fix pack download. 5. We accepted the default language (English) and clicked OK and clicked Next on the Welcome page. 6. The Update Installer wizard will detect where WebSphere Commerce is installed on your system. In our example, we accepted the directory it detected where WebSphere Commerce was installed (for example, c:\ibm\wc), and clicked Next. 7. Select Install fix packs, and then click Next. 8. When prompted to enter the directory where the WebSphere Commerce V5.5.0.2 was unpacked, we entered c:\temp\wc55.fp2\wc and then clicked Next. In our example, since we have not created a WebSphere Commerce instance yet, we only need to install the fix pack found in the wc directory of the unpacked files. 9. Review that the fix pack information and target installation directory information are correct, and then click Next to begin installing the fix pack files. 10.When the installation is complete, you should see a message. The following fix pack was successfully installed: wc55BE_fp2_win If successful, click Finish. If you do not see the successfully installed message, the installer will indicate the log files to check to resolve the problem. In our example, the fix pack installation log files were located in the c:\ibm\wc\logs\update directory. 570 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 16.2.6 WebSphere Commerce instance creation For details on how to create a WebSphere Commerce instance, refer to the Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000 product guide. Note: If you created a WebSphere Commerce or WebSphere Commerce Payments instance prior to installing the WebSphere Commerce V5.5.0.2 Fix Pack, refer to the Installation Guide for IBM WebSphere Commerce V5.5.0.2 Fix Pack for instructions on updating the instance. The following are the high-level steps and setting we used to create the WebSphere Commerce instance for the single-node configuration: 1. Ensure the IBM HTTP Server Windows service has been stopped. 2. Ensure the WebSphere Application Server server1 application server has been stopped. 3. Start the IBM WebSphere Commerce Configuration Manager Windows service (server component). 4. Start the WebSphere Commerce Configuration Manager (client component) by clicking Start -> Programs -> IBM WebSphere Commerce -> Configuration. 5. Log on to the Configuration Manager. By default the user ID is webadmin, and the password is webibm. You will be prompted to change your password during the first logon. 6. Select and expand WebSphere Commerce -> -> Commerce -> Instance List. 7. Right-click Instance List, and select Create Instance. 8. We entered the following settings to create the WebSphere Commerce instance. If not specified, we accepted the default setting. Instance tab: – – – – – – Instance name: wc1 Instance’s root path: c:\ibm\wc\instances\wc1 Merchant Key: Site Admin ID: wcadmin Site Admin Password: Confirm Site Admin Password: Database tab: – WebSphere Commerce Database: Select Create a new database or tablespace Chapter 16. Windows: Migrate a single-tier to a multi-tier 571 – Database administrator name: admin We created the admin user in “Create admin user and assign user rights” on page 560. – Database administrator password: – Database name: wc1 Schema tab: – Database user name: admin In our example, the database administrator and user are the same. In a production environment, these may be separate users. – Database user password: Languages tab: – We accepted the default settings for English. Web Server tab: – Hostname: wcwin1.itso.ral.ibm.com This is the host name of the Web server for the WebSphere Commerce. In a single tier, this is the host name of the WebSphere Commerce node. In a remote Web server configuration, this is the host name of the remote Web server used by WebSphere Commerce. – – – – Web Server Type: Select IBM HTTP Server Primary Document Root: c:\ibm\ihs\htdocs\en_US Server Port: 80 Authentication mode: Select Basic WebSphere tab: – – – – – DataSource Name: WebSphere Commerce DB2 DataSource wc1 JDBC Driver Location: c:\ibm\sqllib\java\db2java.zip Tools Port Number: 8000 WC Admin Port Number: 8002 WC OrgAdmin Port Number: 8004 Payments tab: – Hostname: wcwin1.itso.ral.ibm.com This is the host name of the Web server for WebSphere Commerce Payments. In our example, it is the same node as WebSphere Commerce. – Webserver Port: 5433 Log system tab: – We accepted the default settings. 572 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Messaging tab: – We accepted the default settings. Auction tab: – We accepted the default settings. 9. Click Finish to begin instance creation. 10.When instance creation is complete, you should see a message “Restart your webserver to apply the changes to your webserver configuration file”. Restart the IBM HTTP Server windows service. 11.Next you should see the message, “Instance was successfully created”. Refer to the Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000 to review log files and settings to verify the installation was successful. In our example, the logs used to capture instance creation information are found in the c:\ibm\wc\instances\wc1\logs directory. 12.Do not close the Configuration Manager. It is needed in the next section to create the WebSphere Commerce Payments instance. 16.2.7 WebSphere Commerce Payments instance creation For details on how to create a WebSphere Commerce Payments instance, refer to the Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000 product guide. Note: If you created a WebSphere Commerce or WebSphere Commerce Payments instance prior to installing the WebSphere Commerce V5.5.0.2 Fix Pack, refer to the Installation Guide for IBM WebSphere Commerce V5.5.0.2 Fix Pack for instructions on updating the instance. The following are the high-level steps and settings we used to create the WebSphere Commerce Payments instance for the single-tier configuration: 1. From the Configuration Manager, select and expand WebSphere Commerce -> -> Payments -> Instance List. 2. Right-click Instance List, and select Create Instance. 3. We entered the following settings to create the WebSphere Commerce instance. If not specified, we accepted the default setting. Instance tab: – Instance name: wpm – Check Password Required for startup Chapter 16. Windows: Migrate a single-tier to a multi-tier 573 Note: If you check Password Required for startup, you will need to run the IBMPayServer.bat after starting the WebSphere Commerce Payments application server. – Instance Password: – WebSphere Node Name: wcwin1 – Site Admin ID: wcadmin Database tab: – WebSphere Commerce Payments Database: Select Create a new database or tablespace – Database administrator name: admin – Database administrator password: – Database name: pay1 Schema tab: – Database user name: admin – Database user password: Languages tab: – We accepted the default settings for English. Web Server tab: – Hostname: wcwin1.itso.ral.ibm.com This is the host name of the Web server for WebSphere Commerce Payments. In a single tier, this is the host name of the WebSphere Commerce node. In a remote Web server configuration, this is the host name of the remote Web server used by WebSphere Commerce Payments. – – – – Web Server Type: Select IBM HTTP Server Server Port: 5432 Check Use SSL SSL Port: 5433 WCSRealm tab: – WC Hostname: wcwin1.itso.ral.ibm.com® This is the host name of the Web server for WebSphere Commerce. – WC Web Server Port: 443 4. Click Finish to begin instance creation. 5. When instance creation is complete, you should see a message “Restart your webserver to apply the changes to your webserver configuration file”. Restart the IBM HTTP Server windows service. 574 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 6. Next you should see the message, “Instance was successfully created”. Refer to the Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000 to review log files and settings to verify the instance creation was successful. 7. When done, close the Configuration Manager. 16.2.8 Database backup Prior to publishing a sample store to verify the runtime environment, we recommend that you create a backup of the WebSphere Commerce instance database (for example, wc1) and WebSphere Commerce Payments database (for example, pay1). For details refer to “DB2 backup and restore” on page 988. 16.2.9 Start servers Prior to publishing a sample store to verify the runtime environment, you will need to start the following servers on the WebSphere Commerce node: Start IBM HTTP Server Start DB2 Server Start WebSphere Commerce instance application server Start WebSphere Commerce Payments application server Start IBM HTTP Server The IBM HTTP Server can be started from Windows services. Ensure that you have restarted the IBM HTTP Server after the WebSphere Commerce and WebSphere Commerce Payments instances were created for virtual hosts, alias, and other directives to become active. The IBM HTTP Server is configured to start automatically on server restart. Tip: The WebSphere Commerce V5.5.0.2 Fix Pack addressed a security problem related to directives in the IBM HTTP Server httpd.conf. When creating the WebSphere Commerce instance using the updated Configuration Manager, the httpd.conf will be updated properly. If you have created a WebSphere Commerce instance prior to installing the WebSphere Commerce V5.5.0.2 Fix Pack, you will need to manually update the httpd.conf file as documented in the Installation Guide for IBM WebSphere Commerce V5.5.0.2 Fix Pack included with the fix pack. Chapter 16. Windows: Migrate a single-tier to a multi-tier 575 Start DB2 Server The DB2 Server and supporting services can be started from Windows services. By default, the DB2 Server services are set to start automatically upon server restart. Start WebSphere Commerce instance application server To start the WebSphere Commerce instance application server, do the following: 1. Open a command window and change to the \bin directory. 2. Enter the following command to start the WebSphere Commerce application server: startServer WC_wc1 Where WC_wc1 is the name of the WebSphere Commerce instance application server. 3. To check the status of server startup, we used the tail utility on the startupServer.log file found in the \logs\ directory: tail -f serverStartup.log You should see the following message if successfully started: Server WC_wc1 is open for e-business Start WebSphere Commerce Payments application server To start the WebSphere Commerce Payments application server, do the following: 1. Open a command window and change to the \bin directory. 2. Enter the following command to start the WebSphere Commerce Payments application server: startServer wpm_Commerce_Payments_Server 3. To check the status of server startup, we used the tail utility on the startupServer.log file found in the \logs\ directory: tail -f serverStartup.log You should see the following message if successfully started: Server wpm_Commerce_Payments_Server is open for e-business 4. Run IBMPayServer command. If you checked Password Required for startup on the Instance tab when creating the WebSphere Commerce Payments instance (default), run the following IBMPayServer command from the \payments\bin directory: IBMPayServer.bat 576 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Where in our example is wpm (not full application server name created within WebSphere Application Server), and is the DB2 administrator password. 16.2.10 Verify the runtime environment and store functionality In order to verify the runtime environment, we will publish a sample store and test the functionality of the store. Publish a sample store To publish a sample store, do the following: 1. Ensure you have created a backup of the WebSphere Commerce instance and WebSphere Commerce Payments databases. 2. Ensure the servers are started as listed in 16.2.9, “Start servers” on page 575. 3. Start the WebSphere Commerce Administration Console by entering the following URL in the Microsoft Internet Explorer Web browser. https://:8002/adminconsole Where is the host name of the WebSphere Commerce node, 8002 is the virtual host port defined in the httpd.conf and WebSphere Application Server, adminconsole is the alias defined in the httpd.conf and https is used (SSL enabled). Note: The WebSphere Commerce administration tools required Microsoft Internet Explorer V5.5 or higher. In our example, we used Internet Explorer V6 + Service Pack 1. 4. Log on with the site administrator ID (for example, wcadmin). 5. Select Site and click OK. 6. From the menu, select Store Archives -> Publish. 7. From the Store Archives page, the view is set to Default, which lists the composite (full-featured store archives) for each business model supplied with WebSphere Commerce. Check the desired store to publish (for example, B2BDirect.sar) and then click Next. 8. On the Parameters page, notice the parameters store directory and identifier are set to read only by default. Click Next. Chapter 16. Windows: Migrate a single-tier to a multi-tier 577 For the purposes of testing, it is not an issue that the parameters are set to read only, but when creating a store you will want to modify these settings, as described in Chapter 12, “Create a store” on page 341. 9. When the Summary page appears, click Finish to begin the publishing process for the store archive. 10.Store publishing will schedule a job, since this is a long-running task. You can monitor the store publish on the Publish Status page by clicking Store Archives -> Publish Status. If successful, the publishing status will change to Successful. 11.After the Publish Status changes to Successful, check the check box for the given publishing job, and click Details. 12.Click Launch Store, and click OK for the application Web path for the store. 13.Click Logoff. 14.From the store home page, add the URL of the store to Favorites and then close the Web browser window. 15.Close the WebSphere Commerce Administration Console. Compiling JSPs for tools and store We recommend that you precompile your JSPs for the WebSphere Commerce tools and store. Compiling the JSPs will significantly reduce the amount of time needed to load the WebSphere Commerce tools the first time they are accessed. By default, the WebSphere Application Server will compile the JSPs the first time the JSP is requested. This step is optional, but recommended. IBM WebSphere Commerce V5.5 has separate Web modules for the administration tools and store as follows: WebSphere Commerce Administration Console: SiteAdministrator.war WebSphere Commerce Accelerator: CommerceAccelerator.war WebSphere Commerce Organization Administration Console: OrganizationAdministration.war WebSphere Commerce Stores: Stores.war 578 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Syntax: JspBatchCompiler.sh JspBatchCompiler -enterpriseapp.name [-webmodule.name ] [-cell.name ] [-node.name ] [-server.name ] [-classloader.parentFirst ] [-classloader.singleWarClassloader ] [-filename ] [-keepgenerated ] [-verbose ] [-deprecation ] Refer to the WebSphere Application Server V5 InfoCenter for more information (search on JspBatchCompiler): http://publib7b.boulder.ibm.com/webapp/wasinfo1/index.jsp?deployment=Appl icationServer&lang=en To batch compile JSPs for the WebSphere Commerce tools, do the following: 1. Ensure that the WebSphere Commerce instance application server is started. 2. Open a command window, and set up the command line by running setupCmdLine.bat from the \bin directory. 3. To compile the JSPs for the WebSphere Commerce Administration Console (SiteAdministration.war), enter the following from the \bin directory: JspBatchCompiler.bat -enterpriseapp.name WC_wc1 -webmodule.name SiteAdministration.war -server.name WC_wc1 -node.name wcwin1 -cell.name wcwin1 4. Repeat the previous step for each webmodule.name: – CommerceAccelerator.war – OrganizationAdministration.war – Stores.war Chapter 16. Windows: Migrate a single-tier to a multi-tier 579 Tip: We recommend that you create a script to perform the compile of the JSPs. The script will need to be run any time the cache is flushed for the application server. For example: Create a script wcjsp.bat in the bin directory such as the following: JspBatchCompiler.bat -enterpriseapp.name WC_wc1 -webmodule.name SiteAdministration.war -server.name WC_wc1 -node.name wcwin1 -cell.name wcwin1 Execute the wctools_jsp.bat script: wcjsp.bat We have included a sample wcjsp.bat in the ITSO sample code c:\6969code\scripts directory. Verify the WebSphere Commerce tools After compiling the JSPs for the WebSphere Commerce tools, verify that they are working properly. WebSphere Commerce Administration Console To start the WebSphere Commerce Administration Console, enter the following in the Microsoft Internet Explorer Web browser and log on as the site administrator (for example, wcadmin): https://:8002/adminconsole WebSphere Commerce Accelerator To start the WebSphere Commerce Accelerator, enter the following in the Microsoft Internet Explorer Web browser and log on as the site administrator (for example, wcadmin): https://:8000/accelerator WebSphere Commerce Organization Administration Console To start the WebSphere Commerce Organization Administration Console, enter the following in the Microsoft Internet Explorer Web browser and log on as the site administrator (for example, wcadmin): https://:8004/orgadminconsole 580 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Create a test shopping transaction Register a new user and complete a shopping transaction as follows: 1. Enter the following URL in a Web browser to access the sample store that was published or access the store URL saved to the Favorites list of your Web browser from a previous step: http://wcwin1.itso.ral.ibm.com/webapp/wcs/stores/servlet/ToolTech/index.jsp Note: Depending on the number of stores that have been published, you may have a different store ID number and if you published a store other than ToolTech, you will have a different store directory name. 2. Register a new user. For example, we create a testuser1 user. 3. Log on to the store as testuser1. 4. Purchase a product as the testuser1 user. When prompted to enter the credit card information, we entered 0000000000000000 (16 0s) as a test number for Visa. Note: If you do not have a credit card type visible from the store checkout, most likely the WebSphere Commerce Payments application server (and IBMPayServer) were not running at the time of publishing. The sample store archives contain default payment information for credit card types for the offline payment cassette. To resolve this problem, republish the store or manually create an account, credit card type, etc. Verify payment After the order is completed, the order should be awaiting payment approval within WebSphere Commerce Payments assuming you used the default offline cassette. 1. Enter the following URL to access the WebSphere Commerce Payments Administration Console: https://:5433/webapp/PaymentManager 2. Log on to WebSphere Commerce Payments as the site administrator (for example, wcadmin). 3. Click Approve from the left-hand navigational bar. 4. Check the check box for the order generated and click Approved Selected. Congratulations, the WebSphere Commerce node single-tier configuration is now complete. Chapter 16. Windows: Migrate a single-tier to a multi-tier 581 16.3 Add a remote Database Server node This section describes the tasks required to migrate the WebSphere Commerce and related databases to a remote DB2 Server. This section includes the following tasks: Windows 2000 installation Install DB2 V8.1 Enterprise Edition Server Backup and restore of databases Configure DB2 connectivity Verify the remote DB2 Server node configuration 16.3.1 Windows 2000 installation Refer to 16.2.1, “Windows installation” on page 560 for details on required service levels of Windows 2000 and user right assignments for DB2. 16.3.2 Install DB2 V8.1 Enterprise Edition Server To install the IBM DB2 V8.1 Enterprise Edition Server on the remote DB2 Server, do the following: 1. Insert the DB2 UDB V8.1 Enterprise Server Edition CD. 2. Run Setup to start the installation. 3. When the DB2 Installer window appears, click Install Products. 4. When the Select the Product to Install window appears, select DB2 UDB Enterprise Server Edition (default and only option) and then click Next. 5. When the Welcome window appears, click Next to launch the DB2 Setup wizard. 6. When the License Agreement window appears, review the agreement and select I accept the terms in the license agreement and click Next. 7. When the Type of Installation window appears, select Custom Install and then click Next. 8. When the Select the Installation Action window appears, select Install DB2 UDB Enterprise Server Edition and then click Next. 9. When the Installation Action window appears, take note of the Response File check box. This can be used to capture your selection options to be used for a future installation. When selecting Custom Install, by default most of the installation options are set to be installed. Click Next. 582 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 10.When the Select the Features you Want to Install window appears, select the following options and then click Next: – Administration Tools: We accepted the default (all suboptions selected). – Getting started: We deselected this option. Note: This option may be useful to install if you are experimenting and have plenty of disk space. – Client support: We accepted the default (all suboptions selected). – Application Development tools: We accepted the default (all suboptions selected, especially Base Application Development Tools to load stored procedures), with one exception. We deselected Warehouse Samples, since we will also deselect Business Intelligence. – Server Support: We accepted the default (all suboptions selected). – Business Intelligence: We deselected this option. This option is needed for WebSphere Commerce Analyzer. – Directory: c:\ibm\sqllib Note: The options selected requires approximately 400 MB of disk space. 11.When the Languages to Install window appears, select the desired language (for example, English), and click Next. 12.When the Set User Information for DB2 Administration Server window appears, enter the following and then click Next: – – – – Domain: we left this field blank User name: db2admin Password: Confirm password: 13.When the Setup the Administration Contact List appears, we accepted the default settings and then clicked Next. 14.When the warning message “Notification SMTP server has not been specified”, click OK. 15.When the Create a DB2 instance window appears, select Create the DB2 instance and then click Next. 16.When the Configure DB2 instances window appears, we accepted the default (DB2, DB2CTLSV) and then clicked Next. 17.When the Prepare the DB2 tools catalog window appears, select Do not prepare the DB2 tools catalog on this computer and then click Next. Chapter 16. Windows: Migrate a single-tier to a multi-tier 583 18.When the Specify a contact for health monitor notification window appears, select Defer the task after installation is complete, and then click Next. 19.When the Request satellite information window appears, accept default settings and click Next. 20.When the Start copying files window appears, review the selected options and then click Finish. 21.When the Setup is Complete window appears, click Finish. 22.Restart your system. 16.3.3 DB2 UDB V8.1 Fix Pack 3 installation Refer to 16.2.3, “DB2 UDB V8.1 Fix Pack 3 installation” on page 562 for details. 16.3.4 Backup and restore of databases Now that everything is working on the single-tier WebSphere Commerce node, we need to create a backup of the WebSphere Commerce instance database and the WebSphere Commerce Payments database. Next, we will restore these databases on the newly added remote DB2 Server node. Lastly, we will drop the databases on the WebSphere Commerce node. For more information on DB2 backup, refer to “DB2 backup and restore” on page 988. Back up databases on the WebSphere Commerce node The high-level steps to back up the databases on the existing single-tier WebSphere Commerce node are as follows: 1. Ensure the WebSphere Commerce instance application server is stopped. 2. Ensure the WebSphere Commerce Payments application server is stopped and the IBMPayServer is stopped. 3. Create a backup directory that will later be copied and restored on the remote DB2 Server node. For example, we created the c:\wcwin1.db directory. 4. Verify that no applications are connected to the databases: db2 list applications There should not be any connections, since the applications that connect to the databases have been stopped. If there are connections not able to be stopped, enter the following to enforce that no applications are connected: db2 force applications all db2 terminate db2stop db2start 584 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 5. To back up the databases, do the following: a. To back up the WebSphere Commerce instance database: db2 backup db wc1 to c:\wcwin1.db b. To back up the WebSphere Commerce Payments database: db2 backup db pay1 to c:\wcwin1.db Restore databases to the remote DB2 Server node To restore the WebSphere Commerce instance database and WebSphere Commerce Payments database to the remote DB2 Server node, do the following: 1. Copy the database backup directory containing the DB2 database backups from the WebSphere Commerce node to the remote DB2 Server node (for example, c:\wcwin1.db). 2. Restore the WebSphere Commerce instance database and WebSphere Commerce Payments database on the remote DB2 Server node: db2 restore db wc1 from c:\wcwin1.db db2 restore db pay1 from c:\wcwin1.db 3. Perform an SQL query on the restore WebSphere Commerce instance database as a basic test that the restore worked properly: db2 connect to wc1 db2 select * from catalog db2 connect reset Drop databases After you have created a backup of the databases and restored them to the remote DB2 Server node, you can drop the databases on the single-tier WebSphere Commerce node by running the following commands from a DB2 command window: db2 drop db wc1 db2 drop db pay1 Note: Make sure that you have a backup before dropping the databases. 16.3.5 Configure DB2 connectivity The objective of this section is to configure network connectivity between DB2 installed on the WebSphere Commerce node and the remote DB2 Server node. Chapter 16. Windows: Migrate a single-tier to a multi-tier 585 Catalog the TCP/IP node To catalog the TCP/IP node, do the following on the WebSphere Commerce node: 1. Ensure DB2 Server or Administration Client is installed on the WebSphere Commerce node. 2. Ensure DB2 Server is installed on the remote DB2 Server node. 3. Open a DB2 command prompt on the WebSphere Commerce node. 4. From a DB2 command window, type the following command: db2 catalog tcpip node remote server The is the DB2 instance connection port found on the DB2 Server node in the c:\winnt\system32\drivers\etc\services file. In our example, the connection port for the DB2 Server was 50001. The service name in our services file looked like the following: db2c_DB2 50001/tcp Alternatively, in place of the port number a service name can be used. If a service name is used, the port and service name must be added to the DB2 client system services file so that it can resolve where to find the system. For example: db2 catalog tcpip node db2win1 remote db2win1 server 50000 Attach to the remote DB2 Server From a DB2 command window, type the following command: db2 attach to user using For example: db2 attach to db2win1 user admin using Catalog the databases Once you have attached to the remote DB2 Server, catalog the WebSphere Commerce instance and WebSphere Commerce Payments databases from a DB2 command window: db2 catalog db at node For example: db2 catalog db wc1 at node db2win1 db2 catalog db pay1 at node db2win1 586 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide List databases Notice that the database are now remote when you list the DB2 database with the following command: db2 list db directory 16.3.6 Verify the remote DB2 Server node configuration After completing the database restore and connectivity configuration, verify that WebSphere Commerce in the two-tier configuration is functioning properly. 1. Restart the appropriate servers. – WebSphere Commerce node • • • • IBM HTTP Server 1.3.26 IBM WebSphere Application Server V5 - server1 WebSphere Commerce instance application server WebSphere Commerce Payments application server – DB2 Server node • DB2 Server 2. Verify the functionality of the WebSphere Commerce and WebSphere Commerce Payment administration tools and store. 16.4 Add remote Web Server node In this scenario, we will add a remote Web Server node using IBM HTTP Server and the WebSphere Application Server plug-in. We used the IBM HTTP Server; however, the procedure documented can be adapted for other supported Web servers. The high-level procedure to add a remote Web Server to an existing single-tier or two-tier remote database WebSphere Commerce runtime environment is as follows: Review preconditions Install IBM HTTP Server and WebSphere plug-in WebSphere Application Server V5 Fix Pack 1 installation Configure IBM HTTP Server for SSL Verify IBM HTTP Server IBM HTTP Administration (optional) Modify Web Server host name Configure the Web server static content Verify the remote Web Server configuration Chapter 16. Windows: Migrate a single-tier to a multi-tier 587 16.4.1 Review preconditions When adding a remote Web Server node for WebSphere Commerce, we considered the following preconditions: Precondition 1: WebSphere Commerce node includes a working IBM HTTP Server and the WebSphere Commerce instance has been created. This scenario applies to single-tier and two-tier remote Database Server configurations. In this case IBM HTTP Server is installed, configured, and verified, and the WebSphere Commerce instance has been created on the WebSphere Commerce node. This precondition offers a useful starting point, in that the httpd.conf may already contain the needed WebSphere Commerce instance aliases and directives for a WebSphere Commerce instance. Precondition 2: WebSphere Commerce node includes a working IBM HTTP Server and the WebSphere Commerce instance has not been created. The big difference between this scenario and the previous is that the WebSphere Commerce instance aliases and directives will need to be added to the remote IBM HTTP Server httpd.conf at a later time. Precondition 3: Remote Web Server configuration with WebSphere Commerce from scratch. In this case, the specialist implementing the configuration will install the remote Web server from the start. This scenario does not depend on ever having an IBM HTTP Server installed on the WebSphere Commerce node. The disadvantage to this is that the httpd.conf will need to be constructed manually. This may not be too much of an issue for advanced specialists that already have a “template” of an httpd.conf that they have constructed from a previous install. The default procedure described in this chapter assumes that you have precondition 1. We will provide an optional section to address the needs of precondition 2 and 3. 16.4.2 Install IBM HTTP Server and WebSphere plug-in This section describes how to install the IBM HTTP Server V1.3.26 and WebSphere Application Server V5.0 plug-in. When WebSphere installs the IBM HTTP Server, the default httpd.conf file does not contain the SSL directives and the WebSphere plug-in configuration is made to the httpd.conf. We will need to manually copy the httpd.conf.sample containing the SSL directives. To install the IBM HTTP Server and WebSphere Application Server plug-in, complete the following steps: 1. Insert the WebSphere Application Server CD. 588 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 2. Run Install.exe from the nt directory to start the WebSphere Application Server Installer. 3. Select the Language for the Installer (for example, English) and then click OK. 4. When the Welcome to the InstallShield Wizard window appears, click Next. 5. When the terms and conditions window appears, review the agreement and select I accept the items of the license agreement and then click Next. 6. Select Custom when the Choose the setup type window appears and click Next. 7. We selected only the following options to install, and then clicked Next: – Check IBM HTTP Server Version 1.3.26 – Check Web Server Plugins • Check IBM HTTP Server – Deselect all other options. 8. When prompted to specify the installation directories, we entered the following and then clicked Next. – IBM WebSphere Application Server: c:\ibm\was – IBM HTTP Server: c:\ibm\ihs 9. When prompted to run the IBM HTTP Server as a service, we entered the following and then clicked Next: – Check Run IBM HTTP Server as a service – User ID: admin The user ID must exist within Windows and be able to run as a Windows service. Refer to “Create admin user and assign user rights” on page 560 for details on how to assign user rights. – Password: 10.A confirmation window will appear. Click Next to begin the installation. This process will take a few minutes. 11.When the installation is finished the Registration window appears. Deselect the check box if you do not want to register the product online and click Next. 12.At this point you have successfully installed the IBM HTTP Server V1.3.26 and the Web Server plug-in. Click Finish to close this window. 16.4.3 WebSphere Application Server V5 Fix Pack 1 installation On the remote Web Server node, you will need to install WebSphere Application Server V5.0 Fix Pack 1 (V5.0.1) and the Cumulative WebSphere Plug-in fix. Chapter 16. Windows: Migrate a single-tier to a multi-tier 589 Refer to 16.2.4, “WebSphere Application Server V5 Fix Pack 1 installation” on page 563 for details. 16.4.4 Configure IBM HTTP Server for SSL After the installation of the IBM HTTP Server, we recommend that you configure the IBM HTTP Server for SSL and create an administrative user to remotely manage the IBM HTTP Server. In our example, we will use a self-signed certificate. For production use, a proper certificate will need to be obtained. Enable the httpd.conf for SSL To modify the httpd.conf to enable SSL support, do the following: 1. Stop the IBM HTTP Server V1.3.26 Windows service. 2. Back up the original httpd.conf. For example: cd \\conf copy httpd.conf httpd.conf.org 3. Copy the httpd.conf.sample containing the commented SSL directives to httpd.conf. For example: copy httpd.conf.sample httpd.conf 4. Open the \conf\httpd.conf file with a text editor. 5. Search for the following lines, uncomment the # symbol and modify the settings as described: – Verify that the ServerName value includes your host name: ServerName= – Uncomment the IBM SSL module for the given SSL encryption level (56 or 128 bit). For example: LoadModule ibm_ssl_module/IBMModuleSSL128.dll Note: Where 56 or 128 is the appropriate encryption level for your locale. For example, 128 is for 128-bit encryption in the US and Canada. – Uncomment the following line to listen on port 443 for HTTPS: Listen 443 – Uncomment and update the VirtualHost with your host name as follows: Note: Substitute your fully qualified host name in this line (for example, ). 590 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – Uncomment: SSLEnable – Uncomment: – Uncomment: SSLDisable – Uncomment and update the following: Keyfile "/ssl/keyfile.kdb" Note: The keyfile path has been modified to include ssl instead of keys. For example: Keyfile "c:\ibm\http/ssl/keyfile.kdb" – Uncomment: SSLV2Timeout 100 SSLV3Timeout 1000 6. Save the changes to the httpd.conf file. Copy WebSphere plug-in entries During the installation of the IBM HTTP Server and WebSphere plug-in, the httpd.conf was updated with the plug-in entries. Now that we have copied the httpd.conf.sample in the previous section to enable the SSL directives, we now also need to add the WebSphere plug-in entries to the httpd.conf. 1. Change to the directory the IBM HTTP Server \conf directory. 2. Modify the httpd.conf, and add the following for the WebSphere plug-in at the end of the file: LoadModule ibm_app_server_http_module "c:\ibm\was/bin/mod_ibm_app_server_http.dll" WebSpherePluginConfig "c:\ibm\was/config/cells/plugin-cfg.xml" Tip: The above text is two separate lines. Within the httpd.conf, the lines are not wrapped. If you backed up the httpd.conf.org, you can cut and paste the plug-in entries to the SSL-enabled httpd.conf. Chapter 16. Windows: Migrate a single-tier to a multi-tier 591 Create the IBM HTTP Server key store To create the IBM HTTP Server key store database used to store certificates, do the following: 1. From Windows, click Start -> Programs -> IBM HTTP Server 1.3.26 -> Start Key Management Utility. 2. From the menu bar, click Key Database File -> New. 3. In the New window, enter the following and then click OK: – Key Database Type: CMS key database file – File name: keyfile.kdb – Location: \ssl (for example, c:\ibm\http\ssl) Note: This path must match the keyfile path in the httpd.conf. 4. In the Password Prompt window, enter the following and then click OK: – Password: (to protect the key store file) – Check Set expiration time and enter the number of days before the password will expire. If no expiration is required, do not check. Note: Although not required in a development environment, it is recommended that all key stores used in production environments set an expiration period. – Check Stash the password to a file. Note: The IBM HTTP Server accesses the password-protected key store. 5. When the information window appears with the following message, click OK: The password has been encrypted and saved in the file: c:\ibm\http\ssl\keyfile.sth 6. Close the IBM Key Management Utility. Create a certificate for the IBM HTTP Server For development and testing purposes, you should create a new self-signed certificate. The following steps outline the creation of a new self-signed certificate: 1. From the Key Management Utility menu bar, select Create -> New Self-Signed Certificate. 592 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 2. Fill in the information on the form and click OK. For example, we entered the following: – Key Label: http_ssl – Common Name: – Organization: (for example, ibm) Note: For the production IBM HTTP Server, you should create a new certificate request (do not use a self-signed certificate). 3. When done, close the Key Management Utility. 16.4.5 Verify IBM HTTP Server After the IBM HTTP Server configuration, we recommend that you complete the following verification tests: Start IBM HTTP Server Verify the IBM HTTP Server Back up the httpd.conf Start IBM HTTP Server The IBM HTTP Server service can be started by one of the following methods: IBM HTTP Server 1.3.26 Windows service or From the command line or batch file containing the following: net start “IBM HTTP Server 1.3.26” Verify the IBM HTTP Server To verify IBM HTTP Server is working properly, enter the following URLs in a Web browser after the IBM HTTP Server has been started: Verify HTTP: http:// Verify HTTPS: https:// Back up the httpd.conf After you have verified that the IBM HTTP Server is working properly with SSL enabled, we recommend that you make a backup of the \conf\httpd.conf file to httpd.conf.ssl. In the event that you need to roll back the installation of subsequent software such as WebSphere Chapter 16. Windows: Migrate a single-tier to a multi-tier 593 Application Server and WebSphere Commerce, which modify this file, you will have a clean starting point and will benefit in terms of the time saved on configuration. For example, we copied the \conf\httpd.conf to httpd.conf.ssl. 16.4.6 IBM HTTP Administration (optional) The configuration and usage of the IBM HTTP Administration is optional. Many of the configuration tasks we performed were to directly modify configuration files for the IBM HTTP Server from the command-line utilities with a text editor. Create an administrative user To create an administrative user used to manage the IBM HTTP Server from the IBM HTTP Server Administration Web-based interface, do the following: 1. Open a command prompt and navigate to the directory. 2. Enter the following command to create the administrative user: htpasswd -cm conf\admin.passwd New password: Re-type new Password: Start IBM HTTP Administration The IBM HTTP Administration service can be started by one of the following methods: IBM HTTP Administration 1.3.26 Windows service or From the command line or batch file containing the following: net start “IBM HTTP Administration 1.3.26” Verify the IBM HTTP Administration To verify IBM HTTP Administration is working properly, do the following: 1. Enter the following URL in a Web browser: http:// or https:// 2. Click Configure server. 3. When prompted, enter the user ID and password of the IBM HTTP Administration user created in “Enable the httpd.conf for SSL” on page 590. 594 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 4. Navigate to the menu options. When done, you may stop and disable the IBM HTTP Administration service. 16.4.7 Modify Web Server host name Now that the remote Web Server node has been verified, we will configure the WebSphere Commerce instance and WebSphere Commerce Payments instance to use the remote Web Server host name. In our example, the WebSphere Commerce node has a working IBM HTTP Server configured with WebSphere Commerce. We will need to disable the IBM HTTP Server that is running on the WebSphere Commerce node. 1. On the WebSphere Commerce node, back up the existing \conf\httpd.conf to httpd.conf.wcwin1. 2. Stop the IBM HTTP Server on the WebSphere Commerce node from Windows services. 3. Set the Windows services Startup Type to Disabled for the IBM HTTP Server on the WebSphere Commerce node. 4. Stop the WebSphere Commerce instance application server. 5. Stop the WebSphere Commerce Payments application server. Important: At the time of writing the redbook, we found that we were not able to update the host name of the Web Server from the Configuration Manager because the field was greyed out. To work around this problem, we will manually update the host name in the instance.xml file, update the httpd.conf, update the WebSphere virtual host aliases, and regenerate the plugin-cfg.xml. 6. Back up the \instances\\xml\.xml to .xml.org for the WebSphere Commerce and WebSphere Commerce Payments instances. 7. Update the WebSphere Commerce instance \instances\\xml\.xml file to change the value of the HOSTNAME keyword to the remote Web Server host name for all occurrences of the fully qualified host name. For example: – From: wcwin1.itso.ral.ibm.com Single-tier host name where IBM HTTP Server was installed and used. Chapter 16. Windows: Migrate a single-tier to a multi-tier 595 – To: webwin1.itso.ral.ibm.com Three-tier host name of remote Web Server where IBM HTTP Server is installed and now used. 8. Back up theWebSphere Commerce Payments instance \instances\wpm\xml\wpm.xml file to wpm.xml.org. 9. Update the WebSphere Commerce Payments instance \instances\wpm\xml\wpm.xml file to change the value of the HOSTNAME keyword to the remote Web Server host name in the following sections: – Virtual Hosts. d. Update the remote Web Server host name for the host alias for following virtual hosts (for example, from wcwin1 to webwin1): • • 596 VH_PYM_wpm VH_wc1 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide • • • VH_wc1_Admin VH_wc1_OrgAdmin VH_wc1_Tools e. Under Environment, click Update Web Server Plugin and then click OK. f. Click Save and Save again to save the master configuration. g. Ensure the \config\cells\plugin-cfg.xml contains the updates for the host name of the remote Web Server for the host aliases. h. Log out and close the WebSphere Administration Console. i. Stop the WebSphere Application Server sever1 application server. 12.Copy the updated \conf\httpd.conf from the WebSphere Commerce node to the same location on the remote Web Server node. 13.Copy the updated \config\cells\plug-cfg.xml from WebSphere Commerce node to the same location on the remote Web Server node. 16.4.8 Configure the Web server static content This section describes the steps needed to copy and configure the remote Web Server static content. Copy store static content to the remote Web Server node When using a remote Web server, the static content for WebSphere Commerce stores is served by the Web server. Copy the following directory from the WebSphere Commerce node to the remote Web Server node: Copy the contents of the Stores.war from the WebSphere Commerce node to the remote Web Server node c:/ibm/was/installedApps/wcwin1/WC_wc1.ear/Stores.war Note: The directory structure must match the WebSphere Commerce node. You will need to manually create the directories on the remote Web Server node. Copy tools static content to the remote Web Server node When using a remote Web server, the static content for WebSphere Commerce tools served by the Web server. Copy the contents of the following tools .war directories on the WebSphere Commerce node to the remote Web Server node: c:/ibm/was/installedApps/wcwin1/WC_wc1.ear/CommerceAccelerator.war c:/ibm/was/installedApps/wcwin1/WC_wc1.ear/OrganizationAdministration.war c:/ibm/was/installedApps/wcwin1/WC_wc1.ear/SiteAdministration.war Chapter 16. Windows: Migrate a single-tier to a multi-tier 597 Note: The directory structure must match the WebSphere Commerce node. You will need to manually create the directories on the remote Web Server node. Removing dynamic content from the Web server Remove JSPs and JAR files from all directories found within .war directories on the remote Web Server node. 16.4.9 Verify the remote Web Server configuration After the configuration is complete, do the following to verify the configuration: 1. Restart the servers. a. Restart the IBM HTTP Server on the remote Web Server node. b. Restart the WebSphere Commerce instance application server on the WebSphere Commerce node. c. Restart the WebSphere Commerce Payments application server and IBMPayServer on the WebSphere Commerce node. 2. Access the WebSphere Commerce administration tools: – WebSphere Commerce Accelerator: https://:8000/accelerator – WebSphere Commerce Administration Console: https://:8002/adminconsole – WebSphere Commerce Accelerator https://:8004/orgadminconsole 3. Access the sample store. For example, we completed a transaction for the ToolTech sample store: http:///webapp/wcs/stores/servlet/ToolTech/index.jsp 4. Approve payment from the WebSphere Commerce Payments Administration Console: https://:5433/webapp/PaymentManager Congratulations, you have now completed the configuration of adding a remote Web Server to an existing WebSphere Commerce runtime environment. 598 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 17 Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server The objective of this chapter is to provide an advanced three-tier (also called 3-tier) runtime environment in a three-node scenario for WebSphere Commerce V5.5 on the Sun Solaris platform using Oracle9i Enterprise Edition and Sun ONE Enterprise Web Server (iPlanet Web Server V6.0). The scenario complements the procedures documented in the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems product guide by providing real-world examples, best practices, tips, and workarounds. The highlights for this scenario are as follows: Solaris three-tier, three-node runtime environment (best practices, tips, workarounds) Oracle9i Enterprise Edition iPlanet Web Server IBM WebSphere Commerce V5.5, Business Edition © Copyright IBM Corp. 2003. All rights reserved. 599 This chapter is organized into the following sections: Scenario overview and planning Solaris installation Web Server node implementation Database Server node implementation WebSphere Commerce node implementation Verify the runtime environment 17.1 Scenario overview and planning This section describes the scenario and defines the hardware and software used within the ITSO WebSphere Commerce three-tier runtime environment for the Solaris platform. The scenario and planning section is organized as follows: Scenario overview Hardware and software prerequisites Software used within the ITSO test environment Software installation paths and variables Hardware used within the ITSO test environment File system planning 17.1.1 Scenario overview The scenario documented in this redbook is complementary to the installation procedures documented in the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems product guide. The product installation guide does a good job of explaining the various possible options. The procedure documented in this chapter includes best practices and workarounds for a specific configuration. This three-tier runtime environment scenario features Solaris 8, iPlanet Enterprise Web Server 6.0, and Oracle9i Enterprise Edition Release2. This combination is common on the Sun Solaris platform. We guide you through the process of installing, configuring, and verifying each component of the three-tier runtime environment in a three-node setup. This scenario includes tips for security, systems management, and scalability. Figure 17-1 on page 601 depicts the runtime product mapping for the three-tier runtime environment on the Solaris platform. 600 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide DMZ Outside world Internal network Oracle9i EE Server 9.2.0.1 Solaris 8 + MU7 + Recommended Patches User I N T E R N E T 80/443 80/443 Web Server node (sun1) iPlanet Web Server V6 WebSphere V5 plugin + Fixes Solaris 8 + MU7 + Recommended Patches Domain Firewall Domain Name Server Protocol Firewall Public Key Infrastructure WebSphere Commerce Web node Server (sun2) Database Server node (sun3) WebSphere Application Server V5 + Fixes WebSphere Commerce 5.5, Business Edition WebSphere Commerce Payments 5.5 Oracle9i EE Client 9.2.0.1 Solaris 8 + MU7 + Recommended Patches Figure 17-1 WebSphere Commerce three-tier runtime environment product mapping for Solaris 17.1.2 Hardware and software prerequisites The most current and detailed information on the hardware and software requirements can be found in the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems product guide. In 17.1.6, “File system planning” on page 604, we provide detailed information about the file system sizes we used within our three-tier for Solaris. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 601 Note: Hardware requirements vary depending on the number of items in the store, the degree to which audio, video, and graphics are used, and the expected number of hits by customers per time interval. Response time in an Internet environment depends on a variety of network and telecommunication factors, such as line speeds, local network constraints, and available processing capacity on the server. The hardware requirements listed in the product installation guide are guidelines for all components being installed on one system. The system requirement minimums are less as additional nodes are added. This being said, if you are planning for a three-tier runtime for scalability reasons, you will want to have sufficient hardware on each node to achieve desired non-functional requirements. 17.1.3 Software used within the ITSO test environment We used the following software on each of the nodes within the WebSphere Commerce three-tier Solaris configuration. Table 17-1 Web Server node Software Version Solaris 8 + Maintenance Update 7 (MU) + Recommended 7 Sun ONE Web Server Enterprise Edition Note: formerly iPlanet Web Server 6 + Service Pack 4 WebSphere Application Server plug-in 5.0 Table 17-2 WebSphere Commerce node 602 Software Version Solaris 8 + Maintenance Update 7 (MU) + Recommended 7 Oracle9i Enterprise Edition Client 9.2.0.1 WebSphere Application Server 5.0 WebSphere Commerce Business Edition 5.5 WebSphere Commerce Payments 5.5 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Table 17-3 Database Server node Software Version Solaris 8 + Maintenance Update 7 (MU) + Recommended 7 Oracle9i Enterprise Edition Server * WebSphere Commerce table space * WebSphere Commerce Payments table space 9.2.0.1 17.1.4 Software installation paths and variables Table 17-4 describes the variable names, default installation directories and components. We will reference these variables throughout this document. Table 17-4 Product installation directories Variable Default directory Component /usr/iplanet/servers iPlanet Web Server /opt/oracle Oracle9i /opt/WebSphere/AppServer WebSphere Application Server /opt/WebSphere/CommerceServer55 WebSphere Commerce 17.1.5 Hardware used within the ITSO test environment This section lists the hardware, key system specifications, host name and IP address for each node of the scenarios used within the ITSO test environment. Web Server node In this scenario, the remote Web server is installed on the following hardware: Sun SPARC Ultra 60 (600-6486-01) – – – – 450 MHz UltraSPARC II CPU 512 MB RAM 17 GB hard disk 1 Ethernet adapter (built-in) Hostname: sun1.itso.ral.ibm.com IP address: 9.24.105.46 Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 603 WebSphere Commerce node In this scenario, the WebSphere Commerce node is installed on the following hardware: Sun SPARC Ultra 60 (600-6486-01) – – – – 450 MHz UltraSPARC II CPU 1 GB RAM 17 GB hard disk 1 Ethernet adapter (built-in) Hostname: sun2.itso.ral.ibm.com IP address: 9.24.105.47 Database Server node This system is used as the Database Server, and the databases for the WebSphere Commerce instance database, and WebSphere Commerce Payment database. Sun SPARC Ultra 60 (600-6486-01) – – – – 450 MHz UltraSPARC II CPU 1 GB RAM 17 GB hard disk 1 Ethernet adapter (built-in) Hostname: sun3.itso.ral.ibm.com IP address: 9.24.105.48 17.1.6 File system planning During the interactive phase of the Solaris 8 operating system installation, you will need to customize the file systems and allocate the necessary space for the applications to be installed in subsequent steps. For example, if you are building a three-tier WebSphere Commerce runtime for Solaris with Oracle and iPlanet Web Server, your file system requirements will be different for each of the following nodes: Web Server node WebSphere Commerce node Database Server node Web Server node The remote Web server in this scenario includes the software listed in Table 17-1 on page 602 and the static content for the WebSphere Commerce administration tools and store. 604 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Table 17-5 lists the disk space needed for each application on the remote Web server. This information can be used to calculate the total file system size when creating the file systems during the installation. Table 17-5 Application disk space usage: Web Server node Application WebSphere iPlanet plug-in, interim fix, Sun JDK 1.3.1 File system mount points installed to Disk space required Disk space used /opt/WebSphere/AppServer N/A 420 MB * 330 MB for temp space for install WebSphere Commerce static content for store and admin tools /opt/WebSphere/AppServer/insta lledApps/WC_Enterprise_App_.ear/wcstores.war N/A N/A WebSphere Commerce node The WebSphere Commerce node includes the software listed in Table 17-2 on page 602 and the WebSphere Commerce store application assets. Table 17-6 lists the disk space needed for each application on the WebSphere Commerce node. This information can be used to calculate the total file system size when creating the file systems during the installation. Table 17-6 Application disk space usage: WebSphere Commerce node Application File system mount points installed to Disk space required Disk space used Oracle9i Client /opt/oracle/u01 400 MB (application user) 400 MB WebSphere Application Server /opt/WebSphere/AppServer N/A 550 MB Note: 330 MB for temp space WebSphere Commerce * runtime * docs /opt/WebSphere/CommerceServer WebSphere Commerce instance 290 MB 436 MB 500 MB Note: runtime /opt N/A 220 MB WebSphere Commerce store /opt N/A WebSphere Commerce Payment /opt/PaymentManager N/A 72 MB Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 605 Database Server node The Database Server node in this scenario includes software listed in Table 17-3 on page 603 and the database table space for WebSphere Commerce and WebSphere Commerce Payments. Table 17-7 lists the applications and disk space needed for the target files system to install the application. This information can be used to calculate the total file system size when creating the file systems during the installation. Table 17-7 Application disk space usage: Database Server node Application File system mount points installed to Disk space required Disk space used Oracle9i Enterprise Edition /opt/oracle/u01 2.7 GB (full custom ) 3 GB Table space within o920 database/instance /opt/oracle/u02 /opt/oracle/u03 N/A * WebSphere Commerce (wctblspc) * WebSphere Commerce Payment (paymantblspc) 105 MB Note: After the installation of Solaris 8, maintenance update 7(MU7) and the 8_Recommended patches, we listed the disk space allocation and usage by the file system, as follows: # df -k Filesystem /dev/dsk/c0t0d0s0 /dev/dsk/c0t0d0s6 /proc fd mnttab swap swap /dev/dsk/c0t0d0s5 /dev/dsk/c0t0d0s7 kbytes used avail capacity 494235 188564 256248 43% 2056211 675243 1319282 34% 0 0 0 0% 0 0 0 0% 0 0 0 0% 1831976 8 1831968 1% 1832304 336 1831968 1% 6196234 1221 6133051 1% 7597873 12 7521883 1% Mounted on / /usr /proc /dev/fd /etc/mnttab /var/run /tmp /opt /export/home 17.2 Solaris installation The steps in the following section must be completed on all nodes of the three-tier environment: Network information 606 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Installing Solaris 8 Installing Solaris 8 maintenance update Installing Solaris 8 recommended patches 17.2.1 Network information During the Solaris 8 installation, you will be prompted for information specific to your network environment. We listed the necessary information to complete the installation in preparation for installing WebSphere Commerce V5.5 for Solaris. The following network information is needed during the Solaris installation: Host name IP address Domain name Subnet netmask Default router (configured manually after the Solaris installation) 17.2.2 Installing Solaris 8 Appendix B, “Solaris tips” on page 969 describes all basic procedures, tasks, and commands necessary to install, configure, and manage the Solaris operating system in preparation for a WebSphere Commerce V5.5 installation. Tip: When installing Solaris, refer to 17.1.6, “File system planning” on page 604 for the node to be installed. 17.2.3 Installing Solaris 8 maintenance update The Solaris 8 MU7 contains the same set of patches as the ones prepackaged on the Solaris 8 7/01 software CDs. If your release of Solaris 8 is dated 7/01 or later, then it is already at the minimum level of maintenance update, which is needed for WebSphere Commerce. A family comparison chart of Solaris 8 updates can be reviewed online at the following location: http://www.sun.com/software/solaris/fcc To identify the version of your Solaris 8 software, type: # cat /etc/release If the release does not specify a date later than 7/01 or Solaris 8 Maintenance Update 5 is applied, then you have to apply MU5 or higher. Appendix B, “Solaris tips” on page 969 describes detailed steps to download and install the Solaris maintenance update. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 607 17.2.4 Installing Solaris 8 recommended patches Ensure that you have the most recent Solaris patch cluster installed on your Solaris system. The following Solaris patches at the indicated levels or higher are required by WebSphere Commerce V5.5 and must be installed on your Solaris system: 608 110380-04 110934-10 111111-03 110662-09 112396-02 108987-09 111293-04 108869-18 109326-09 109147-20 112218-01 108949-07 108434-09 108435-09 110458-02 111325-02 108875-12 111881-02 109898-05 110075-01 110901-01 108901-06 112325-01 110943-01 110898-06 109324-04 110916-03 109091-05 110387-03 110283-05 109277-03 110951-03 111234-01 110903-05 112138-01 109320-06 109470-02 109783-02 109951-01 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 110453-03 110945-07 111071-01 111232-01 110700-01 110939-01 111548-01 111570-02 108652-61 110322-02 110286-10 111504-01 111606-02 109882-06 111069-01 110615-05 110668-03 110670-01 111826-01 108981-09 111874-05 111659-07 111596-02 109667-04 110957-02 111626-03 111085-02 108919-15 110838-05 112254-01 112459-01 111879-01 112611-01 112425-01 112668-01 111958-02 112796-01 112846-01 112279-02 109793-12 108806-12 110842-08 111321-03 109328-03 111310-01 Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 609 109223-02 111098-01 111327-05 108974-25 108977-01 110386-02 108528-17 109805-12 108989-02 108827-34 108993-11 109657-08 110723-05 110460-23 109888-15 108727-19 108725-11 109318-28 108985-03 109885-09 109238-02 112237-06 109234-09 111299-04 109134-27 108968-07 108997-03 108975-06 109007-07 Verify that the required patches are installed by entering the following command: # showrev -p | grep Where without the - as listed above must be included. For example: # showrev -p | grep 108940 Appendix B, “Solaris tips” on page 969 describes detailed steps to download and install Solaris recommended patches. 610 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 17.3 Web Server node implementation This section provides detailed instructions on how to install, configure, and verify the iPlanet Web Server on a separate node than WebSphere Commerce node. In our scenario, the host name is sun1. The iPlanet Web Server installation is organized into the following phases: Pre-installation tasks for the iPlanet Web Server Installing the iPlanet Web Server Enabling SSL for the iPlanet Web Server Disabling the iPlanet servlet engine Verifying the Sun ONE Web Server installation Installing the WebSphere plug-in Verifying the WebSphere plug-in Note: The iPlanet Web Server has been renamed to Sun ONE Enterprise Web Server. Many of the documents that we reference still refer to the iPlanet Web Server. You will find references to both in this section. More detailed information on iPlanet Web Server 6.0, Enterprise Edition installation can be found at: http://docs.sun.com/db/coll/S1_ipwebsrvree60_en The iPlanet Web Server 6.0 release notes can be found at: http://docs.sun.com/db/coll/S1_ipwebsrvree60_en 17.3.1 Pre-installation tasks for the iPlanet Web Server Before starting the iPlanet Web Server installation, complete the following tasks: Determine the host name and IP address of your system. For example: Hostname: sun1.itso.ral.ibm.com IP Address: 9.24.105.46 Determine whether the server needs a DNS alias. You may wish to establish a DNS alias that points to the Web server machine. If a DNS alias will be needed, create it. In our example, we do not create a DNS alias. Ensure that you choose unique port numbers; you need one for the Administration Server and one for each instance of iPlanet Web Server. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 611 The standard Web Server port number is 80 and the standard SSL-enabled Web Server port number is 443, but you can install iPlanet Web Server to use any port. For security reasons, choose a random number for the Administration Server port. Make sure, however, that the ports you choose are not currently in use by another service (check /etc/services file). Note: If you choose a server port number lower than 1024, you must be logged in as root to start the server. After the server binds to the port, the server changes from the root user account to the user account you specify. If you choose a port number higher than 1024, you don't have to be the root user to start the server. Ensure that you are using Netscape Navigator V4.76 or higher. The iPlanet Web Server requires the browser for administration. If you are using Solaris 8, most likely this will be installed by default. Create a UNIX user account for iPlanet Web Server. This account should have restricted access to your system resources for security reasons. The account needs read permissions for the configuration files and write permissions for the logs directory. The user should not have write permissions to some of the configuration files, although access control files, for example, should be group writable. Therefore, make sure you perform the following steps as the root user in the Solaris Console: # groupadd iplanet # useradd -g iplanet -d /export/home/iplanet -m -s /usr/bin/ksh iplanet # passwd iplanet After the last command, you will be prompted for a password for this user; enter one and re-enter to confirm. Note: It may be useful to download the gzip utility for decompressing files for some of the steps. You can download it from: http://www.sunfreeware.com 17.3.2 Installing the iPlanet Web Server To install the iPlanet Web Server (SP4), complete the following steps: 1. Start the Solaris Console and log in as root. 2. Insert the iPlanet Web Server 6.0 CD in the CD-ROM drive. a. Copy the iPlanet Web Server .tar file to a temp directory on your system: # mkdir -p /opt/ip6 # cd /cdrom/solaris/enterprise 612 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide # cp enterprise.tar /opt/ip6 b. Unmount the CD-ROM drive and remove the iPlanet Web Server 6.0 CD. c. Extract the files from the .tar file: # cd /opt/ip6 # tar -xvf enterprise.tar Note: Alternatively, you can download an evaluation copy of the iPlanet Web Server 6.0 at: http://wwws.sun.com/software/download/products/3e3add06.html 3. Start the iPlanet Web Server installation from the installation directory with the following command: # ./setup Note: The following tips are used for navigation during the install: Press Enter to choose the default and go to the next window. Press Ctrl+B to return to the previous window. Press Ctrl+C to cancel the installation program. You can enter multiple items using commas to separate them, for example 1,2,3. 4. When you are prompted with the message “Would you like to continue with the installation [Yes]” enter y or press Enter (to accept Yes as the default). 5. When you are prompted with the message “Do you agree to license terms?” enter y or Yes, and then press Enter. 6. When you are prompted with the message “Choose the installation type [2]” enter 2 or press Enter (to accept a Typical installation as the default). 7. When you are prompted with the message “Install location [/usr/iplanet/servers]” press Enter (to accept the default /usr/iplanet/servers). 8. When you are prompted with the message “Specify the components you wish to install [All]” press a or Enter (to accept All as the default). 9. When you are prompted with the message “Specify the components you wish to install [1,2,3,4,5]” type 1,2,3,4,5 and then press Enter. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 613 Note: The following components are required by WebSphere Commerce: Server Core - component 1 Java Runtime Environment - component 2 Java Support - component 3 Search and Indexing Support - component 4 SNMP Support - component 5 10.When you are prompted with the message “Computer name [your_hostname.domain]” enter and press Enter (for example, we entered sun1.itso.ral.ibm.com). 11.When you are prompted with the message “System User [nobody]”, type the user created in the pre-installation steps (for example, iplanet), and then press Enter. 12.When you are prompted with the message “System Group [nobody]”, type the group created in the pre-installation steps (for example, iplanet), and then press Enter. 13.When you are prompted with the message “Run iWS Administration Server as [root]”, press Enter (to accept root as the default). Note: We do not recommend that you leave this server running. Only start when needed on a production system. 14.When you are prompted with the message “iWS Administration Server User Name [admin]”, press Enter (to accept admin as the default). You will be prompted for a password. Enter a password and re-enter to confirm. 15.When you are prompted with the “message iWS Admin Server Port [8888]”, press Enter (to accept 8888 as the default). Note: When using the Adminstration Server on a production system, we recommend that you use a different port other than the default port. 16.When you are prompted with the message "Web Server Port [80]”, press Enter (to accept 80 as the default). 17.When you are prompted with the message "Web Server Content Root [/usr/iplanet/servers/docs]” press Enter (to accept /usr/iplanet/servers/docs as the default). 18.When you are prompted with the message "Do you want to use your own JDK [No]” press Enter (to accept No as the default). 614 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 19.Review messages to make sure everything was extracted and installed successfully. Press Enter to return to the command prompt. 17.3.3 Enabling SSL for the iPlanet Web Server This section provides detailed instructions for requesting a certificate, installing the certificate and configuring an iPlanet Web Server for SSL. In our example, we will request a test certificate from VeriSign. For a production environment, you will need a real certificate. The iPlanet Web Server SSL enablement is organized into the following sections: Starting the iPlanet Web Server Administration Server Creating ports for WebSphere Commerce Creating a certificate trust database Requesting a server certificate Installing the server certificate Starting the iPlanet Web Server Administration Server To start the iPlanet Web Server Administration Server, complete the following steps: 1. Type the following commands in the Solaris Console as a root: # cd /usr/iplanet/servers # ./startconsole 2. When the Netscape browser opens and the Login window appears, enter the following (admin is the iWS Administration Server user created during the installation steps above): – User ID: admin – Password: Tip: You can access the Web server administration server from another computer at the following: http://:8888/https-adminserv/bin/index This should only be used if you do not have a Web browser on the Web Server node. Creating ports for WebSphere Commerce Before creating listener sockets for WebSphere Commerce ports, we need to create an instance of the Web Server. Once the Web Server is created, you can configure required ports for WebSphere Commerce. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 615 Tip: The following ports are required: – – – – – – – 80 for non-secure interaction 443 for secure interaction 8000 for WebSphere Commerce Tools 8002 for WebSphere Commerce Administration 8004 for WebSphere Commerce Organization Administration 5432 for WebSphere Commerce Payment non-secure server 5433 for WebSphere Commerce Payment secure server Create server instance To create a server instance, complete the following steps: Note: The iPlanet Web Server installation may have already created a server instance. If a server with your fully qualified host name (for example, sun1.itso.ral.ibm.com) already exists, skip the next three steps. 1. From the iPlanet Web Server 6.0 Administration Server, select the Servers tab. 2. Click Add Server in the left navigation pane. 3. When the Add Server window appears, enter the following information and then click OK. – Server Name: For example, sun1.itso.ral.ibm.com – Server Port: For example,we entered port 80 (HTTP Web server). – Server Identifier: For example, we entered sun1.itso.ral.ibm.com. – Server User: Enter the user that you created for the Web server (for example, iplanet). – MTA Host: localhost Accept the default of localhost. – Select Never attempt to resolve IP addresses into hostnames (the default). – In the Document Root field, accept the default, which will be the document root that you specified during installation, for example /usr/iplanet/servers/docs, and click OK. 616 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Configure ports for server To configure the ports for the server, complete the following steps: 1. From the iPlanet Web Server 6.0 Administration Server, select the Servers tab. 2. Select your server from the list and click Manage. 3. Select the Preferences tab. 4. Click Add Listen Socket on the left-hand pane and enter the following: a. ID: enter ls Usual convention is followed by port number. For example, choose ls443 for port 443. b. IP: 0.0.0.0 Usually 0.0.0.0 value is chosen for IP, as it means the server can listen on all IP addresses. c. Port: port number Enter the port number you are configuring. d. Servername: Web Server host name This is the fully qualified host name for the Web Server node. For example, we entered sun1.itso.ral.ibm.com. e. Security: On for secure ports and Off for non-secure ports. This option enables or disables the use of Secure Socket Layer (SSL) for the specified ports. Ports 80 and 5432 are non-secure ports. Ports 443, 5433, 8000, 8002 and 8004 are secured ports. f. Default VS: Select the default value. This field indicates which Virtual Server will handle a request g. Click OK. 5. Repeat this process until all the required ports are created (80, 443, 5432, 5433, 8000, 8002, 8004). Note: You may get a security warning when you click Submit. Click Continue Submission. If your Web browser is not set to accept cookies automatically (default), you will get warnings on incoming cookies. Click OK to continue. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 617 Creating a certificate trust database A certificate database is a key-pair and database installed on the local host. Each Web server instance has its own certificate key pair referred to as a trust database. In our scenario, we will need to create a certificate trust databases as we have only one server instance. To create the certificate trust database needed for SSL-enabled server, complete the following steps: 1. From the Manage Server window, select the sun1.itso.ral.ibm.com server from the Select a Server pull-down menu, and then click Manage. 2. Click the Security tab from the top of the page. 3. Click the Create Database link from the left-hand side of the page. 4. Enter the database password. 5. Click OK. 6. A pop-up window should appear, indicating that a database was successfully created. Requesting a server certificate For an SSL server, you have to request a server certificate for the server instance. Perform the following steps to generate a certificate request: 1. From the iPlanet Web Server Adminstration Server, select the Servers tab. Select your server from the list and click Manage. Select the Security tab. 2. Click the Request a Certificate link in the left navigation pane. 3. When the Request a Server certificate window appears, do the following and click OK to request the certificate. The certificate will be e-mailed to you. – Select the New Certificate radio button. – In the CA-email address field, enter your e-mail address. – Select Internal from the Cryptographic module pull-down. – In the Key Pair File Password field, enter your Certificate Trust database password as previously created. – In the Common Name field, enter the URL by which your host will be known. This is normally the fully qualified host name, for example sun1.itso.ral.ibm.com. – In the remaining fields, fully enter your contact information. 4. The next window will inform you that your request has been sent. Take note of the file name specified by the message “A copy of the certificate request has been saved in the file: ”. 618 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 5. Proceed to a Certificate Authority Web site to submit your request. Follow the instructions provided there for the completion of your request. Note: Most certificate sites will allow you to generate a test certificate for use on non-production servers, for example, a VeriSign Free Trial SSL ID can be found at: http://www.verisign.com/products/site/index.html Once you have submitted the request (request file created in the previous step), after a short period you should receive an e-mail with a test certificate from VeriSign. Be aware that the test certificate is valid for 14 days only. When you receive the certificate, cut and paste the lines including beginning and ending text to a file and copy it to the iPlanet Web Server 6.0 in preparation for installing the certificate. -----BEGIN CERTIFICATE---------END CERTIFICATE----- You will see many characters in between the begin and end certificate statements. This is what makes the certificate unique. Installing the server certificate When you receive the certificate, you have to install it on each SSL server. Perform the following steps: 1. From the Server Manager pull-down menu, select the server you want to configure (for example, sun1.itso.ral.ibm.com). Click Manage. 2. Click the Security tab. 3. Click the Install Certificate to install your new certificate. 4. When the Install a Server Certificate window appears, do the following and then click OK. – – – – – – Certificate For: Select This Server Cryptographic Module: Select Internal Key Pair File Password: Certificate Name: Leave this field blank Select the Message Text radio button. Paste the certificate sent to you by the Certificate Authority into the Message Text area. Note: Alternatively, you can save the certificate to a file, and specify that the file name in the Message is in this file entry. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 619 5. When the Add Server Certificate window appears, take note of the information provided (for example, Certificate Name: Server-Cert) and click Add Server Certificate. You should see a Success window pop-up, as well as a window warning you that the server will need to be restarted for the security changes to take effect. Now you can turn on the SSL encryption for the secured ports. 17.3.4 Disabling the iPlanet servlet engine By default, Java is globally enabled and enabled for each virtual server. Follow these steps to disable the iPlanet servlet engine: 1. In the Select a Server Manager pull-down menu, select the server you want to configure. For example, we selected sun1.itso.ibm.com server instance. 2. Click Manage. 3. Select the Java tab. 4. Then select Enable/Disable Servlets/JSP from the left pane. 5. Uncheck the Enable Java Globally check box. 6. Click OK. 7. Restart the Web server. 17.3.5 Verifying the Sun ONE Web Server installation To test that Sun ONE Web Server is working properly, perform the following steps: 1. Enter the URL in a browser to access the Administration Server: http://:8888/https-admserv/bin/index Note: Every manual change to iPlanet Web Server opt.conf configuration file have to be applied and the new opt.conf loaded. By clicking Server On and Server Off buttons (start and stop server), you get the following message: WARNING: The configuration files have been edited by hand. If you wish to keep the changes to opt.conf (for example after installing the iPlanet Web Server WebSphere Application Server plug-in, you do wish to keep the changes), click the Load Configuration Files and Apply in the upper-right corner. 2. To verify the HTTP server, from the Server Manager pull-down menu, select your HTTP server, for example sun1.itso.ral.ibm.com, and click Manage. 620 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide The server status is displayed with a message: “The server is currently on or The server is currently off”. 3. If the server is off, enter the Certificate Trust database password and click Server On to start the server, and vice versa. 4. Verify that the server is On and access the server from a browser client, by entering the following URLs: http://:80 http://:5432 https://:443 https://:5433 https://:8000 https://:8002 https://:8004 Note: When using a secure address (HTTPS), You may get the following Netscape error: “Netscape and this server cannot communicate securely because they have not common algorithm(s)”. This error occurs because a browser with 128-bit encryption is required to test secure connections in US. Either download and install a browser with 128-bit encryption, or test from another computer that has 128-bit encryption. 17.3.6 Installing the WebSphere plug-in To install the WebSphere Application Server V5.0 plug-in for your iPlanet Web Server, complete the following steps: 1. Start the Solaris Console as root. 2. Ensure that all the iPlanet Web Server instances is stopped. For example, sun1.itso.ral.ibm.com. Tip: To stop the iPlanet Web server processes, issue the following command for the server from the Solaris Console as root: # /usr/iplanet/servers/https-sun1.itso.ral.ibm.com/stop Alternatively, you can use iPlanet Web Server Administrative Server Console to stop the server. 3. Insert the WebSphere Application Server V5.0 CD in the CD-ROM drive. 4. Type the following command to start the installation program: # cd /cdrom/sun # ./install Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 621 5. When the Installation Wizard window appears, choose the preferred language to be used by the Installation wizard. For example, we accepted default value of English. click OK. 6. When the Welcome to the IBM WebSphere Application Server, Version 5 Installation Wizard window appears, click Next to continue. 7. When the Software License Agreement window appears, read the agreement and choose the option to indicate you do accept the license agreement. Then click Next to continue. 8. When the Install Options window appears, select Custom and then click Next. 9. When the Select the features for IBM WebSphere Application Server, Version 5 window appears, deselect all features except Web Server Plugins and iPlanet Web Server and then click Next. 10.When Select Destination Directory window, accept the default (/opt/WebSphere/AppServer) and then click Next. 11.When the Location of Configuration Files window appears, enter the path to iPlanet Web Server configuration file. Alternatively, use the Browse button to select the correct path and obj.conf. Click Next. For example: /usr/iplanet/servers/https-sun1.itso.ral.ibm.com/config/obj.conf Note: Refer to WebSphere Application Server, V5 InfoCenter for details on what is added to the obj.conf for the WebSphere iPlanet 6 plug-in: http://publib7b.boulder.ibm.com/webapp/wasinfo1/index.jsp?deployment=A pplicationServer&lang=en 12.When the Installation Summary window appears, click Next. 13.When the Installation Completed window appears, click Finish. 14.Unmount the CD-ROM drive and remove the WebSphere Application Server V5.0.1 CD. 15.Restart the Web server instance. 17.3.7 Verifying the WebSphere plug-in After the installation of WebSphere Application Server inspect the two files, obj.conf and magnus.conf, to verify that the plug-in is correctly configured. 622 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide The following are the steps for plug-in verification: 1. View obj.conf for your server instance. Just after the following line is present: Service fn=“a_handler” For example, obj.conf is located at /usr/iplanet/servers/https-sun1.itso.ral.ibm.com/config/obj.conf. 2. View magnus.conf for your server instance. The following two directives should be present at the end of the file: Init fn="load-modules" funcs="as_init,as_handler,as_term" shlib="/opt/WebSphere/AppServer/bin/libns41_http.so" Init fn="as_init" bootstrap.properties="/opt/WebSphere/AppServer/config/cells/plugin-cfg.xml" 17.4 Database Server node implementation This section provides detailed instructions for installing and configuring the Oracle 9i (9.2.0.1.0) Enterprise Edition for Sun SPARC Solaris on the Database Server node. The Oracle 9i database server installation consists of the following phases: Oracle9i installation prerequisites Installing Oracle9i Enterprise Edition (server installation) Preparing the database for WebSphere Commerce Note: More information on the Oracle9i installation, can be found at: http://docs.oracle.com/database_mp_9i_sun_sparc.html The HTML and PDF versions of the installation guide for Oracle Database 9i (9.2.0) for Sun SPARC Solaris can be found at: http://otn.oracle.com/documentation/oracle9i.html 17.4.1 Oracle9i installation prerequisites Before the installation of Oracle9i, the following tasks need to be completed: Hardware requirements Solaris 8 required patches for Oracle9i Solaris 8 required packages for Oracle9i Configuring the UNIX Kernel for Oracle9i Creating groups Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 623 Creating a user account for Oracle9i Setting environment variables in the user .profile Creating mount points Hardware requirements To install Oracle9i products, your system must meet the minimum following hardware requirements: Memory A minimum of 512 MB of Random Access Memory (RAM) is required to install Oracle9i Server. A minimum of 521 MB of RAM is required to install Oracle9i Management and Infrastructure. A minimum of 256 MB is required to install Oracle9i Client. To determine the amount of RAM installed on your system, enter the following command: /usr/sbin/prtconf grep “Memory Size” Swap space Disk space equal to the system’s physical memory, or 1 GB, whichever is greater. To determine the amount of swap space currently configured in your system, enter the following command: /usr/sbin/swap -l From the output of the command, divide the value shown in the BLOCKS column by 2 to obtain the swap space. CR-ROM device A CR-ROM drive capable of reading ISO 9660 format CR-ROM disks with RockRidge extensions. Disk Space The following disk space requirements are approximate as it might vary slightly at installation time. – Database software => 3.5 GB – Seed database => 1GB – Temporary disk space required by the Oracle Universal Installer The Oracle Universal Installer requires up to 400 MB of space in the /tmp directory. If you do not have enough space in the /tmp directory, set the TMPDIR and TMP environment variables to specify a directory with sufficient space. 624 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Solaris 8 required patches for Oracle9i There are no specific patches identified for Oracle9i. You can determine the patches installed by entering the following command: showrev -p Solaris 8 required packages for Oracle9i When installing Solaris 8, we chose a Developers distribution, which includes the following packages required for Oracle9i: SUNWarc SUNWbtool SUNWhea SUNWlibm SUNWlibms SUNWsprot SUNWtoo To verify operating system packages, enter the following: # pkginfo For example: # pkginfo SUNWarc system SUNWarc Archive Libraries Configuring the UNIX Kernel for Oracle9i Configure the UNIX Kernel Interprocess Communication (IPC) parameters to accommodate the System Global Area (SGA) structure of Oracle9i. You will not be able to start up the database if the system does not have adequate shared memory to accommodate the SGA. Also by maintaining data in memory, the UNIX kernel reduces disk I/O activity. To update the UNIX Kernel for Oracle9i, do the following: 1. Start a Solaris Console logged in as root. 2. Back up the original system file containing the Solaris Kernel parameters: # cd /etc # cp system system.org 3. In our scenario, we added the following Kernel parameters to the end of the /etc/system file to configure the Solaris Kernel for the Oracle9i: set set set set semsys:seminfo_semmni=100 semsys:seminfo_semmns=1024 semsys:seminfo_semmsl=256 shmsys:shminfo_shmmax=4294967295 Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 625 set shmsys:shminfo_shmmin=1 set shmsys:shminfo_shmmni=100 set shmsys:shminfo_shmseg=10 4. The Solaris system needs to be restarted for the Kernel shared memory and semaphore parameters to take effect. # shutdown -i6 -g0 -y Note: For more detailed information on Solaris Kernel settings for Oracle9i, refer to the following: Installation Guide, Oracle9i Release 2, May 2002, A96167-01 Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems Creating groups Depending on the size and makeup of your organization, you may have several roles defined for the database administrator. The Installation Guide, Oracle9i Release 2, May 2002, A96167-01 recommends the following groups. Table 17-8 Recommended groups for Oracle9i Role of Oracle9i group Suggested group name Database administrator - OSDBA dba Database operator - OSOPER oper Oracle installer group - ORAINVENTORY oinstall In our scenario, we created groups called dba, oper, and oinstall as follows: 1. Start a Solaris Console logged in as root. 2. Create the groups dba, oper and oinstall as follows: # groupadd dba # groupadd oper # groupadd oinstall 626 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: Alternatively, use the Solaris Admintool to create groups and users. Start the Solaris Admintool by entering the following from a Console command line as user root: # admintool When the Admintool:Users window appears, select Browse -> Groups from the menu bar. From the Admintool:Groups window, select Edit-> Add from the menu bar. In the Admintool:Add Group window, enter dba for the group name and click OK. Repeat for groups oper and oinstall. Creating a user account for Oracle9i To create a user named oracle and make the user a member of the dba and oinstall group, do the following: 1. Start a Solaris Console logged in as root. 2. Start the Solaris Admintool by entering the following from a Console command line while logged in as user root: # admintool 3. When the Admintool:Users window appears, click Edit -> Add. 4. When the Admintool: Add User window appears, enter the following and then click OK: – – – – – User Name: oracle Primary Group: oinstall Secondary Groups: dba Login Shell: Select Korn Select Password -> Normal Password. Enter your password and click OK. – Ensure that the radio button Create Home Dir field is selected. – Path: /export/home/oracle (home directory for oracle user). – Accept the default values for the other fields. 5. Exit the admintool utility. Note: As an alternative to using the Admintool to create users, you can add users via the command line as follows: # useradd -g oinstall -G dba -d /export/home/oracle -m -s /usr/bin/ksh oracle Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 627 6. Set the password for the oracle user. # passwd oracle This will prompt you to set the new password. 7. Log in with user oracle to verify the password and account: # su - oracle $ su - oracle This time you will be prompted to enter the password. 8. Enter the following to verify that the path is set to /export/home/oracle. $ pwd /export/home/oracle $ exit $ exit Setting environment variables in the user .profile It is necessary to set the DISPLAY and PATH environment variables before the Oracle Universal Installer. To set the environment variables as part of the .profile for the oracle user shell, do the following: 1. Log in as user oracle: # su - oracle 2. We added the following environment variables to the oracle user .profile: umask 022 export ORACLE_BASE=/opt/oracle/u01/app/oracle export ORACLE_HOME=$ORACLE_BASE/product/9.2.0 export ORACLE_SID=o920 export PATH=$PATH:$ORACLE_HOME/bin:/usr/ccs/bin:/usr/openwin/bin export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib export CLASSPATH=$CLASSPATH:$ORACLE_HOME/jdbc/lib/classes12.zip Note: For detailed information on the environment variables, refer to the Installation Guide, Oracle9i Release 2, May 2002, A96167-01. Tip: You can add the following optional lines (or your preferred variations) for your own convenience to the end of /export/home/oracle/.profile: set -o vi alias 'dir=ls -Fal' export PS1=`hostname`':$LOGNAME:$PWD$ ' 628 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Creating mount points Oracle9i needs at least four mount points when creating an Optimal Flexible Architecture (OFA)-compliant installation: one for the software and at least three for the database files. To create the mount points, do the following: 1. Start a Solaris Console, logged in as user root. 2. Create the following mount point used for the Oracle9i software: # mkdir -p /opt/oracle/u01 3. Create the following mount points used for the Oracle9i databases: # cd /opt/oracle # mkdir u02 u03 u04 4. Change the ownership of the Oracle9i root directory as follows: # chown -R oracle:dba /opt/oracle 5. Change the permissions: # chmod -R g+w /opt/oracle 17.4.2 Installing Oracle9i Enterprise Edition (server installation) Oracle9i is installed on node C within our scenario. To install the Oracle9i Enterprise Edition (database server) installation, complete the following steps: 1. Start a Solaris Console logged in as user root. 2. Insert the Oracle9i Enterprise Edition CD 1 in the CD-ROM drive. The OS usually mounts the CD-ROM for you to /cdrom/cdrom0. Otherwise, you will have to mount the CD manually. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 629 Note: If you are using local filesystem to install Oracle: You don’t need to mount CD-ROM. We downloaded Oracle zipped files. After the zipped files are downloaded, do the following: a. Unzip the files. b. Create a folder for each zip file. For example, we created the following folders: # mkdir Disk1 # mkdir Disk2 # mkdir Disk3 c. Change directory to Disk1: # cd Disk1 d. Extract disk1.cpio file to Disk1 folder: # cat .cpio | cpio -icd e. Repeat steps c and d for disk2 and disk 3 cpio files. 3. Before running the Oracle Universal Installer, you will need to set the DISPLAY variable. The following commands set the variable for the oracle user: a. As root, you might need to add the host name of your workstation machine to xhost access control list (xhost command located in /usr/openwin/bin): # xhost + b. Check the DISPLAY variable: # echo $DISPLAY Note: You should see output similar to :0.0. c. Change the user account to oracle: # su - oracle d. Export the DISPLAY variable with the fully qualified host name of your workstation machine: $ export DISPLAY=:0.0 For example: $ export DISPLAY=sun3.itso.ral.ibm.com:0.0 After this command, the DISPLAY value will only be known to the current Solaris Console. 630 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide e. If XWindows is working properly, a clock will appear on your screen when you enter the following command: # xclock f. Close the xclock application. 4. While still logged in as user oracle, change the Oracle9i directory and run the installer as follows: # cd / # /cdrom/cdrom0/runInstaller& Note: If you are using local filesystem to install Oracle Change to Disk1 folder $ cd /Disk1 Run the installer program by typing the following command: $ ./runInstaller 5. When Oracle Universal Installer 2.2 Welcome window opens, click Next. 6. When the Inventory Location window opens, enter the path you would like to use and click OK. We accepted the default values. 7. When prompted for the UNIX Group name, enter oinstall and click Next. 8. A message appears stating that “Certain actions have to be performed with root privileges before the install can continue”. When prompted, open a console window, ensure you are running as root user, and run /tmp/orainstRoot.sh. 9. When the script has finished running, return to the installer window and click Next. 10.When the File Locations window appears, verify that the paths are correct and then click Next, for example: – Source: /cdrom/orcl920/stage/products.jar, or /opt/oracle9i/Disk1install/stage/products.jar (when using file system) – Destination: /opt/oracle/u01/app/oracle/product/9.2.0 Note: The destination file location need to be the same as defined in the pre-installation steps, where the environment variables for the oracle user (ORACLE_HOME) have been set (see “Setting environment variables in the user .profile” on page 628). 11.When the Available Products window appears, select Oracle9i Database 9.2.0.1.0, and then click Next. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 631 12.When the Installation Types window appears, select Custom and then click Next. 13.When the Available Product Components window appears, we selected the following options and then clicked Next: – Under Oracle 9i Database 9.2.0.1.0 >> Enterprise Edition Options 9.2.0.1.0, deselect the following: • • • • Oracle Advanced Security 9.2.0.1.0 Oracle Partitioning 9.2.0.1.0 Oracle Spatial 9.2.0.1.0 Legato Network Single Server 6.1.0.0.0 – Under Oracle 9i Database 9.2.0.1.0, deselect the following: • • • • Oracle Enterprise Manager Products 9.2.0.1.0 Oracle 9i Development Kit 9.2.0.1.0 Oracle HTTP Server 9.2.0.1.0 Oracle Transparent Gateways 9.2.0.1.0 Note: Refer to the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems for a listing of the required options for a custom installation. 14.When the Component Locations window appears, accept the defaults and click Next. 15.When the Privileged Operating System Groups window appears, click Next to accept the default group of dba. 16.At the Create Database window, select No and click Next. Note: We will create databases and table spaces for the WebSphere Commerce instance and Payment instance using the Oracle Database Configuration Assistant and WebSphere Commerce instance creation process. 17.When the Summary window appears, review the selections and then click Install. During the installation, you will be prompted to insert CD 2 and 3. When prompted to insert another CD, run the following commands from a Console: # umount /cdrom/cdrom0 # eject Remove the CD and insert the new one. Specify the path to /cdrom/cdrom0 and click OK. The installation takes approximately 30 minutes. 632 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: If you are using filesystem for installation you will not be prompted for CDs. For example, we used local filesystem folder, Disk1 for installation initiatiation, Disk2 and Disk3 folders were read implicitly by the installer. You may see error messages in the Console from which you invoked the installer. You can ignore these messages. 18.At the end of the installation, a Setup Privileges window may appear with a message stating “A configuration script needs to be run as root before installation can proceed. Please leave this window up, go run /opt/oracle/u01/app/oracle/product/9.2.0/root.sh as root”. When prompted for the full path name of the local bin directory, specify /usr/local/bin and click OK. The following environment variables are set: ORACLE_OWNER= oracle ORACLE_HOME= /opt/oracle/u01/app/oracle/product/9.2.0 The usr/local/bin directory is created if necessary, and several files are copied to this directory. The /var/opt/oracle/oratab file is also updated. If you see a warning stating “chmod: WARNING: can’t access opt/oracle/u01/app/oracle/product/9.2.0/network/agent/html”, ignore it. 19.After running the script, click OK in the Setup Privilege window. 20.At the end of the Oracle Universal Installer, Oracle9i Enterprise Edition installation, the Oracle Net Configuration Assistant is started automatically. The Oracle Net Configuration Assistant is used to configure the directory usage configuration, listener configuration, and naming methods configuration. 21.When the Oracle Net Configuration Assistant: Welcome window appears, click Next. 22.When the Directory Usage Configuration window appears, check the option of No to complete the configuration later. Click Next. 23.When the Listener Configuration window appears, accept the default listener name, LISTENER. Click Next. 24.When the Protocol selection window appears, make sure TCP is in the selected Protocols list. Click Next. 25.When the TCP/IP port setup window appears, select the option to use the standard port number of 1521. Click Next. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 633 26.When the window for configuration of another listener appears, choose No. Click Next. 27.When the listener configuration completed window appears, click Next. 28.When Naming Methods Configuration window appears, select the option of not changing the naming methods. Click Next. Note: By default the local naming methods, tnsnames.ora file, is configured for functionality requiring the server to connect back to itself. In our case, this is suffice. You may need to configure additional naming methods if your server needs to connect to other servers, or if you are going to use your server as a client. 29.When Oracle Net Configuration completion message window appears, click Finish. 30.When the Configuration Tools status appears, click Next. 31.When the End of Installation window appears, click Exit to close the Oracle Universal Installer. Click Yes. 17.4.3 Preparing the database for WebSphere Commerce Prior to the installation of the WebSphere Application Server, WebSphere Commerce and WebSphere Commerce Payment, we need to create a database instance and prepare the database. In our scenario, we created one database (instance) for all applications. The database preparation is organized into the following sections: Creating an Oracle9i database Database tuning Oracle9i database verification Creating an Oracle9i database To create an Oracle9i database, complete the following steps on the Oracle9i Enterprise Edition database server (for example, Oracle9i is installed on Node C-sun3, in our scenario): 1. Start a Solaris Console, and log in as user oracle: # su - oracle 634 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 2. Start the Oracle Database Configuration Assistant as follows: $ dbca Note: You may need to increase the Solaris Kernel settings found in /etc/system to run dbassist. This is dependent on system memory available and current settings for processes. Tip: If you get the error: “ORA-27102 Out of memory”. Check that the kernel setting for the shmsys:shminfo_shmmax is as described in the section. 3. When the Oracle Database Configuration Assistant welcome window appears, click Next. 4. At step 1 of 8, select Create a database and then click Next. 5. At step 2 of 8, ensure that New Database is selected and click Next. 6. At step 3 of 8, set Global database name to instancename.hostname.domain (for example, o920.sun3.itso.ral.ibm.com) and SID to o920. Click Next. 7. At step 4 of 8, deselect Example Schemas, selecting Yes when prompted to delete the table space. Deselect Oracle OLAP Services, selecting Yes when prompted to delete table space. Deselect Oracle Ultra Search. Click Standard database features and deselect Oracle JVM. Click OK. Click Next. 8. At step 5 of 8, select Dedicated Server Mode as the server mode and then click Next. Note: We selected the Dedicated Server Mode, since Oracle recommends using this mode when the number of client connections is expected to be small or when clients will be making persistent, long-running requests to the database. You may decide to select Shared Server Mode, if your requirement dictates so. 9. At step 6 of 8, on the Memory tab, set Shared pool to 120 MB, Buffer Cache to 120 MB, PGA to 50 MB. On the Character Sets tab, set the Database character set and the National Character Set to UTF8. On the DB Sizing tab, set the Block Size to 4 KB and Sort Area Size to 655350 bytes. Click Next. Note: The values set in the tabs are as per recommended database parameter settings to use when using Oracle9i with WebSphere Commerce. The values are specified in Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 635 10.At step 7 of 8, ensure that all the values are appropriate for your system and click Next. 11.At step 8 of 8, ensure that Create Database is selected and click Finish. 12.A summary window displays. Click OK. The database creation may take from 30 to 70 minutes. 13.A window displays stating that the database creation is complete and details for sys and system users, including default passwords. Click Exit. Note: More details about the database creation can be found in the log files under /opt/oracle/u01/app/oracle/admin/o920/create. Important: If you click Password Management you will be able to change passwords, lock and unlock user accounts, and create new accounts. We strongly recommend that you change the sys and system passwords immediately. Database tuning This section describes how to perform the recommended database tuning for the Oracle9i wc database (instance). 1. Start a Console window and log in as user oracle. # su - oracle 2. The Oracle Database Creation Assistant creates the following initialization file: $ORACLE_HOME/dbs/spfile.ora Modify the parameters in Table 17-9 on page 637. The parameters file cannot be changed directly and must be changed through sqlplus. The command in sqlplus is: alter system set = Following is an example of how we accomplished it: # su - oracle $ sqlplus Enter user-name: sys as sysdba Enter password: alter system set shared_pool_size=120000000 alter system set open_cursors=1000 quit To validate that the parameters have been updated, in sqlplus, you can issue the show parameters command to see the values. 636 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: The value for shared_pool_size gets round up to the next megabyte boundary. For some reason, any value between about 118000000 and 134000000 keeps getting rounded to 134217728. Default parameter value after database creation can be viewed from within the sqlplus using the following command: SQL> show parameters Table 17-9 Oracle9i database recommended tuning parameters for WebSphere Commerce WC5.5 recommended values Parameter Default parameter value after database creation shared_pool_size 134217728 120000000 processes 150 150 db_block_size 4096 4096 open_cursors 300 1000 3. Stop and start the Oracle9i Enterprise Edition for the database tuning changes to take effect: # su - oracle $ dbshut $ dbstart Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 637 Note: The Oracle9i dbshut and dbstart scripts will stop and start all databases. This behavior is desired in this example, but may not be appropriate in other situations. Using sqlplus is another option for stopping and starting the databases. Restart the database instance, for the changes to take effect. To stop an oracle instance: # su - oracle $ sqlplus Enter user-name: sys as sysdba Enter password: SQL > shutdown SQL > quit And to start an oracle instance: # su - oracle $ sqlplus/nolog SQL > startup; SQL > exit 4. If your Oracle9i Enterprise Edition does not start, check the tuning parameters entered for errors. Changing the tuning values beyond the physical memory available on the system will result in the database server not starting. Oracle9i database verification After the database creation, we recommend that you take some steps to verify that the Oracle9i Enterprise Edition is working correctly before attempting to configure a database client for remote connectivity on nodes with WebSphere Commerce servers. To verify the Oracle9i Enterprise Edition installation, complete the following steps: 1. Start the Console and log in as user oracle. # su - oracle 638 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 2. To start an Oracle command window, type the following: > sqlplus system/@ For example: $ sqlplus system/manager@o920 SQL> quit Tips: When the typical configuration is performed, Oracle will take the global database name as the service name. You can change it to be the same as the SID. To do this, perform the following steps: 1. Start the Console and log in as the Oracle user: # su - oracle 2. Start Oracle Net Manager: $ netmgr & 3. Expand Oracle Net Configuration-> Local -> Service Naming and select the service name for the instance. For example: o920.sun3.itso.ral.ibm.com 4. Select Edit -> Rename. 5. In the Enter name window, use a simple name, for example, SID o920 and click OK. 6. Save the Network Configuration and exit. If LANG on your Oracle server or client is set to a value such as LANG=C, you may not be able to start sqlplus. 1. Add the following line to /export/home/oracle/.profile: export LANG= 2. Reload .profile: .profile 17.5 WebSphere Commerce node implementation This section describes the procedures we used to implement the WebSphere Commerce node, including the following: Oracle9i client installation WebSphere Commerce installation Create users and groups Installing the remaining WebSphere Commerce components WebSphere Commerce instance creation Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 639 WebSphere Commerce post-instance config Creating a WebSphere Commerce Payment instance WebSphere Commerce payment post-instance config Start/stop the WebSphere Commerce instance Regenerating Web server plug-in configurations iPlanet Web Server configuration for WebSphere Commerce 17.5.1 Oracle9i client installation This section provides detailed instruction for installing and configuring the Oracle9i Client (9.2.0) for Sun SPARC Solaris on the WebSphere Commerce server system for a remote database configuration. Note: More detailed information on Oracle9i installation can be found at: http://docs.oracle.com/database_mp_9i.html The Oracle9i Client installation consists of the following phases: Prerequisites for the Oracle9i client installation Installing Oracle9i client Verifying the Oracle9i client installation Prerequisites for the Oracle9i client installation Before the installation of Oracle9i Client, complete the following tasks: Hardware requirements Creating groups Creating a user account for Oracle9i Setting environment variables in the user .profile Creating mount points For detailed information on performing the above tasks, refer to 17.4.1, “Oracle9i installation prerequisites” on page 623. Installing Oracle9i client To install Oracle9i Client on the WebSphere Commerce node, do the following: 1. Start a Solaris Console logged in as root. 2. Insert the Oracle9i Enterprise Edition CD 1 in the CD-ROM drive. The OS usually mounts the CD-ROM for you to /cdrom/cdrom0. 640 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: If you are using local filesystem to install Oracle: You don’t need to mount CD-ROM. We downloaded Oracle zipped files. After the zipped files are downloaded, do the following: a. Unzip the files. b. Create a folder for each zip file. For example, we created the following folders: # mkdir Disk1 # mkdir Disk2 # mkdir Disk3 c. Change directory to Disk1: # cd Disk1 d. Extract disk1.cpio file to Disk1 folder: # cat .cpio | cpio -icd e. Repeat steps c and d for disk2 and disk 3 cpio files. 3. Before running the Oracle Universal Installer, you will need to set the DISPLAY variable. The following commands set the variable for the oracle user: a. As root, you might need to add the host name of your workstation machine to xhost access control list (xhost command located in /usr/openwin/bin): # xhost + b. Check the DISPLAY variable: # echo $DISPLAY You should see output similar to :0.0. c. Change the user account to oracle: # su - oracle d. Export the DISPLAY variable with the fully qualified host name of your workstation machine: $ export DISPLAY=:0.0 For example: $ export DISPLAY=sun2.itso.ral.ibm.com:0.0 After this command, the DISPLAY value will only be known to the current Solaris Console. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 641 e. If XWindows is working properly, a clock will appear on your screen when you enter the following command: # xclock f. Close the xclock application. 4. While still logged in as user oracle, change the Oracle9i directory and run the installer as follows: # cd / # /cdrom/cdrom0/runInstaller& Note: If you are using local filesystem to install Oracle: – Change to Disk1 folder $ cd /Disk1 – Run the installer program by typing the following command: $ ./runInstaller 5. When the Oracle Universal Installer 2.2 Welcome window opens, click Next. 6. When Inventory Location window opens,enter the path you would like to use as the base directory and click OK. 7. When prompted for the UNIX Group name, enter oinstall and click Next. 8. A message appears stating that “Certain actions have to be performed with root privileges before the install can continue”. When prompted, open a Console window, ensure you are running as root user, and run /tmp/orainstRoot.sh. 9. When the script has finished running, return to the installer window and click Continue. 10.When the File Locations window appears, verify that the paths are correct and then click Next, for example: – Source: /cdrom/orcl920/stage/products.jar, or /opt/oracle9i/Disk1install/stage/products.jar (when using filesystem) – Destination: /opt/oracle/u01/app/oracle/product/9.2.0 Note: The destination file location needs to be the same as defined in the pre-installation steps, where the environment variables for the oracle user (ORACLE_HOME) have been set (see “Setting environment variables in the user .profile” on page 628). 11.When the Available Products window appears, select Oracle9i Client 9.2.0.1.0, and then click Next. 642 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 12.When the Installation Types window appears, select Custom and then click Next. 13.In the Available Components window, select the following components under Oracle 9i Client 9.2.0.1.0 (as required by the WebSphere Commerce V5.5) and click Next: – – – – – Oracle Enterprise Manager Products 9.2.0.1.0 SQL*Plus 9.2.0.1.0 Oracle JDBC/OCI Interfaces 9.2.0.1.0 Oracle JDBC/THIN Interfaces 9.2.0.1.0 Oracle Network Utilities 9.2.0.1.0 14.When the Component Locations window appears, accept the defaults and click Next. 15.When the Summary window appears, review the information and click Next. 16.At the end of the installation, a Setup Privileges window may appear with a message stating “A configuration script needs to be run as root before installation can proceed. Please leave this window up, go run /opt/oracle/u01/app/oracle/product/9.2.0/root.sh as root.” When prompted for the full path name of the local bin directory, specify /usr/local/bin and click OK. The following environment variables are set: ORACLE_OWNER= oracle ORACLE_HOME= /opt/oracle/u01/app/oracle/product/9.2.0 The usr/local/bin directory is created if necessary, and several files are copied to this directory. The /var/opt/oracle/oratab file is also updated. If you see a warning stating “chmod: WARNING: can’t access opt/oracle/u01/app/oracle/product/9.2.0/network/agent/html”, ignore it. 17.After running the script, click OK in the Setup Priviledge window. 18.At the end of the Oracle Universal Installer, Oracle9i Enterprise Edition installation, the Oracle Net Configuration Assistant is started automatically. The Oracle Net Configuration Assistant is used to configure the directory usage configuration, listener configuration, and naming methods configuration. 19.When the Oracle Net Configuration Assistant Welcome window appears, click Next. 20.When the Directory Usage Configuration window appears, check the option of No to complete the configuration later and click Next. 21.When Naming Methods Configuration window appears, select the Local, Host Name and Oracle Names as the naming methods. Click Next. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 643 22.When Oracle database version window appears, accept the option of connecting to Oracle8i or later database. Click Next. 23.When the service name window appears, enter the service name in the service name field on the server. For example, our service name is o920.sun3.itso.ral.ibm.com. Click Next. 24.When network protocol for communication window appears, select TCP. Click Next. 25.When the TCP/IP details window appears, enter your database server host name in the host name field and select default value of 1521 as the TCP port. We entered sun3.itso.ral.ibm.com in the Host name field. Click Next. 26.When the Test window appears, select Yes, perform a test. 27.When the Net Service Name Configuration Connecting window appears, you may see an error message stating that the test did not succeed. A default system user ID of system is defined. Click Change Login, and enter the following: – Username: system (default) – Password: password_of_system (default: manager) – Click OK. 28.The test will occur automatically after clicking OK to change the login. You should see a message stating ”Connecting... Test successful”. When done, click Next. 29.When the Net Service Name window appears, enter the following: – Net Service Name: For example: o920 – Click Next. 30.Now that you have created the o920 Net Server Name, when the Another Net Service Name window opens, select No, and then click Next. 31.When the Net Service name Configuration Complete window appears, click Next. 32.When the informational message on Host Name mapping appears, review the information and click Next. 33.When the Naming Methods Configuration Complete window appears, click Next. 34.When the Oracle Net Configuration Complete window appears, click Finish. 35.When the End of Installation window appears, click Exit, and answer Yes to confirm. 644 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: The Oracle Enterprise Manger Console may be launched automatically right after the install. You can cancel the window and close the application. Verifying the Oracle9i client installation To test the Oracle9i database client installation, perform the following steps (for tips on some of the steps detailed below, refer to Appendix D, “Oracle tips” on page 997): 1. Ensure that the Oracle instance on the Oracle database server (Node C) is started. 2. Ensure that the Oracle listener on the Oracle database server is started. 3. Open a Solaris Console and enter the following: # su -oracle # sqlplus system/manager@o920 4. You should see all database users by entering: SQL> select * from all_users; You should see all SIDs by entering: SQL> select * from v$instance; You should see all table spaces by entering: SQL> select * from v$tablespace; SQL> quit The Oracle9i Client installation and configuration are now complete. 17.5.2 WebSphere Commerce installation Before performing a typical three-node installation of WebSphere Commerce V5.5, do the following: 1. Install and configure the Oracle9i database. Refer to 17.4, “Database Server node implementation” on page 623 and 17.5.1, “Oracle9i client installation” on page 640 for details on performing this step. 2. Install and configure the Sun ONE V6 (SP4) Web server. Refer to 17.3, “Web Server node implementation” on page 611 for details on performing this step. Once these steps are performed, the remaining WebSphere Commerce components can be installed as specified in the following sections. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 645 17.5.3 Create users and groups To reduce the security risk, it is advisable to run applications servers such as WebSphere Commerce and WebSphere Commerce Payments as a non-root user. This section explains how to create the non-root user(s) and groups and what they are used for. Note: Refer to the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems for more detailed information. We will create two separate non-root users and groups: Create the non-root user for WebSphere MQ embedded WebSphere MQ embedded messaging requires non-root user mqm, and groups mqm and mqbrkrs. This is needed due to a hardcoded requirement of the MQ embedded messaging included with WebSphere Application Server V5 when running as non-root. If the WebSphere Application Server had been installed via smitty on AIX, this step would have been done automatically for a non-root user installation. In our example, the WebSphere Commerce installer used the WebSphere Application Server response file-driven installation, which does not have the ability to create the non-root user mqm. Create the non-root user for WebSphere application servers We created the non-root user wasuser and group wasgroup. During the WebSphere Commerce installation (including Payments), you will be prompted to provide the non-root user and group that the WebSphere Commerce or WebSphere Commerce Payments application servers will use for configuration and startup. Note: The non-root users and groups must be created before the WebSphere Commerce installer is executed. The WebSphere Commerce installer will perform a prereq check to verify the non-root user(s) and groups exist before allowing you to proceed during the installation. Create the non-root user for WebSphere MQ embedded You must create the users and groups on the machine where you want to install WebSphere Commerce or WebSphere Commerce Payments. You can create users and groups by performing the following steps: 1. Log on as root. 2. Start the Solaris Admintool by entering the following from a Console command line as user root: # admintool 646 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 3. When the Admintool Users window appears, select Browse -> Groups from the menu bar. 4. From the Admintool Groups window, select Edit -> Add from the menu bar. 5. In the Admintool Add Group window, enter mqm for the group name and root in the Members List and click OK. 6. Repeat for the other group, entering mqbrkrs. 7. From the Admintool Groups window, select Browse -> Users from the menu bar. 8. From the Admintool Users window, select Edit -> Add from the menu bar. 9. In the Admintool Add User window, fill in the information as follows, and click OK: – – – – – – – – User Name: mqm Primary Group: mqm Login Shell: Select Korn Select Password -> Normal Password You will be prompted to enter your password and click OK Ensure that Create Home Dir is selected Path: /export/home/mqm (home directory for oracle user) Accept the default values for the other fields Note: The mqm user requires the WebSphere Application Server environment variables to be set. There is a shell script to set up the environment. It can be found at /bin/setupCmdLine.sh. Typically, you would be able to invoke this script from the .profile file of the mqm user. However, in our case we were not able to do so. Thus, you may have to copy the contents of the file into the .profile file. Create the non-root user for WebSphere application servers To create the non-root user and groups used to configure and start WebSphere application servers such as WebSphere Commerce and WebSphere Commerce Payments repeat the steps outlined in “Create the non-root user for WebSphere MQ embedded” on page 646 for the user wasuser and group wasgroup. Add users wasuser and root to wasgroup. 17.5.4 Installing the remaining WebSphere Commerce components 1. Start the Solaris Console as root. 2. Insert the WebSphere Commerce Business Edition V5.5 CD in the CD-ROM drive. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 647 3. Type the following command to start the installation program: # ./cdrom/webspherecommbe1/setup_solaris Note: Don’t switch to the directory to launch the setup script, or you will not be able to unmount and switch CDs when prompted by the installation program. # cd /cdrom/sun # ./setup_solaris Tip: Alternatively, you can issue the following command: # /setup_solaris -console Using the -console parameter starts a text-based install wizard. The steps in the text-based install wizard and the GUI-based install wizard are the same, but the methods of selection options and continuing in the install wizard differ. For our installation, we used the GUI-based install wizard. 4. When the Installation Wizard window appears, choose the preferred language to be used by the Installation wizard. For example, we accepted the default value of English. Click Next. 5. When the Installation wizard welcome window appears, click Next. 6. When the Software License Agreement window appears, read the agreement. Accept the agreement to continue. Click Next. Note: Rejecting the agreement ends the installation process. 7. When the installation type window appears, select Typical Installation, and click Next. 8. When the typical installation node options window appears, select Three-node installation and click Next. 9. When window appears which node of a typical three-node installation you want to install, select WebSphere Commerce Server node. Click Next. 10.When the database used by WebSphere Commerce window appears, select Oracle Database from the list. Click Next. 11.When the Oracle database server version window appears, select Oracle version 9.2 or higher from the list. Click Next. 648 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 12.When the destinations paths window appears, accept default or enter different destination paths. We accepted the following default values and then clicked Next: /opt/WebSphere/AppServer /opt/WebSphere/CommerceServer55 13.When the database user ID and password window appears, enter values for database user password and database user home directory. For example, we entered the following values and then clicked Next: – – – – – Database instance owner: oracle Database user Password: oracle Verify database user password: oracle Database user group: oinstall Database user home directory: /export/home/oracle 14.When the non-root user ID information for the WebSphere Commerce application server user appears, enter the following and then click Next: – Non-root user ID: wasuser – Non-root user group: wasgroup – Fullpath of the user ID’s home directory: /export/home/wasuser Note: The non-root user wasuser was created in “Create the non-root user for WebSphere application servers” on page 647. 15.Click Next on the installation options and parameters window. Click Next. 16.Replace the CD and enter the location of the WebSphere Application Server installable module. Click Next. # umount /cdrom/cdrom0 # eject 17.When the path for disk1 for WebSphere Commerce installation window appears, swap the CDs and enter the path or location. 18.When the path for disk2 for WebSphere Commerce installation window appears, swap the CDs and enter the path or location. Note: The installer installs fixes for WebSphere Application Server from WebSphere Commerce CD 2. 19.iWhen a message indicating successful installation of WebSphere Commerce appears, click Next. 20.When the Installation Complete window appears, click Finish. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 649 WebSphere fix installation for Web Server node After the installation is completed, specified WebSphere Application Server interim fixes need to be applied to the node with Web server. Apply the fixes by executing the following steps: 1. Go to Disk2 of the WebSphere Commerce Installation CDs: /cdrom/webspherecommbe2/Software_Patches/WAS/repository. 2. Extract the file: $ gunzip PQ70166_SUN.tar.Z $ tar -xvf PQ70166_SUN.tar 3. Copy mod_ibm_ssl_128.so to /libexec. cp mod_ibm_ssl_128.so /opt/WebSphere/AppServer/libexec 4. Copy dtd from the commerce node (from /properties/version/dtd) to the Web Server node (/properties/version/dtd). Fixes listed in Readme file Refer to the WebSphere Commerce Readme file for additional fixes required. 17.5.5 WebSphere Commerce instance creation Once you have installed all the required software, you can create a WebSphere Commerce instance. In our scenario, we used the WebSphere Commerce Configuration Manager to create the instance. The WebSphere Commerce instance creation is organized as follows: Starting the Configuration Manager server Starting the Configuration Manager client Create the WebSphere Commerce instance Verifying the WebSphere Commerce instance creation Starting the Configuration Manager server To start the WebSphere Commerce Configuration Manager server, do the following: 1. Start the Solaris Console and log in as root. 2. WebSphere Commerce uses valid Java locales only. Therefore, before you start the Configuration Manager, ensure that any locale-related environment variables are set to include the WebSphere Commerce-supported locale, shown in the following list: – Language: German, Locale Code: de_DE – Language: English, Locale Code: en_US 650 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – – – – – – – – Language: Spanish, Locale Code: es_ES Language: French, Locale Code: fr_FR Language: Italian, Locale Code: it_IT Language: Japanese, Locale Code: Ja_JP Language: Korean, Locale Code: ko_KR Language: Brazilian Portugese, Locale Code: pt_BR Language: Simplified Chinese, Locale Code: Zh_CN Language: Traditional Chinese, Locale Code: Zh_TW To determine your locale, run the following command: # echo $LANG If your locale is not supported or not set, change your locale properties by running the following commands as root user: # LANG=xx_XX # export LANG Where xx_XX is your four-letter locale code with the same capitalization as shown in the above list. Note: Update the .profile for the non-root user wasuser to include the above statement by adding the following line to the .profile: export LANG=xx_XX 3. Ensure that your remote database server is running. 4. Change the user to wasuser user. # su - wasuser 5. Change to the WebSphere Commerce directory and run the script: $ cd /opt/WebSphere/CommerceServer55/bin $ ./config_server.sh & Wait for the following message: “Registry created. CMServer bound in registry”. This Configuration Manager server background process will be automatically terminated when you close the Configuration Manager client, to eliminate a potential security risk. Starting the Configuration Manager client To start the Configuration Manager client, complete the following steps: 1. Start a Solaris Console. 2. Change the user to wasuser user. # su - wasuserwasuser 3. Export the DISPLAY variable, if needed. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 651 4. Export the LANG variable, if needed. 5. Change the directory and run the Configuration Manager client: $ cd /opt/WebSphere/CommerceServer55/bin $./config_client.sh 6. A window displays where you will be prompted to enter the Configuration Manager user ID and password. The default Configuration Manager user ID is webadmin, and the default password is webibm. You will be asked to change your password the first time you log in. Create the WebSphere Commerce instance To create your instance, do the following using the WebSphere Commerce Configuration Manager Instance Creation wizard: 1. From the Configuration Manager, expand the host name where you want the instance to be created. 2. Right-click Instance List and from the resulting pop-up menu, and select Create Instance. 3. When the Instance Creation wizard opens, we entered the following values for each tab to create the instance. Unless otherwise noted, we accepted the default values. – Instance tab • Instance name: demo • Instance’s root path: /opt/WebSphere/CommerceServer55/instances/demo • Merchant Key: This is the 16-digit hexadecimal number for the Configuration Manager to use as the encryption key. You must enter your own key in the Merchant Key field. Ensure that the key that you enter will be sufficient to protect your site, especially for a production server. Take note of the merchant key you entered. After you have created a store, you can only change this key by using the Database Update Tool. To use this tool, access Configuration Manager, right-click the database node, and select Database Update Tool. 652 • URL mapping file: /opt/WebSphere/CommerceServer55/instances/xml/mapping/urlmapp er.xml • Site Admin ID: Enter a preferred ID for your site. We used wcadmin as the ID. WebSphere Commerce V5.5 Handbook Customization and Deployment Guide • In the Site Admin Password and Confirm Sire Admin Passwords fields enter the password of your choice (must be at least 8 characters long). • Click Next. – Database tab • WebSphere Commerce Database: Choose Create a new database or table space option. • Database administrator name: system Enter the system ID of the user who issues Oracle commands. • Database administrator password: Enter password for system • Database administrator home directory: /export/home/oracle • Database name: o920 • Oracle SID: o920 Enter the SID of the database you created for use by WebSphere Commerce server. • Database type: Select Oracle • Oracle instance userid: oracle • Select the check box for Remote. • Database Server Hostname: sun3.itso.ral.ibm.com This field is enabled if you select Use Remote Database. Enter the fully qualified host name of the node on which your database resides. • Database Server Port: 1521 • Enter the database server port for Oracle9i listener (1521 default). • Tablespace Name: WCTBLSPC • Temporary Tablespace: temp • Accept the default values • Click Next. – Schema tab • Oracle instance userid: oracle • Database user name: wcuser • Database user password and Confirm Database user password: Your chosen password. • Click Next. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 653 – Languages tab • We accepted the default, English. • Click Next. – Web Server tab • Select Use Remote WebServer. • Web Server Type: Select Sun ONE. By selecting a different Web server from the default, all fields previously filled in will be cleared. For this reason, select the Web server type first. • Hostname: sun1.itso.ral.ibm.com This is the host name of the remote iPlanet Web Server. • Primary Document Root: /usr/iplanet/servers/docs • Server Port: 80 • Authentication Mode: Basic • Secure Server Config File Path: /usr/iplanet/servers/https-sun1.itso.ral.ibm.com/config/obj.conf • Non-secure Server Config File Path: /usr/iplanet/servers/https-sun1.itso.ral.ibm.com/config/obj.conf • Secure Tools Server Config File Path: • /usr/iplanet/servers/https-sun1.itso.ral.ibm.com/config/obj.conf • Secure Admin Server Config File Path: /usr/iplanet/servers/https-sun1.itso.ral.ibm.com/config/obj.conf • Secure OrgAdmin Server Config File Path: • /usr/iplanet/servers/https-sun1.itso.ral.ibm.com/config/obj.conf • Select the Remote Configuration, which results in a window with the following additional fields: • • • • • Remote Server Name: sun1.itso.ibm.com Remote Server Port: 21 Remote User name: iplanet Remote User Password: Click Next. – WebSphere tab • DataSource Name: WebSphere Commerce Oracle DataSource demo This is used to set up the Connection Pool for access to the database with which WebSphere Commerce works. Accept the default 654 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide WebSphere Commerce Oracle DataSource demo, where demo is the instance name. • JDBC Driver Location: /opt/oracle/u01/app/oracle/product/9.2.0/jdbc/lib/classes12.zi p This is the location of the JDBC file. We accepted the default. • Tools Port Number: 8000 The port number used for accessing WebSphere Commerce administration tools. Accept the default port number 8000. • WC Admin Port Number: 8002. • WC OrgAdmin Port Number: 8004 • Click Next. – Payment Manager tab • Hostname: sun1.itso.ral.ibm.com Enter the domain qualified host name of the Web server used by WebSphere Commerce Payments, for example sun1.itso.ral.ibm.com, the remote Web server machine. • Profile Path: The full path name of the directory where the Standard WebSphere Commerce Payments Cashier Profiles are to be stored, for example /opt/WebSphere/CommerceServer55/instances/demo/xml/payment. • Use non-SSL Payment Manager Client: do not enable this check box. WebSphere Commerce will use the SSL client to communicate with the WebSphere Commerce Payments server. • Web Server Port: accept the default value for this field, which is 5433 (the SSL port). • Use SOCKS Server: do not enable this check box WebSphere Commerce will not go through a SOCKS server in order to reach WebSphere Commerce Payments. • Click Next. – Log System tab We accepted the default values for all messaging options. • Activity Log Cache Size: Enter the maximum size of the activity log’s cache. The default value is 20. • Notification Enabled: Select this check box if you want to be notified of error-level messages. You must also modify the notification information Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 655 in the WebSphere Commerce Administration Console to receive these messages. • Click Next. – Messaging tab We accepted the default values for all messaging options. • User Template File: This is the name of the XML message template definition file that allows you to add new inbound XML messages to be supported by your system. An outline should be added to this file for each new XML message that you want to support. It is recommended that you use the default user_template.xml, which is stored in the template path directory. • Inbound Message DTD Path: This is the path where all the DTD files for inbound XML messages are stored. The default is /opt/WebSphere/CommerceServer55/xml/messaging. • WebController User ID: This is the ID used by WebSphere Commerce to execute all the WebSphere Commerce MQSeries® Adapter inbound messages. It should be an ID that has Site Administrator authority. The default is wcsadmin. Ensure that only authorized persons have the authority to update the User Template File and System Template File, since the inbound XML messages can be mapped to execute WebSphere Commerce commands using this ID. • System Template File: This is the name of the XML message template definition file that contains the outline of all inbound XML messages supported by the WebSphere Commerce MQSeries Adapter. This file defines the data fields for each message, mapping the message to the appropriate WebSphere Commerce Controller command, and mapping each field within the message to the appropriate parameter for that command. It is recommended that you use the default sys_template.xml which is stored in the template path directory. • Template Path: This is the path where the User Template File and System Template File are stored. The default is /opt/WebSphere/CommerceServer55/xml/messaging. • Inbound Message DTD Files: This is the list of the DTD and include files for inbound XML messages. If you add a new inbound XML message, you need to add it in this field. • Click Next. – Auction tab • 656 Enable Auction: in our scenario, we did not select the Enable check box to enable Auctions. WebSphere Commerce V5.5 Handbook Customization and Deployment Guide • Click Finish. 4. You are asked if you want to populate the Oracle database. Click Yes to populate your database and click OK. Depending on the speed of your system, the time needed to create an instance can be as much as several hours. The progress bar that displays when you start creating the instance will indicate when the process has finished. 5. We recommend that you check the progress of the instance creation by looking at the log entries. For example, after the instance creation progress indicator is started, enter the following: # cd /opt/WebSphere/CommerceServer55/instances//logs # tail -f createdb.log # tail -f populatedb.log If any of these logs contain failures, your database schema will not be created properly for WebSphere Commerce and the instance creation should be stopped. Resolve the problem (password, db name, etc.) and then recreate the instance. 6. After your instance has been created, WebSphere Commerce will attempt to start the WebSphere Commerce Server associated with the instance. When this has successfully completed, click OK to close the Instance Creation wizard. Note: If you get the error message, “Cannot configure the secure server. Instance was not created. Please correct before retrying,” ensure that the environment for the wasuser user has been set up properly. 7. In the Configuration Manager menu, select Console -> Exit. Stop the Configuration Manager Server for security reasons. Confirm the message by clicking OK. Verifying the WebSphere Commerce instance creation To verify that the WebSphere Commerce instance has been created properly, complete the following steps: 1. Check the following configuration and log files: – .xml: This file contains all of the configuration information about your WebSphere Commerce instance. /opt/WebSphere/CommerceServer55/instances//xml/.xml Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 657 – createdb.log: This file contains information about the WebSphere Commerce schema creation, foreign keys, and indices. /opt/WebSphere/CommerceServer55/instances//logs/createdb. log – createdb.production.log: This file contains information about the WebSphere Commerce schema creation with production support. /opt/WebSphere/CommerceServer55/instances//logs/createdb. production.log – populatedb.log: This file contains information about the WebSphere Commerce database population process. /opt/WebSphere/CommerceServer55/instances//logs/populate db.log – createsp.log: This file contains information about the stored procedure creation in the WebSphere Commerce instance database schema. /opt/WebSphere/CommerceServer55/instances//logs/createsp. log – populateddb2.log: T his file contains information about the database population with Access Control and UBF data. /opt/WebSphere/CommerceServer55/instances//logs/populate ddb2.log – WASConfig.log: This file contains information about the enterprise application deployment and configuration of your WebSphere Commerce instance (application server), within WebSphere Application Server. /opt/WebSphere/CommerceServer55/instances//logs/WASCon fig.log 658 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: The log directory also contains error logs associated with some of the log files above. You can check the error files for any messages. For example: /opt/Websphere/CommerceServer55/instance//logs/createsp.l og /opt/Websphere/CommerceServer55/instance//logs/createsp. err.log 2. Start the newly created WebSphere Commerce instance under WebSphere Application Server and look at the log file for any errors. Under the WebSphere Application Server, the instance name is prefixed with WC_, so in our case, it would be WC_demo. Log in as root and do the following: # su - wasuser $ cd $WAS_HOME/bin $ ./startServer.sh WC_demo Note: To stop the server, enter the following: $ ./stopServer.sh 3. Check that the database tables have been created correctly by entering the following: # su - oracle $ sqlplus wcuser/wcuser1@o920 $ select count(*) from user_tables; You should see the following message (listing all WebSphere Commerce tables created during the instance creation): COUNT(*) --------559 17.5.6 WebSphere Commerce post-instance config This section contains the steps that need to be completed for the WebSphere Commerce configuration after instance creation. You must manually copy some files from the WebSphere Commerce node to the Web Server node as specified in the following steps: On the Web server machine, check that the following directories exist: – WAS_installdir/installedApps – WAS_installdir/config/cells Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 659 For example, our machine is sun1 and locations are as following: – /opt/WebSphere/AppServer/installedApps – /opt/WebSphere/AppServer/config/cells If the directories don’t exist, create them. Note: The full path of the WAS_installdir directory on the Web Server node must match the WAS_installdir directory on the WebSphere Commerce node. If the directory paths do not match, WebSphere Commerce will not function correctly. Copy WC_instance_name.ear directory from the WebSphere Commerce node to the WAS_installdir/installedApps directory on the Web Server node. For example, we copied WC_demo.ear from sun2 host located in /opt/WebSphere/AppServer/installedApps/sun2 to sun1 host. On sun1 host, we copied WC_demo.ear folder to /opt/WebSphere/Appserver/installedApps directory. Copy the plugin-cfg.xml file from the WebSphere Commerce node to the WAS_installdir/config/cells directory on the Web Server node. For example, we copied plugin-cfg.xml from sun2 host located in /opt/WebSphere/AppServer/config/cells to sun1 host. On sun1 host, we copied the file to /opt/WebSphere/Appserver/config/cells directory. Note: If your are creating a WebSphere Commerce Payment instance after creating a WebSphere Commerce instance, copy the plugin-cfg.xml after creating the WebSphere Commerce Payment instance. Restart the iPlanet Web Server instances after the plugin-cfg.xml file has been copied to the remote Web server. 17.5.7 Creating a WebSphere Commerce Payment instance To create your instance, do the following using the WebSphere Commerce Configuration Manager Instance Creation wizard. 1. From the Configuration Manager, expand the host name where you want the instance to be created. 2. Right-click Payments instance List and from the resulting pop-up menu, select Create Instance. 3. When the Instance Creation wizard opens, we entered the following values for each tab to create the instance. Unless otherwise noted, we accepted the default values. 660 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – Instance tab • Instance name: wpm • Select the option, Password Required for startup • Instance Password: password of your choice, • WebSphere Node Name: sun2 This is the machine on which WebSphere Commerce is installed. • Protocol Threads: 8 • Service Threads: 6 • Minimum Access Role: clerk • Site Admin ID: wcpadmin • Click Next. – Database tab • WebSphere Commerce Database: Choose Create a new database or tablespace option. • Database administrator name: Enter the system ID of the user who issues Oracle commands. • Database administrator password: Enter password for system • Database administrator home directory: /export/home/oracle • Database name: o920 • Oracle SID: o920 Enter the SID of the database you created for use by WebSphere Commerce server. • Database type: Select Oracle • Oracle instance userid: oracle • Select the check box for Remote. • Database server hostname: sun3.itso.ral.ibm.com This field is enabled if you select Use Remote Database. Enter the fully qualified host name of the node on which your database resides. • Database Server Port: 1521 • Enter the database server port for Oracle9i listener (1521 is the default). • Tablespace Name: WPMTBLSPC • Temporary Tablespace: temp Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 661 Accept the default values • Click Next. – Schema tab • Database name: o920 • Oracle SID: o920 • Database type: Oracle • Oracle instance userid: oracle • Database user name: wcpuser • Database user password and Confirm Database user password: Your chosen password. • Click Next. – Web Server tab • Select Use Remote WebServer • Web Server Type: Select Sun ONE By selecting a different Web server from the default, all fields previously filled in will be cleared. For this reason, select the Web server type first. • Hostname: sun1.itso.ral.ibm.com This is the host name of the remote iPlanet Web Server. • Primary Document Root: /usr/iplanet/servers/docs • Server Port: 5432 • Non-secure Server Config File Path: /usr/iplanet/servers/https-sun1.itso.ral.ibm.com/config/obj.conf • Select Use SSL • SSL Port: 5433 • Secure Server Config File Path: /usr/iplanet/servers/https-sun1.itso.ral.ibm.com/config/obj.conf • Select the Remote Configuration, which results in a window with the following additional fields: • • • • 662 Remote Server Name: sun1.itso.ral.ibm.com Remote Server Port: 21 Remote User name: iplanet Remote User Password: Your password for iplanet user WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: We did not use this configuration option. Instead we used the Mapped Network Drive Configuration option. Refer to “NFS share/mount” on page 984 for information on mounting a file system on Solaris. Alternatively, you can mount a remote file system and choose the option Mapped Network Drive Configuration. Note: Make sure you enter appropriate paths in the fields Primary Document Root, Non-Secure Server Config File Path and Secure Server Config File Path. For example, we mounted Web Server node, /usr/iplanet/servers/ path on /mnt on the WebSphere Commerce node. Hence, we entered the following values for the specified fields: Primary Document Root: /mnt/docs Non-secure Server Config File Path: /mnt/https-sun1.itso.ral.ibm.com/config/obj.conf Non-secure Server Config File Path: /mnt/https-sun1.itso.ral.ibm.com/config/obj.conf • Click Next. – WCS Realm tab • WC Hostname: sun1.itso.ral.ibm.com • WC Web Path: /webapp/wcs/stores/servlet • WC Web Server Port: 443 • Click Finish. 4. The Install wizard will prompt you to confirm if your want to use existing database for Payments. Click Yes to use existing database. 5. We recommend that you check the progress of the instance creation by looking at the log entries. For example, after the instance creation progress indicator is started, enter the following: # cd /opt/WebSphere/CommerceServer55/instances/WCSConfig.log # tail -f createdb # tail -f populatedb Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 663 If any of these logs contain failures, your database schema will not be created properly for WebSphere Commerce Payment and the instance creation should be stopped. Resolve the problem (password, db name, etc.) and then recreate the instance. 6. After your instance has been created, WebSphere Commerce will attempt to start the WebSphere Commerce Server associated with the payment instance. When this has successfully completed, click OK to close the Instance Creation wizard. 7. In the Configuration Manager menu, select Console -> Exit. Stop the Configuration Manager Server for security reasons. Confirm the message by clicking OK. 17.5.8 WebSphere Commerce payment post-instance config This section contains the steps that need to be completed for the WebSphere Commerce Payment configuration after instance creation. You must manually copy some files from the WebSphere Commerce node (node-B) to the Web Server node (node-A) as specified in the following steps: 1. On the Web server machine, check that the following directories exist: – WAS_installdir/installedApps – WAS_installdir/config/cells For example, our machine is sun1 and the locations are as following: – /opt/WebSphere/AppServer/installedApps – /opt/WebSphere/AppServer/config/cells If the directories don’t exist, create them. Note: The full path of the WAS_installdir directory on the Web Server node must match the WAS_installdir directory on the WebSphere Commerce node. If the directory paths do not match, WebSphere Commerce will not function correctly. 2. Copy the instance_name_Commerce_Payment.ear directory from the WebSphere Commerce node to the WAS_installdir/installedApps directory on the Web Server node. For example, we copied the wpm_Commerce_Payments_App.ear folder from sun2 host located in /opt/WebSphere/AppServer/installedApps/sun2 to sun1 host. On sun1 host, we copied the wpm_Commerce_Payments_App.ear folder to the /opt/WebSphere/Appserver/installedApps directory. 3. Copy the plugin-cfg.xml file from the WebSphere Commerce node to the WAS_installdir/config/cells directory on the Web Server node. 664 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide For example, we copied plugin-cfg.xml from sun2 host located in /opt/WebSphere/AppServer/config/cells to sun1 host. On sun1 host, we copied the file to the /opt/WebSphere/Appserver/config/cells folder. Note: Restart the iPlanet Web Server instances after the plugin-cfg.xml file has been copied to the remote Web server. 17.5.9 Start/stop the WebSphere Commerce instance Once your instance has been created, it will not be started automatically in a three-tier scenario. If you modify your instance at a later time, you will need to restart it. You can stop and start your instance from the Console: 1. Log in as root and then change the user to wasuser. For example: # su - wasuser 2. Change the working directory to /bin: $ cd /opt/WebSphere/AppServer/bin 3. Use startServer.sh or stopServer.sh to start or stop a server instance. To start a server instance: $./startServer.sh To stop a server instance $./stopServer.sh For example, we started WebSphere Application Server instance using: $./startServer.sh server1 It is not essential to run this server to start the WebSphere Commerce server instance. We started a WebSphere Commerce instance using: $./startServer.sh WC_demo And we started a WebSphere Commerce Payment instance using: $./startServer.sh wpm_Commerce_Payments_Server Start WebSphere Commerce Payment instance To start WebSphere Commerce Payment, complete the following steps: 1. Start the WebSphere Commerce Payment server using the following command: Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 665 $ /bin/startServer.sh _Commerce_Payments_Server For example, we entered: $ cd /opt/WebSphere/AppServer/bin $ ./startServer.sh wpm_Commerce_Payments_Server 2. Start the WebSphere Commerce Payment instance using the following command: $ /payments/bin/IBMPayServer Where and are the values entered by you during the payment instance creation process. For example, we entered: $ cd /opt/WebSphere/CommerceServer55/payments/bin $ ./IBMPayServer wpm password Tip: You can monitor the startup by looking at the file Configurator.1.log file located in the directory /instances. For example, change your current directory and issue the following command: $ tail -f Configurator.1.log 17.5.10 Regenerating Web server plug-in configurations At times, you might need to instruct the WebSphere Application Server plug-in to regenerate its configuration. You should typically regenerate the plug-in configuration after, for example, installing or removing an enterprise application, adding or removing servlets and mappings from a particular application, or changing the configuration for the plug-in, a virtual host or a transport. To generate the plug-in configuration, you can either use the Update Web Server Plugin Configuration page in the WebSphere Application Server Administration Console, or run the following script: was_install_dir/bin/GenPluginCfg.sh For example, we issued: $ /opt/WebSphere/Appserver/bin/GenPluginCfg.sh Alternatively, go to the Update Server Plugin page within the WebSphere Application Server Administration Console. Click Environment -> Update Web Server Plugin in the Console navigation tree. Click OK. After you have regenerated the plug-in file, copy it to the Web Server node. Refer to 17.5.8, “WebSphere Commerce payment post-instance config” on page 664 666 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide for details on completing this step. You might need to stop the Web server and then start it again before the changes to the plug-in configuration takes effect. 17.5.11 iPlanet Web Server configuration for WebSphere Commerce In this section, we describe how to configure the remote iPlanet Web Server for use with WebSphere Commerce, including the following tasks: Configuring aliases in Web server Verifying the WebSphere Commerce tools Configuring aliases in Web server You need to configure iPlanet server to set up directories for the WebSphere Commerce WAR files. This is an essential step, because the static content path is not known to the Web server, which will result in broken images. Follow these steps to configure the iPlanet server: 1. Start iPlanet Administrator Console by issuing the following command: #./startconsole 2. Select your server instance and click Manage. 3. Click the Class Manager link next to the Apply link. 4. Click the Content Mgmt tab. 5. Click the Additional Document Directories link on the left-hand side. 6. Enter one entry at a time, then click OK. For example, we added the URL prefixes and corresponding map to directories listed in Table 17-10. Table 17-10 WebSphere Commerce instance aliases URL prefix Map to directory adminconsole /installedApps/WC_demo.ear/SiteAdministration.wa r/tools/adminconsole/wcsadmincon.html accelerator /installedApps/WC_demo.ear/CommerceAccelerato r.war/tools/common/accelerator.html wcs /installedApps/WC_demo.ear/CommerceAccelerato r.war wcadmin /installedApps/WC_demo.ear/SiteAdministration.wa r/ wcsstore /installedApps/WC_demo.ear/Stores.war/ Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 667 URL prefix Map to directory wcorgadmin /installedApps/WC_demo.ear/OrganizationAdministr ation.war/ orgadminconsole /installedApps/WC_demo.ear/OrganizationAdministr ation.war/tools/buyerconsole/wcsbuyercon.html 7. Restart the server instance. Verifying the WebSphere Commerce tools In order to verify that the WebSphere Commerce three-tier implementation is functioning correctly, enter the following URLs from a supported Web browser (for example, Microsoft Internet Explorer 5.5 or 6.0): https://:8002/adminconsole https://:8004/orgadminconsole https://:8000/accelerator The WebSphere Commerce instance creation is now complete. Note: If you get a 404 error (file not found), check your obj.conf file to make sure that “Service fn=”as handler” is the first item under the element. If not, then edit the file to make it so. The file can be found in //config/obj.conf. In our case, it was found in /usr/iplanet/servers/sun1-https.sun1.itso.ral.ibm.com/config/obj.conf. The file should contain the following: Service fn=”as handler” ....... If you are still getting errors, you can view the following files to check for correctness: /config/cells/plugin-cfg.xml /magnus.conf For example, in our case: /opt/WebSphere/AppServer/installedApps/config/cells/plugin-cfg.xml /usr/iplanet/servers/https-sun1.itso.ral.ibm.com/config/magnus.conf 668 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 17.6 Verify the runtime environment Publishing a store archive to a WebSphere Commerce Server allows you to create a running store. You have two options for publishing a store archive: publish a store archive from the Store Archives menu on the Site Administration Console or from a command line. This section includes the following tasks for publishing a store from Store Archives: Publish a store archive (SAR) Configure Web server for static content Removing dynamic content from Web server Compile the WebSphere Commerce store JSPs Launch store from Site Administration Console Verify the sample store 17.6.1 Publish a store archive (SAR) To publish a store archive, do the following: 1. Open the Site Administration Console by typing in the Site Administration Console URL in the Internet Explorer browser. For example, we typed: https://sun1.itso.ral.ibm.com:8002/adminconsole 2. Log on to the Console. Enter the administrator user name and password. For example, we entered the following information: – Username: wcadmin – Password: wcpadmin Click Log On. 3. From the Administration Console Site/Store Selection window, select the Site check box. Click OK. 4. From the Site Administration Console window, go to Store Archives and select the Publish menu item. 5. When the Store Archives window appears, choose one of the store archives by clicking the radio button next to it. For example, we selected the B2BDirect.sar Store Archive. Click Next. 6. When the parameters window appears, select your desired publishing options. For more information on publishing options, click Help. We accepted the default options, and then clicked Next. 7. When the summary window appears, click Finish. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 669 8. When a pop-up window appears informing you that the store archive is submitted for publishing, click OK. 9. While the store is publishing, you are returned to the Store Archive list page. The publishing state is reflected in the Publish status column. Depending on the speed of your system, it may take some time to complete the publishing process. Click Refresh to update the status. Tip: Publishing a store with the combination of Solaris and Oracle9i database can take a long time. We recommend that you also keep an eye on the CPU and Disk activity indicator for the Solaris toolbar of the Commerce/Application server. 10.When the status changes to Complete, continue to the next section. 17.6.2 Configure Web server for static content This section describes how to configure your Web Server node so that the iPlanet server can locate static content.There are different ways of achieving this, but we copied the /installedApps/sun2/WC_demo.ear/Stores.war from the Commerce and Application server node, node B and updated the /installedApps/WC_demo.ear/Stores.war on the Web Server node. Our approach: To copy the .war file, we created a .tar file for the Stores.war folder. For example: 1. On Node-B: Commerce/Application Server: a. Change the working directory: cd /opt/WebSPher/installedApps/sun2/WC_demo.ear b. Issue the following command to create a .tar file: tar -cvf stores.war.tar stores.war 2. On Node-A: iPlanet Web Server; a. Change the working directory: cd /opt/WebSPher/installedApps/WC_demo.ear b. Get the stores.war.tar file from Node-B using FTP or any other mechanism of your choice. We used FTP. c. Untar the file by issuing the following command: tar -xvf stores.war.tar 670 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Removing dynamic content from Web server This section describes how to remove dynamic content, in particular, JSPs from the Web Server node. Since the application server deals with dynamic content, it should be kept on the Application node. Hence, we removed the JSPs from the Web Server node. To remove JSPs, remove META-INF and WEB-INF subdirectories from the on the Web Server node. 17.6.3 Compile the WebSphere Commerce store JSPs In order to provide better performance when store JSPs are accessed for the first time, we recommend that the store JSPs be compiled. To batch compile JSPs for the WebSphere Commerce store, do the following: 1. Ensure that the WebSphere Application Server is started. If it has not been started already, then open a Solaris Console and enter the following commands: # su - wasuser $ /opt/WebSphere/AppServer/bin/startupServer.sh server1 To monitor when the WebSphere Application Server is finally started, type: $ tail -f /opt/WebSphere/AppServer/tracefile Tail the trace file until the message “adminServer open for e-business” appears. 2. From a command prompt, run the script from /bin location: JspBatchCompiler 17.6.4 Launch store from Site Administration Console After you have published the store and optionally compiled the store JSps, do the following to launch the sample store: 1. Get the Site Administration Console by typing in the Site Administration Console URL in the Internet Explorer browser. For example, we typed: https://sun1.itso.ral.ibm.com:8002/adminconsole 2. Log on to the Console. Enter the administrator user name and password. For example, we entered the following information: – Username: wcadmin – Password: wcpadmin Click Log On. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 671 3. From the Administration Console Site/Store Selection window, select the Site check box. Click OK. 4. From the Site Administration Console window, go to Store Archives and select the Publish Status menu item. 5. Select the job number. Click Details on the right-hand side. 6. When the Publish Details window appears, click Launch Store to view and test your store. 7. After clicking the Launch Store button, a window pops up asking for the Web application Web path for the store in the input field; the default value is /webapp/wcs/stores. 8. Accept the default value and click the OK button. The first page of your store will be displayed. When you have finished, bookmark the site and close the browser. Note: When you launch the store from Store Archives Console, you are logged in to the store with the same user name and password that you used to log in to Store Services. If you change your password in the store, you are also changing it for that user. Instead, to test the features in the store, including changing your password, bookmark the site, close the browser, then log in to the store again. 17.6.5 Verify the sample store To place a test order at your store, do the following to verify the store and runtime environment: 1. Ensure that you have copied the appropriate static content to the Web server. Refer to 17.6.2, “Configure Web server for static content” on page 670 for steps on how to do so. 2. Open your store by doing either one of the following: – In the Site Administrator Console, choose the Store option. Click OK. Choose Store Archives, and click Publish Status. In the Publish Summary window, click Details and select your store. Click Launch Store. – Select the bookmarked link for the store in your browser. 3. Navigate to your Store's home page. 4. On the home page, select Product. On the Product page, click Add to shopping cart. 672 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 5. Complete the order process. For testing purposes, you can use the credit card number 4111111111111111 (15 ones for VISA). An order confirmation page displays, confirming that your order is complete. Chapter 17. Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server 673 674 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 18 Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server This chapter describes in detail how to implement an AIX three-tier (also called 3-tier) WebSphere Commerce V5.5 runtime environment using a remote Web Server node, WebSphere Commerce node, DB2 Server node, and remote WebSphere Commerce Payments node. The scenario documented is intended to be used with the procedures documented in the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems product guide. The scenario provides a first-hand account of what we did to implement the solution, including best practices, tips, and workarounds. This chapter is organized into the following sections: Scenario overview and planning AIX installation Web Server node implementation DB2 Server node implementation WebSphere Commerce Payments node implementation WebSphere Commerce node implementation Verify the runtime environment Additional configuration © Copyright IBM Corp. 2003. All rights reserved. 675 18.1 Scenario overview and planning This section describes the scenario and defines the hardware and software used within the ITSO WebSphere Commerce runtime environment for the AIX platform. The section is organized as follows: Scenario overview Hardware and software prerequisites Hardware used in the ITSO runtime environment Software used in the ITSO runtime environment Software installation paths and variables Installation approaches 18.1.1 Scenario overview The ITSO AIX three-tier runtime environment is depicted in Figure 18-1 on page 677. In this scenario, we provide detailed instructions for implementing a WebSphere Commerce three-tier runtime environment on the AIX platform using DB2 and the IBM HTTP Server. In addition, this scenario uses a remote WebSphere Commerce Payments node. The three-tier AIX configuration can be used as a base to add a load-balanced Web cluster and application server cluster. When implementing a cluster of application servers, WebSphere Commerce Payments needs to be installed on a remote node. For this reason, we will install and configure a separate WebSphere Commerce Payments node as part of this chapter (see Figure 18-1 on page 677). 676 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide DMZ Outside world Internal network WebSphere Commerce 5.5 Business Edition WebSphere Application Server V5 + Fixes DB2 8.1 Enterprise Client + FixPak 1 AIX 5.1 + ML 4 User I N T E R N E T 80/443 80/443 Web Server Web node Server (webaix1) IBM HTTP Server 1.3.26 WebSphere V5 plugin + Fixes AIX 5.1 + ML 4 Domain Firewall Domain Name Server Protocol Firewall Public Key Infrastructure WebSphere Commerce node (wcaix1) WebSphere Commerce Payments node (wcpaix1) DB2 8.1 Enterprise Server Edition + FixPak1 AIX 5.1 + ML 4 DB2 Server node (db2aix1) WC instance database WC Payments database WebSphere Commerce Payments 5.5 WebSphere Application Server V5 + Fixes IBM HTTP Server 1.3.26 DB2 8.1 Enterprise Client + FixPak 1 AIX 5.1 + ML 4 Figure 18-1 AIX three-tier for WebSphere Commerce V5.5 18.1.2 Hardware and software prerequisites For detailed information on WebSphere Commerce V5.5 hardware and software requirements, refer to the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems product guide. 18.1.3 Hardware used in the ITSO runtime environment We used the following hardware within the ITSO runtime environment for the AIX three-tier configuration: Web Server node – IBM RS/6000® 43P (7043-150) • 1 CPU, 375 MHZ PPC 604e • 512 MB RAM • 8 GB hard disk • 1 Ethernet adapter WebSphere Commerce node – IBM RS/6000 44P (7044-170) • 1 CPU, 450 MHZ PPC • 2 GB main memory • 18 GB DASD • 1 IBM Ethernet adapter Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 677 DB2 Server node – IBM RS/6000 F50 (7025-F50) • 2-way CPU PPC • 1 GB main memory • 48 GB DASD (6 8 GB hard disks) • 1 IBM Ethernet adapter WebSphere Commerce Payments node – IBM RS/6000 43P (7043-150) • 1 CPU, 375 MHZ PPC 604e • 1 GB RAM • 16 GB DASD (2 8 GB hard disks) • 1 Ethernet adapter 18.1.4 Software used in the ITSO runtime environment We used the software listed in the following tables on each of the nodes within the WebSphere Commerce three-tier AIX configuration. Table 18-1 Web Server node Software Version AIX 5.1 + Maintenance Level 4 (ML) IBM HTTP Server 1.3.26 WebSphere Application Server plug-in 5.0 Table 18-2 WebSphere Commerce node Software Version AIX 5.1 + Maintenance Level 4 (ML) DB2 UDB Client, Enterprise Server Edition 8.1 + Fix Pack 1 WebSphere Application Server 5.0 WebSphere Commerce, Business Edition 5.5 Table 18-3 DB2 Server node 678 Software Version AIX 5.1 + Maintenance Level 4 (ML) DB2 UDB Server, Enterprise Edition 8.1 + WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Table 18-4 WebSphere Commerce Payments node Software Version AIX 5.1 + Maintenance Level 4 (ML) IBM HTTP Server 1.3.26 DB2 UDB Client, Enterprise Server Edition 8.1 + Fix Pack 1 WebSphere Application Server 5.0 WebSphere Commerce Payments 5.5 WebSphere Commerce - Configuration Manager 5.5 18.1.5 Software installation paths and variables Table 18-5 lists the software installation paths and variables used within this chapter. Table 18-5 Software installation paths and variables Software Install path Variable DB2 UDB Enterprise Edition /usr/lpp/db2_08_01 IBM HTTP Server /usr/IBMHttpServer WebSphere Application Server /usr/WebSphere/AppServer WebSphere Commerce /usr/WebSphere/CommerceSever55 WebSphere Commerce Payments /usr/WebSphere/CommerceSever55 18.1.6 Installation approaches As with most things, there is more than one approach to installing a three-tier WebSphere Commerce runtime environment. We have briefly outlined two installation approaches based on the skill level of the specialist performing the installation. Out-of-the-box install This method of installation uses the documented procedures in the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems. This approach is appropriate for new users to WebSphere Commerce V5.5. The WebSphere Commerce installer will prompt the user to insert the appropriate CDs and make decisions for the user to simplify the installation and Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 679 configuration. In WebSphere Commerce V5.5, there are several installation types (Express, Typical and Custom), each progressing in the number of configuration options. The drawback to this approach is that the user is not aware of what is being configured behind the scenes for them. Many of these behind-the-scenes configuration options are important to an advanced user who needs to fully understand how the “system” is put together. This type of information is needed for troubleshooting and for advanced configurations. Component-based install A three-tier WebSphere Commerce runtime configuration includes many interrelated software components. The component-based install relies upon manually installing and verifying each component before proceeding to the next. This method of installation can take longer to navigate, but is ideal for advanced users who may have existing software components installed and need/want to understand how the system works. In this redbook, we will focus on this installation approach for the AIX three-tier WebSphere Commerce runtime environment. 18.2 AIX installation All systems used in the scenario have the same basic AIX requirements. This section includes the following topics: Network planning AIX installation File system planning Netscape 7 Web browser (optional) AIX software prerequisites Disable wsmserver on port 9090 18.2.1 Network planning We used the following host names for the three-tier AIX runtime environment: Web Server node WebSphere Commerce node DB2 Server node WebSphere Commerce Payments node Subnet Default router DNS Domain 680 webaix1 wcaix1 db2aix1 wcpaix1 255.255.254.0 9.24.104.1 9.24.106.15 itso.ral.ibm.com WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 18.2.2 AIX installation For detailed instructions on installing IBM AIX 5.1, refer to the AIX product installation guides found at: http://www.ibm.com/aix/ 18.2.3 File system planning IBM AIX has the ability to increase the size of a file system with relative ease using the chfs command after the installation of the operating system. Table 18-6 defines the file system space needed for each node of the AIX three-tier runtime environment. Table 18-6 ITSO test systems for AIX three-tier runtime environment DB2 Server node WebSphere Commerce Payments node Hardware spec Web Server node WebSphere Commerce node Machine type IBM RS/6000 43P Model 150 (7043-150) IBM RS/6000 44P Model 170 (7044-170) IBM RS/6000 Server F50 (7025-F50) IBM RS/6000 43P Model 150 (7043-150) Processor(s) 1 x 375 MHz PowerPC® 604e 1 x 450 MHz POWER3™ 2 x 332 MHz PowerPC 604™ 1 x 375 MHz PowerPC 604e System memory 512 MB 2 GB 1 GB 1 GB Disk space allocation /usr 2 GB /tmp 300 MB /home 100 MB / 100 MB /usr 4 GB /tmp 1 GB / 100 MB /home 100 MB /usr 2 GB DB2 /db2data 1 GB /home 100 MB / 100 MB Note: In our example, we created a separate file system for DB2 databases (db2data) /usr 2 GB /tmp 1 GB /home 100 MB / 100 MB Allocate file system space The Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems recommends the following file system space (assumes all software installed on a single node): /usr 4 GB /tmp 1 GB /home 1 GB (only necessary on DB2 Server system) Paging space 1 GB per CPU Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 681 To increase the size of a file system on AIX, enter the following command: # chfs -a size=’’ For example: # chfs -a size=’600000’ /tmp 18.2.4 Netscape 7 Web browser (optional) Within our test environment, we found it very useful to have the Netscape 7 for AIX (based on Mozilla). We downloaded Netscape 7 for AIX from the following URL: http://www-1.ibm.com/servers/aix/browsers/ Refer to the Web page for instructions on how to install. 18.2.5 AIX software prerequisites For a complete listing of software prerequisites, refer to the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems product guide. Required filesets The following filesets are required by WebSphere Application Server V5 and WebSphere Commerce V5.5. Nearly all packages listed are installed by default for the AIX 5.1 installation. X11.adt.lib X11.adt.motif (not installed by default) X11.base.lib X11.base.rte X11.motif.lib bos.adt.base bos.adt.include bos.rte.net bos.rte.libc bos.net.tcp.client Tip: Enter the following to check in the required filesets are installed: # lslpp -l X11.adt.motif WebSphere Commerce requires the X11.adt.motif (AIXWindows Application Development Toolkit Motif) fileset, which is not installed by default. It can be found on AIX 5.1 Installation CD 1. 682 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Install AIX 5.1 recommended maintenance package At the time of writing this redbook, we tested with AIX 5.1 maintenance level 4. WebSphere Commerce V5.5 officially supports AIX 5.1 maintenance level 2 or higher. In addition, WebSphere Commerce and supporting software require the following AIX 5.1 APARs; IY26221, IY29345, IY31254, IY32217, IY32905. One of the reasons we used AIX 5.1 maintenance level 4 is that it includes the WebSphere Commerce required AIX 5.1 APARs listed. Note: DB2 V8.1 UDB Enterprise Server Edition requires that following filesets be at a higher AIX 5.1 maintenance level 2: bos.rte.libc 5.1.0.27 bos.rte.libpthreads 5.1.0.26 We installed AIX 5.1 maintenance level 4, which includes the required AIX 5.1 APARs needed by WebSphere Commerce. To obtain and install the AIX 5.1 maintenance level 4 update, do the following: 1. Enter the following to download the maintenance package: https://techsupport.services.ibm.com/server/aix.fdc?toggle=DNLDML 2. Make the selection of the current level installed of AIX 5.1 and the desired maintenance level (4). Ensure you have enough space available to download and unpack the AIX 5.1 maintenance 4 file. Depending on which level of AIX 5.1 (maintenance level) you are starting with, the download file size will be different in size. 3. Download AIX 5.1 maintenance level 4, volume 1 510004.v1.tar.gz. IBM AIX 5.1 maintenance level 4 has been divided into two volumes: – Volume 1: Contains all the basic maintenance level updates that all customers will need to update to maintenance level 5100-04. The volume 1 download file name is 510004.v1.tar.gz. – Volume 2: Contains certain LOCALE updates that many customers will not require. The volume 2 file name is 510004.v2.tar.gz. To determine if you need volume 2, download the 510004.v1.tar.gz file to /usr/sys/inst.images. Complete the remainder of the install procedure. After installing the maintenance level 4 volume 1, enter oslevel -r. If the output is 5100-04, then you do not need volume 2. Note: In our example, we needed both volume 1 and 2. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 683 4. Extract the filesets from the package. The files are shipped as PTF numbers. This does not impede the installation process. # cd /usr/sys/inst.images # gzip -d -c 510004.v1.tar.gz | tar -xvf - 5. As a precaution, you should back up your system before installing the maintenance update. 6. Install the package by creating a table of contents (.toc) file for smitty install to use. Then update the install subsystem itself. Run smitty to complete the installation. # inutoc /usr/sys/inst.images # installp -acgXd /usr/sys/inst.images bos.rte.install # smitty update_all 7. Specify /usr/sys/inst.images as the input directory for software. 8. After the maintenance update is complete, shut down and restart your system. The maintenance package replaces critical operating system code. # shutdown -F -r now Note: After installing the AIX maintenance level 4, it may be necessary to open a new terminal window to run the shutdown command. 9. After system restart, verify that the update was applied successfully. Run the oslevel -r command. Depending on the output, do one of the following: – Output from oslevel -r is 5100-04 Your system has all the files it needs. Reboot your system. This maintenance package replaces critical operating system code. or – Output from oslevel -r is not 5100-04. You need to install maintenance level 4 volume 2 (510004.v2.tar.gz) Note: Repeat the documented process to install volume 2, 510004.v1.tar.gz. In our example, we needed to install volume 2. 18.2.6 Disable wsmserver on port 9090 WebSphere Commerce installer will check that port 9090 is not in use, since it is required for the WebSphere Application Server Administration Console. 684 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: A side effect of the AIX 5.1 maintenance level update is the adding of Web-based System Manager Administration to the /etc/services and /etc/inetd.conf. This causes a conflict on port 9090 with the WebSphere Application Server Administration Console (which will not start). To work around this problem, either change the port for the WebSphere Application Server Administration Console by following instructions in the WebSphere InfoCenter, or disable the AIX Web-based System Manager as follows (we chose this option): 1. Remove or comment out the /etc/services entry for the wsmserver on port 9090. # wsmserver 9090/tcp 2. Remove or comment out the /etc/inetd.conf entry for wsmserver: # wsmserver stream tcp now wait root /usr/websm/bin/wsmserver wsmserver -start 3. Stop and disable the wsmserver as follows: # /usr/websm/bin/wsmserver -disable 4. Verify that the wsmserver is no longer listening on port 9090, as follows: # netstat -an | grep 9090 The command should not return any text, which means nothing is listening on the port specified. The installation and base configuration for AIX are now complete. 18.3 Web Server node implementation This section describes how to install and configure the remote Web Server node used by WebSphere Commerce using the IBM HTTP Server V1.3.26 and WebSphere Application Server V5 plug-in. This section is organized as follows: AIX installation Installing IBM HTTP Server and WebSphere plug-in Configure the IBM HTTP Server 18.3.1 AIX installation Refer to 18.2, “AIX installation” on page 680 for details. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 685 18.3.2 Installing IBM HTTP Server and WebSphere plug-in To install the IBM HTTP Server V1.3.26 and the WebSphere Application Server V5.0 plug-in on the Web Server node, do the following: 1. Log on as user root and open an AIX Terminal window. 2. Ensure you have allocated file system space for Web Server. Refer to 18.2.3, “File system planning” on page 681 for details. 3. Ensure you have installed AIX 5.1 maintenance level 4. Refer to 18.2.5, “AIX software prerequisites” on page 682 for details. 4. Mount the IBM WebSphere Application Server V5.0, Advanced Edition CD-ROM. 5. Change to the cdrom mount point, and change to the AIX directory of the WebSphere Application Server. 6. From the command line, enter ./install to start the WebSphere Application Server InstallShield wizard. 7. When the Select a Language window appears, accept the default language (English) and click OK. 8. When the Welcome window appears, click Next. 9. When the Software License Agreement window appears, review the license and upon agreement select I Accept the terms and click Next. 10.The WebSphere Installation wizard will check the system requirements. This process may take a few minutes. Depending on the outcome of this checking, correct the necessary filesets if any or just click Next. 11.Select Custom when the Choose the setup type window appears and click Next. 12.We selected only the following options to install, and then clicked Next: – Select IBM HTTP Server Version 1.3.26 – Select Web Server Plugins, and check the IBM HTTP Server check box – Deselect all other options 13.On the following window, you can specify a different directory for installing the features you just selected in the previous step. In our example, we accepted the default, and clicked Next. 14.A confirmation window will appear. Click Next to begin the installation. This process will take a few minutes. 15.When the installation is finished, the Registration window appears. Deselect the check box if you do not want to register the product online and click Next. 686 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 16.At this point you have successfully installed the IBM HTTP Server V1.3.26 and the Web Server plug-in. Click Finish to close this window. 18.3.3 Configure the IBM HTTP Server In this section, we describe how to configure the IBM HTTP Server and enable SSL. We will manually configure the server to verify its functionality. This section is organized as follows: Create an administrator user and password Create the system user and group (optional) Configure the httpd.conf for SSL Create key store database Create a self-signed certificate Verify the IBM HTTP Server Note: Later when creating the WebSphere Commerce instance on the WebSphere Commerce node, the Configuration Manager will tell you that it will update and manage the httpd.conf changes. Create an administrator user and password Before the IBM HTTP Server Administration Server can be accessed, a user ID and password must be created using the htpasswd utility. For example: # cd /usr/IBMHttpServer/bin # ./htpasswd -cm ../conf/admin.passwd New password: Re-type new password: Create the system user and group (optional) The setupadm utility creates an operating system user (for example, httprun) that will run the IBM HTTP Server Administration Server processes, and also a group. This step is optional. If you choose to follow this step, you will need to change the ownership of files accordingly in later steps when configuring the WebSphere Commerce tools and store on the remote Web Server node. For example, we created the httpadm user and httpgrp group: # cd /usr/IBMHttpServer/bin # ./setupadm Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 687 Note: You will be prompted to confirm making changes and updating the IBM HTTP Administration Server configuration file. Select the appropriate options (option 1 in both cases) to go ahead and make the changes. After running this command, the files in the /usr/IBMHttpServer/conf directory will be owned by user root and group httpgrp. Later, we will add the non-root user wasuser for WebSphere Commerce Payments to the httpgrp group. This will allow for the non-root user wasuser to have write access to the httpd.conf. Configure the httpd.conf for SSL The default IBM HTTP Server httpd.conf does not include the commented out SSL directives. It is possible to add these manually, but we strongly advise you not to do this (Configuration Manager will not be able to update this file accordingly). We do recommend that you copy the httpd.conf.sample to httpd.conf. This version of the httpd.conf contains the commented-out SSL directives. As part of this procedure, we will uncomment the necessary entries to enable SSL in the httpd.conf. Note: If you do not want/need to test the remote Web server with SSL enabled, this step is optional. The WebSphere Commerce Configuration Manager will update the httpd.conf to SSL enable the file. Make sure that you are using a copy of the httpd.conf.sample containing the SSL directives. To enable the httpd.conf for SSL, do the following: 1. Open an AIX Terminal window. 2. Stop the IBM HTTP Server and IBM Administration Server if started: # /usr/IBMHttpServer/bin/apachectl stop # /usr/IBMHttpServer/bin/adminctl stop 3. Change to the configuration directory for the Web Server: # cd /usr/IBMHttpServer/conf 4. Back up the original httpd.conf to httpd.conf.org. 5. Copy the http.conf.sample to httpd.conf. This version of the httpd.conf contains the necessary entries for configuring SSL. 6. Edit the httpd.conf file and add these two lines at the end of the configuration file for the WebSphere plug-in (copy from the httpd.conf.org). LoadModule ibm_app_server_http_module /usr/WebSphere/AppServer/bin/mod_ibm_app_server_http.so WebSpherePluginConfig /usr/WebSphere/AppServer/config/cells/plugin-cfg.xml 688 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: The LoadModule line is wrapped. 7. Uncomment the lines listed to enable the httpd.conf for SSL and update them accordingly. ServerName webaix1.itso.ral.ibm.com LoadModule ibm_ssl_module libexec/mod_ibm_ssl_128.so Note: Where 128 is the appropriate encryption level for your locale, for example 128 for 128-bit encryption in the US and Canada. AddModule mod_ibm_ssl.c Listen 443 Note: You must substitute your fully qualified host name in this line (for example, ). SSLEnable SSLDisable Keyfile /usr/IBMHttpServer/ssl/keyfile.kdb Note: The sample Keyfile path includes in the directory keys, which must be changed to ssl. The value of the Keyfile parameter is the absolute path to the CMS format keystore database file of your choosing. In this example we assume that a keyfile.kdb file is created in the ssl subdirectory of the IBM HTTP Server installation (for example, /usr/IBMHttpServer/ssl). SSLV2Timeout 100 SSLV3Timeout 1000 8. Save the httpd.conf file and close it. Create key store database To create a new key store database used to manage certificates, do the following: 1. Open an AIX Terminal window. 2. Change to the following directory: # cd /usr/IBMHttpServer/bin Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 689 3. Set console. a. On the WebSphere Commerce node, set the authorization for X client (host name) to access the X server where WebSphere Commerce will be installed. # xhost b. Export the DISPLAY as follows: # export DISPLAY=:0.0 Where is the host name of the system from which you will be running the installation (could be from a remote node). 4. Run the IBM Key Management tool by typing: # ./ikeyman 5. In the IBM Key Management window select Key Database File and then select New. 6. Leave the default for Key database type (CMS key database file). 7. Change the file name to keyfile.kdb. 8. Change the location to /usr/IBMHttpServer/ssl and click OK. 9. Set a password for the key database file you are creating and select Stash the password to a file? check box and click OK. 10.An information window appear, click OK. Create a self-signed certificate This section describes how to create a self-signed certificate in order to enable SSL for the Web Server node. In a production environment, a real certificate should be requested from a company such as VeriSign. 1. From the Key Management Utility menu, select Create -> New Self-Signed Certificate. 2. The Create New Self-Signed Certificate window appears. We entered the following and then clicked OK (if not specified, we accepted the default): – Key label: http_ssl – Common name: webaix1.itso.ral.ibm.com – Organization: ibm 3. Provide a Key Label, Common Name and Organization, leave the other values as the default, and click OK. 4. Exit from the IBM Key Management tool by selecting Key Database File and then Exit. 690 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Verify the IBM HTTP Server After configuring the IBM HTTP Server, we recommend that you verify the server as follows: 1. Change to the Web Server bin directory: # cd /usr/IBMHttpServer/bin 2. Start the Web Server by typing the following: # ./apachectl start 3. From a Web browser access the Web Server: http:// https:// 18.3.4 Install WebSphere Application Server V5 fixes Refer to 18.5.7, “Install WebSphere Application Server V5 fixes” on page 710 for details. The Web Server node will need to adhere to the rules following sections: “Update Installer for WebSphere Application Server V5.0” on page 711 “Web server fixes” on page 712 18.4 DB2 Server node implementation This section describes how to install IBM DB2 Universal Database V8.1, Enterprise Server Edition on the DB2 Server node for the AIX three-tier runtime environment. We will describe the components of DB2 V8.1 that are required to be installed for WebSphere Commerce and provide tips and best practices within the installation and configuration procedures. This section is organized as follows: AIX installation Install DB2 UDB V8.1 Enterprise Server Edition Install DB2 UDB V8.1 Fix Pack 1 Create a file system for DB2 databases (optional) 18.4.1 AIX installation Refer to 18.2, “AIX installation” on page 680 for details. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 691 18.4.2 Install DB2 UDB V8.1 Enterprise Server Edition To install the DB2 UDB V8.1 Enterprise Server Edition on the DB2 Server node, do the following: 1. Log on as user root and open an AIX Terminal window. 2. Ensure you have allocated file system space for the DB2 Server. Refer to 18.2.3, “File system planning” on page 681 for details. 3. Ensure you have installed AIX 5.1 maintenance level 4. Refer to 18.2.5, “AIX software prerequisites” on page 682 for details. 4. Ensure you have allocated file system space for DB2. 5. Mount the DB2 CD-ROM. Change to the cdrom mount point. 6. From the command line, enter ./db2setup to start the DB2 Setup wizard. 7. From the Welcome to DB2 window, click Install Products. 8. When the Select Product to Install window appears, select DB2 UDB Enterprise Server Edition. 9. When the Welcome window appears, click Next. 10.When the License Agreement window appears, review the agreement and select Accept and click Next. 11.When the Type of Installation window appears, select Custom Install and then click Next. 12.When the Select the Installation Action window appears, check Install DB2 UDB Enterprise Server Edition on this computer and then click Next. Note: Select the Save your setting in a response file check box to capture your selection options for use in a future installation. When selecting Custom Install, by default most of the installation options are set to be installed. 13.When the Select the Features to Install window appears, do the following and then click Next: – Check Server Support (accept default) – Check Client Support (accept default) – Check Administration Tools (accept default) This includes the Configuration Assistant, Control Center, and DB2 Instance Setup wizard. – Check Application Development tools (Base Application Development Tools used to load stored procedures) 692 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – Uncheck Business Intelligence This option is needed for WebSphere Commerce Analyzer. – Check Getting started (default - optional) This option may be useful to install if you are experimenting and have plenty of disk space. Note: The options selected require approximately 515 MB of disk space. 14.When the Languages to Install window appears, select the desired language (for example, English), and click Next. 15.When the Set User Information for DB2 Administration Server window appears, enter the following and then click Next: – – – – – – – – Select New User User name: dasusr1 UID: check Use Default UID Group name: dasadm1 GID: check Use Default GID Password: Confirm password: Home directory: /home/dasusr1 16.When the Create a DB2 instance window appears, select Create the DB2 instance and then click Next. 17.When the Select How the Instance Will Be Used window appears, select Single-partition instance and then click Next. 18.When the Set User Information for DB2 Instance Owner window appears, enter the following and then click Next: – – – – – – – – Select New User User name: db2inst1 UID: check Use Default UID Group name: db2grp1 GID: check Use Default GID Password: Confirm password: Home directory: /home/db2inst1 19.When the Set User Information for the Fenced User window appears, enter the following and then click Next: – Select New User – User name: db2fenc1 – UID: check Use Default UID Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 693 – – – – – Group name: db2fgrp1 GID: check Use Default GID Password: Confirm password: Home directory: /home/db2fenc1 20.When the Configure DB2 Instance TCP/IP configuration window appears, enter the following and then click Next: – Select Configure – Service name: db2c_db2inst1 – Port number: 50000 Note: The service name and port number are written to the /etc/services file. 21.When the Set Instance properties window appears, we accepted the default Authentication Type Server, checked Autostart the instance at system startup, and then clicked Next. 22.When the Prepare the DB2 tools catalog window appears, we accepted the default, Do not prepare the DB2 tools catalog on this computer, and clicked Next. 23.When the Set up the Administration Contact List window appears, we selected Local - Create a contact list on this system, unchecked Enable Notification (SMTP) and clicked Next. 24.You will get a warning message about Notification SMTP server. Click OK. 25.When the Specify a Contact for Health Monitor Notification window appears, select Defer the task after installation is complete, and then click Next. 26.When the Start copying files window appears, review the selected options and then click Finish. You should see a progress indicator window. This installation takes approximately 20-30 minutes to install depending on the specs of the hardware. 27.When the Setup is Complete window appears, review the log information found in the Status Report tab and click Finish. 694 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 18.4.3 Install DB2 UDB V8.1 Fix Pack 1 Note: The IBM DB2 UDB V8.1 (8.1.1.8) shipped with WebSphere Commerce V5.5 includes Fix Pack 1. Therefore, it is not necessary to install DB2 V8.1 Fix Pack 1. This is only necessary for customers using the IBM DB2 UDB V8.1 GA CDs. To download and install IBM DB2 UDB V8.1 Fix Pack 1, do the following: 1. Enter the following URL to download DB2 UDB V8.1 Fix Pack 1 to a temporary directory: ftp://ftp.software.ibm.com/ps/products/db2/fixes/english-us/db2aix5v8/fixpa k/FP1_U486246/ 2. Unpack the FP1_U486246.tar.Z file as follows: # gzip -d -c FP1_U486246.tar.Z | tar -xvf - 3. Refer to the FixpakReadme.txt for details on this installation. 4. In summary, we did the following: a. For each DB2 instance (db2inst1 is the instance owner), enter: # $ $ $ $ $ $ su - db2inst1 . $HOME/sqllib/db2profile db2 force application all db2 terminate db2stop db2licd -end exit b. For the administration server instance (dasusr1 is the instance owner for the administrative server), enter: # su - dasusr1 $ db2admin stop $ exit c. On AIX, you should also run, as root, slibclean to unload unused shared libraries from memory before installing this fix pack: # /usr/sbin/slibclean d. Change to the Fix Pack unpack directory. Start the DB2 FixPak installer as follows: # ./installFixPak e. Review the Fix Pack 1 installation log. f. Update DB2 instances to the fix level: # /usr/opt/db2_08_01/instance/db2iupdt iname Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 695 Where iname represents the instance name (db2inst1). g. Run the dasupdt command if the database administration server (DAS) instance exists and is a DB2 Version 8 DAS instance. To update the DAS instance, issue the command: # /usr/opt/db2_08_01/instance/dasupdt dasname Where dasname represents the DAS (dasusr1). h. Restart the DB2 instance. # su - db2inst1 $ db2start i. Rebind the bind file. Refer to FixpakReadme.txt for details. 18.4.4 Create a file system for DB2 databases (optional) It is desirable to have a separate file system for the application database to avoid a situation where other applications use file system space needed by the database(s). This step is not required. By default, users are expected to increase the /home file system, which contains all user directories and will be the default location where databases are created. Create a separate file system for DB2 databases In our scenario, we created a separate file system for the databases by implementing the following high-level steps: A new volume group, datavg, on physical volume hdisk3, using 16 MB physical partitions A new 1 GB logical volume, db2lv, within datavg A new 512 MB JFS file system, /db2data, within db2lv A new subdirectory db2inst2 in /db2data, to be owned by the DB2 instance owner The /home file system must still have sufficient capacity (at least 20 MB for each DB2 instance), but will not need to be expanded to 1 GB. Changes to system storage can only be performed by the root user. For detailed steps see Appendix A, “AIX tips” on page 961. Alternatively, the following example sequence of equivalent commands can be used: 1. Create a volume group (alternatively, use the rootvg volume group): # mkvg -f -y ’datavg’ -s’16’ hdisk3 Note: In our scenario, we used rootvg. 696 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 2. Create a logical volume: # mklv -y ’db2lv’ 1 Where is your volume group name. In our example, we used rootvg. 3. Create a JFS file system on a previously defined logical volume: # crfs -v jfs -d ’db2lv’ -m ’/db2data’ -A yes 4. Mount the file system: # mount /dev/db2lv /db2data 5. Allocate space to the file system: # chfs -a size=’2000000’ /db2data The size is measured in 512-KB blocks (for example, 2000000 is approximately 1 GB). 6. Verify the file system is mounted and the space is allocated: # df -k 7. Create a directory on the file system called db2inst1: # cd /db2data # mkdir db2inst1 8. Change ownership of the file system: # chown -R db2inst1:db2grp1 db2inst1 Update DB2 default database path to use the new file system The database manager for each DB2 instance has a default database path parameter (dftdbpath), which defaults to the home directory of the instance owner. 1. Log in as the DB2 instance owner and issue an update database manager configuration command, to assign the new directory to this parameter: # su - db2inst1 $ db2 update dbm cfg using dftdbpath /db2data/db2inst1 2. The new setting will not take effect until DB2 has been restarted. It can be checked by the get database manager configuration command: $ $ # $ $ $ db2 get dbm cfg | more exit su - db2inst1 db2 force applications all db2 terminate db2stop Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 697 Note: When performing this series of commands, we sometimes needed to restart the system to resolve an inconsistency problem with DB2. Start DB2 As the DB2 instance owner, restart DB2 with the db2start command. # su - db2inst1 $ db2start Create test database After makeing the changes outlined in this section, we recommend that you create a test database and then list the directory in which it was created to verify the configuration. 1. Create the test database: # su - db2inst1 $ db2 create db test 2. List the database and check to see location of database. $ db2 list db directory It should be listed in the /db2data/db2inst1 directory as per the example. 18.5 WebSphere Commerce Payments node implementation This section describes the installation and configuration of the WebSphere Commerce Payments node for the AIX three-tier scenario, including the following software components: IBM DB2 Universal Database V8.1, Enterprise Server Edition client IBM WebSphere Application Server V5.0, Advanced Edition IBM HTTP Server V1.3.26 IBM WebSphere Commerce V5.5, Business Edition – Configuration Manager used to create WebSphere Commerce Payments instance – WebSphere Commerce Payments We will use a combination of manual install and the WebSphere Commerce V5.5 installer. After the software components are installed, we will create the WebSphere Commerce Payments instance. 698 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: In our example, we installed the DB2 client on the WebSphere Commerce Payments node and the payments database will reside on the DB2 Server node. You may decide to install the DB2 Server on the WebSphere Commerce Payments node and create the payments database local to that node. This section is organized as follows: AIX installation Install DB2 UDB V8.1 Client Configure and verify the DB2 client and server Create the non-root user(s) Install WebSphere Commerce Payments software Verify the WebSphere Commerce Payments installation Install WebSphere Application Server V5 fixes Verify the WebSphere Application Server Modify the owner and file permissions of the httpd.conf Create the WebSphere Commerce Payments instance Configure the IBM HTTP Server Verify WebSphere Commerce Payments instance 18.5.1 AIX installation Refer to 18.2, “AIX installation” on page 680 for details. 18.5.2 Install DB2 UDB V8.1 Client In our example, the WebSphere Commerce Payments database will reside on the DB2 Server node. We will install the DB2 Client on the WebSphere Commerce Payments node. We chose to manually install and configure the DB2 Cient so that we could verify the connection with the DB2 Server prior to the WebSphere Commerce installation. Install DB2 UDB V8.1 Client To install the DB2 UDB V8.1 Client, do the following: 1. Log on as user root and open an AIX Terminal window. 2. Ensure you have allocated file system space for DB2. 3. Ensure you have installed AIX 5.1 maintenance level 4. 4. Mount the DB2 CD-ROM. Change to the cdrom mount point. 5. From the command line, enter ./db2setup to start the DB2 Setup wizard. 6. From the Welcome to DB2 window, click Install Products. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 699 7. When the Select product to install window appears, select DB2 Administration Client. 8. When the Welcome window appears, click Next. 9. When the License Agreement window appears, review the agreement and select Accept and click Next. 10.When the Type of Installation window appears, select Custom Install and then click Next. 11.When the Select the Installation Action window appears, check Install DB2 Administration Client on this computer and then click Next. Note: Take note of the Save your setting in a response file check box. This can be used to capture your selection options to be used for a future installation. When selecting Custom Install, by default most of the installation options are set to be installed. 12.When the Select the Features to Install window appears, do the following and then click Next: – Check Client Support (accept default) – Check Administration Tools (accept default) This includes the Configuration Assistant, Control Center, and DB2 Instance Setup wizard. – Uncheck Business Intelligence This option is needed for WebSphere Commerce Analyzer. – Check Getting started (default - optional) This option may be useful to install if you are experimenting and have plenty of disk space. Note: The options selected require approximately 203 MB of disk space. 13.When the Languages to Install window appears, select the desired language (for example, English), and click Next. 14.When the Setup a DB2 Instance window appears, select Create a DB2 instance - 32 bit, and then click Next. 15.When the Set User Information for DB2 Instance Owner window appears, enter the following and then click Next: – Select New User – User name: db2inst1 – UID: check Use Default UID 700 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – – – – – Group name: db2grp1 GID: check Use Default GID Password: Confirm password: Home directory: /home/db2inst1 16.When the Start copying files and create response file window appears, review the settings, and then click Finish. The DB2 installer will begin copying files. 17.When the Setup is Complete window appears, review the log information found in the Status Report tab and click Finish. Install DB2 V8.1 Fix Pack 1 Note: The IBM DB2 UDB V8.1 (8.1.1.8) shipped with WebSphere Commerce V5.5 includes Fix Pack1. Therefore, it is not necessary to install DB2 V8.1 Fix Pack 1. This is only necessary for customers using the IBM DB2 UDB V8.1 GA CDs. To install the DB2 V8.1 Fix Pack 1, refer to 18.4.3, “Install DB2 UDB V8.1 Fix Pack 1” on page 695 for details. 18.5.3 Configure and verify the DB2 client and server After installing the DB2 Administration Client, configure the DB2 client on the WebSphere Commerce Payments node for use with the DB2 Server node. The high-level configuration steps are as follows: 1. Add DB2 Server connection port to the /etc/services file on the WebSphere Commerce Payments node. For example, add the following to /etc/services: db2c_db2inst1 50000/tcp #Connection port for DB2 instance db2inst1 2. Catalog the tcpip node as follows: # su - db2inst1 $ db2 catalog tcpip node db2aix1 remote db2aix1 server db2c_db2inst1 Where db2aix1 is the node name and the remote DB2 Server, and db2c_db2inst1 is the connection port defined in /etc/services for the DB2 Server. 3. Attach to the remote DB2 Server to verify the connection. # su - db2inst1 $ db2 attach to db2aix1 user db2inst1 using $ exit Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 701 18.5.4 Create the non-root user(s) To reduce security risk, it is advisable to run applications servers such as WebSphere Commerce and WebSphere Commerce Payments as a non-root user. This section explains how to create the non-root user(s) and groups and what they are used for. Note: Refer to the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems for more detailed information. We will create two separate non-root users and groups: Create the non-root user for WebSphere MQ WebSphere MQ messaging requires non-root user mqm, and groups mqm and mqbrkrs. This is needed because of a hardcoded requirement of the MQ embedded messaging included with WebSphere Application Server V5 when running as non-root. If the WebSphere Application Server had been installed via smitty on AIX, this step would have been done automatically for a non-root user installation. In our example, the WebSphere Commerce installer used the WebSphere Application Server response file-driven installation, which does not have the ability to create the non-root user mqm. Create the non-root user for WebSphere application servers We created the non-root user wasuser and group wasgroup. During the WebSphere Commerce installation (including Payments), you will be prompted to provide the non-root user and group which the WebSphere Commerce or WebSphere Commerce Payments application servers for configuration and startup. Note: The non-root users and groups must be created before the WebSphere Commerce installer is executed. The WebSphere Commerce installer will perform a prereq check to verify the non-root user(s) and groups exist before allowing you to proceed during the installation. Create the non-root user for WebSphere MQ To create the user mqm, and groups mqm and mqbrkrs required by the WebSphere MQ messaging when running the WebSphere Application Server as non-root, do the following: 1. Log on as user root and open an AIX Terminal window. 2. Create groups mqm and mqbrkrs by typing the following: # mkgroup mqm # mkgroup mqbrkrs 702 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 3. Add user root to the mqm and mqbrkrs user groups using smitty. 4. Create the non-root user mqm, add to primary group mqm, set the home directory to /home/mqm. We performed this step using smitty. 5. Set default password for user mqm. When creating a user, the password is set to * (for invalid). It is necessary to set the password. To change the mqm password, type the following: # passwd mqm Changing password for “mqm ” mqm’s New password: Enter the new password again: 6. Change the mqm initial logon password. During the initial user logon, the user will be prompted to change a password. To change the initial logon password, type the following: # login mqm mqm’s Password: mqm’s New password: Enter the new password again: exit 7. Change ownership of /home/mqm file system to user mqm and group mqm by typing the following: # chown -fR mqm:mqm /home/mqm 8. Verify file system ownership (mqm:mqm): # ls -la /home/mqm Create the non-root user for WebSphere application servers To create the non-root user and groups used to configure and start WebSphere application servers, such as WebSphere Commerce and WebSphere Commerce Payments, do the following: 1. Log on as user root and open an AIX Terminal window. 2. Create group wasgroup by typing the following: # mkgroup wasgroup 3. Add user root to the group wasgroup using smitty. 4. Create the non-root user wasuser, add to the primary group wasgroup, set the home directory to /home/wasuser using smitty. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 703 5. Set the default password for user wasuser. When creating a user, the password is set to * (for invalid). It is necessary to set the password. To change the wasuser password, type the following: # passwd wasuser Changing password for “wasuser” wasuser’s New password: Enter the new password again: 6. Change the wasuser initial logon password. During the initial user logon, the user will be prompted to change a password. To change the initial logon password, type the following: # login wasuser wasuser’s Password: wasuser’s New password: Enter the new password again: exit 7. Change the ownership of /home/wasuser file system to user wasuser by typing the following: # chown -fR wasuser:wasgroup /home/wasuser 8. Verify file system ownership (wasuser:wasgroup): # ls -la /home/wasuser 18.5.5 Install WebSphere Commerce Payments software In our example, we will use the WebSphere Commerce installer to install the following software components: WebSphere Application Server IBM HTTP Server WebSphere Commerce Configuration Manager WebSphere Commerce Payments To install WebSphere Commerce Payments and supporting software using the WebSphere Commerce installer on the WebSphere Commerce Payments node, do the following: 1. Log on as user root and open an AIX Terminal window. 2. Ensure you have done the following: – – – – 704 Installed prerequisite AIX filesets Installed AIX 5.1 maintenance level 4 Allocated file system space Created the non-root user(s) WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 3. From the AIX Terminal window, export the display. In a UNIX environment, it is common for the systems to be in racks or located remotely from the console of the administrator. This step allows for the installation of software on the target node (WebSphere Commerce Payments node) from a remote console by setting the remote console display as follows: a. On the WebSphere Commerce node, set the authorization for X client (host name) to access the X server where WebSphere Commerce will be installed. # xhost b. Export the DISPLAY as follows: # export DISPLAY=:0.0 Where is the host name of the system from which you will be running the installation (could be from a remote node). 4. Insert the WebSphere Commerce CD 1 and mount the CD drive. For example: # mount -r -v cdrfs /dev/cd0 /mnt 5. Enter the following command to start the WebSphere Commerce installer: # /mnt/setup_aix Important: It is is very important that you do not change to the mount point (for exmaple, /mnt) and then run the WebSphere Commerce installer (setup_aix). Do not type the following: # cd /mnt # ./setup_aix If you change to the mount point and then run the installer setup_aix, the CD will be in use (busy) and you will not be able to insert the supporting software CDs during the installation. 6. We selected English and then clicked OK. 7. When the Welcome window appears, click Next. 8. Review the license agreement, select I accept the terms of the license agreement, and then click Next. 9. When the Choose the installation Type Best Suited for your Needs window appears, select Custom installation and then click Next. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 705 10.When the Choose the components to install on this node window appears, we did the following and then clicked Next (see Figure 18-2 on page 707): WebSphere Commerce components: – Uncheck WebSphere Commerce Server, including WebSphere Application Server base product – Uncheck WebSphere Commerce example files (optional for production) – Uncheck WebSphere Commerce online help (optional for production) – Check WebSphere Commerce Payments, including WebSphere Application Server base product In our example, we will install a separate WebSphere Commerce Payments node. – Check Remote WebSphere Commerce Configuration Manager client Supporting software: – Uncheck DB2 Universal Database (not applicable for OS/400 users) In our example, DB2 Server is installed on a remote DB2 Server node so this option is not needed. The DB2 client will be installed automatically if this option is not selected, which is not obvious from the window text. – Check IBM HTTP Server, including WebSphere Application Server plug-in (not applicable for OS/400 users) In our example, the IBM HTTP Server is installed on a remote node. – Uncheck WebSphere Application Server Web server plug-in 706 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 18-2 WebSphere Commerce component selections for remote Payments node 11.When the Choose the database and Web server the WebSphere Commerce will Use window appears, we did the following and then clicked Next: – Select Web server: IBM DB2 Universal Database (default) – Select Web server: IBM HTTP Server (default) Important: If you see an error message stating that port 9090 is in use, take corrective action as follows: In our example, we noticed that the /etc/services file contained an entry for wsmserver on port 9090 (AIX Web-based Systems Management). This was added as a side effect to the AIX 5.1 maintenance level update. Refer to 18.2.6, “Disable wsmserver on port 9090” on page 684 to work around this problem and then restart the WebSphere Commerce installer. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 707 12.When the Enter the destination paths or accept the default paths window appears, we accepted the following default paths and then clicked Next (see Figure 18-30). Take note of disk space required and available. – IBM HTTP Server destination path: /usr/IBMHttpServer – IBM WebSphere Application Server destination path: /usr/WebSphere/AppServer – IBM WebSphere Commerce Server destination path: /usr/WebSphere/CommerceServer55 Figure 18-3 WebSphere Commerce install diskspace required and paths for remote Payments node 708 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: If you do not have enough free space, the WebSphere Commerce installer will not let you continue. Exit the installer, increase file system space for /usr for the options desired and file system space needed (see Figure 18-5 on page 729). Once you have increased the file system space accordingly, restart the WebSphere Commerce installer. 13.When the Enter the database user ID and password window appears, we entered the following and then clicked Next: – – – – – Database user ID: db2inst1 Database user Password: Verify database user password: Database user group: db2grp1 Database user home directory: /home/db2inst1 14.When prompted for the language for online help, we checked English and then clicked Next. 15.When the Enter the non-root user ID information for WebSphere Commerce application server (and WebSphere Commerce Payments) window appears, we entered the following and then clicked Next: – Non-root user ID: wasuser – Non-root user Group: wasgroup – Full path to the user ID’s home directory: /home/wasuser Important: The WebSphere Commerce installer will fill in the sample values of wasuser and wasgroup for the non-root user. We accepted these default values. This non-root user was created in “Create the non-root user for WebSphere application servers” on page 703. 16.When the Confirm your installation options and parameters window appears, review the settings and then click Next: 17.When prompted to insert the WebSphere Application Server CD, you will need to unmount the exising CD, insert and mount the WebSphere Application Server CD, and then click Next. Note: In a separate window, we mounted the CD-ROM, removed the WebSphere Commerce CD, and inserted and mounted the WebSphere Application Server CD. If you are installing from a local file system (shared drives not supported by the installer), you must enter the path for the WebSphere Commerce installer to recognize the directory structure of the CD image. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 709 Important: We noticed that there is no Back button displayed on the insert installation media window. In our case, we wanted to go back and change our settings and found we could not do so. The only option available is to click Cancel and exit the installation and start over. 18.When prompted to insert the WebSphere Commerce CD 1, you will need to unmount the existing CD, insert and mount the WebSphere Commerce CD, and then click Next. 19.When prompted to insert the WebSphere Commerce CD 2, you will need to unmount the exising CD, insert and mount the WebSphere Commerce CD, and then click Next. 20.When the installation is complete, you will see a message “The Install Wizard has successfully install IBM WebSphere Commerce”. Click Next. 21.When the Installation Complete window appears, click Finish. 18.5.6 Verify the WebSphere Commerce Payments installation After the WebSphere Commerce installation, we recommend that you review the WebSphere Commerce installation and supporting software logs prior to creating the WebSphere Commerce instance. Note: Refer to the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems for more information. In summary, verify the installation of WebSphere Commerce by checking the following log files: Review the /usr/WebSphere/AppServer/logs/log.txt. Search for the message “The WebSphere 5.0 install is complete”. Review the /usr/WebSphere/CommerceServer55/logs/install_.log Search for the message “WebSphere Commerce installation complete”. 18.5.7 Install WebSphere Application Server V5 fixes After the installation, refer to the WebSphere Commerce Readme file for selected WebSphere Application Server fixes that need to be installed. In summary you will need to install the following WebSphere Application Server V5 fixes: Update Installer for WebSphere Application Server V5.0 Web server fixes 710 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide WebSphere Application Server fixes Update Installer for WebSphere Application Server V5.0 The Update Installer is the tool used to install updates (interim fixes and fix packs) to WebSphere Application Server V5.0.x. We will use the Update Installer to install the other listed fixes for WebSphere Application Server V5.0 that are required by WebSphere Commerce V5.5. The IBM WebSphere Application Server V5.0 Update Installer can be downloaded from the following URL: http://www.ibm.com/software/webservers/appserv/was/support/ Note: Do not use the Update Installer found on WebSphere Commerce CD 2. The Readme file for the Update Installer is over 70 pages describing many usage scenarios. The Update Installer is available to run as a GUI using the wizard, or from the command line using a Silent install. In a nutshell we did the following to download and run the WebSphere Application Server V5 Update Installer: 1. Create a download directory for the Update Installer. # mkdir -p /usr/WebSphere/AppServer/update 2. Download Update Installer - AIX and Readme file (updateInstaller.zip, readme_updateinstaller.html) to the /usr/WebSphere/AppServer/update directory from the following URL: http://www.ibm.com/software/webservers/appserv/was/support/ 3. Unpack the updateInstaller.zip as follows: # unzip updateInstaller.zip Note: We downloaded the unzip utiltiy from the following URL: http://aixpdslib.seas.ucla.edu/packages/unzip.html 4. Change the file permissions on the installer.jar: # chmod 755 installer.jar 5. Create a directory to copy the fixes. The following directories are recommended: # mkdir -p /usr/WebSphere/AppServer/update/fixes # mkdir -p /usr/WebSphere/AppServer/update/fixpacks 6. Copy the fixes from the WebSphere Commerce CD 2 to the /usr/WebSphere/AppServer/update/fixes directory. Note: See details below for which WebSphere Application Server fixes are needed for the target node. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 711 7. To run the Update Installer do the following: a. Ensure each base node and application server is stopped: # /usr/WebSphere/AppServer/bin/stopNode.sh # /usr/WebSphere/AppServer/bin/stopServer.sh server1 b. Set up the command line, as follows: # /usr/WebSphere/AppServer/bin/setupCmdLine.sh c. To run the Update Installer wizard (GUI), type the following: # cd /usr/WebSphere/AppServer/update # ./updateWizard.sh Note: At the time of writing, we found the browse window in the Update Installer to be clumsy. We suggest typing the path directly to where the fix to be installed is located. Alternatively, when using browse enter . in the filename field of the browse window. If you do not enter something in the Filename field, you will not be able to continue. Web server fixes Ensure that you install the following fixes on the Web Server node containing the IBM HTTP Server and WebSphere Application Server V5 plug-in before using WebSphere Commerce: PQ70166 - Interim fix for IBM HTTP Server unable to start session ID caching daemon. This applies to AIX, SunOS/Solaris, Linux Intel, and Linux S/390. For more information, refer to PQ70155_Readme.txt. Note: To install the fix for the IBM HTTP Server, do the following: 1. You will need to unpack the PQ70166_AIX.tar.Z file to a temporary directory, such as /tmp, before the Update Installer can see the fix. For example: # gzip -d -c PQ70166_AIX.tar.Z | tar -xvf - 2. Stop the IBM HTTP Server. 3. Back up the original /usr/IBMHttpServer/libexec/mod_ibm_ssl_128.so. 4. Copy the mod_ibm_ssl_128.so to the /usr/IBMHttpServer/libexec directory. 5. Verify the file size is that of the new file in the stated directory. 6. Restart the IBM HTTP Server. 712 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide PQ73005 - Interim fix to add parameter to specify the chunk size for reading the response body. This fix is needed for all supported Web servers and includes many plug-in fixes. For more information, refer to PQ73005_Readme.txt. Use the Update Installer to install this fix. Note: The fixes and Readme file can be found on WebSphere Commerce CD 2 in the /Software_Patches/WAS/repository directory. WebSphere Application Server fixes Ensure that you install the following fixes, using the WebSphere Application Server V5.0.x Update Installer, on the node where WebSphere Commerce and WebSphere Commerce Payments are installed: PQ73004 - Interim fix to update the mapping of users for an application in the WebSphere Adminstration Console. The changes are not saved to the ibm-application-bnd.xmi. For more information, refer to the PQ73004_readme.txt. PQ74316 - Interim fix for a Null pointer in WebAppRequestDispatcher. For more information, refer to PQ74316_readme.txt. Note: The fixes and Readme file can be found on WebSphere Commerce CD 2 in the /Software_Patches/WAS/repository directory. 18.5.8 Verify the WebSphere Application Server To verify the functionality of the WebSphere Application Server after installation, we will use the First Steps (firststeps.sh) script. To start WebSphere First Steps, do the following: 1. Set the xhosts host name: # xhost wcaix1 2. Log on as the non-root user wasuser, export the DISPLAY, and change to the /usr/WebSphere/AppServer/bin directory, as follows: # su - wasuser $ export DISPLAY=wcaix1:0.0 $ cd /usr/WebSphere/AppServer/bin Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 713 Important: It is critically important that you log on as the non-root user (for example, wasuser) before you start server1 or other application servers the first time. During the first startup of an application server, files and directories get created. For example, if you forget to log on as non-root user wasuser and are logged in as root, all the directories and files will be owned by root. When you attempt to start the server in subsequent attempts when logged in as wasuser, the server will fail to start due to initialization failure. If you make this mistake, you will have to manually change ownership of the following directories and files as follows: chown -R root:wasgroup /usr/WebSphere/AppServer/logs chown root:wasgroup /usr/WebSphere/AppServer/mqjms.trc chown -R wasuser:wasgroup /usr/WebSphere/AppServer/tranlog/server1 3. Start First Steps as follows: $ ./firststeps.sh 4. From the WebSphere Application Server First Steps window, select Start Server. This will start server1 and verify a connection to the server. Note: Review the status of the server startup in the startServer.log: # tail -f /usr/WebSphere/AppServer/logs/server1/startServer.logs You should see the following message: Server server1 open for e-business The /server1 directory will not get created until the first time the application server is started. 5. From the WebSphere Application Server First Steps window, select Verify Installation. 6. Start the WebSphere Application Server Adminstration Console by entering the following URL in a Web browser: http://:9090/admin 7. Log on to the WebSphere Administration Console (for example, admin). 8. When done verifying the WebSphere Administration Console, log out, close the Web browser, and stop server1 as follows: # su - wasuser $ cd /usr/WebSphere/AppServer/bin $ ./stopServer.sh server1 714 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 18.5.9 Modify the owner and file permissions of the httpd.conf In the following section, we will create the WebSphere Commerce Payments instance using the WebSphere Commerce Configuration Manager. As per the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems, the Configuration Manager is started by the non-root user created in “Create the non-root user for WebSphere application servers” on page 703 (for example, wasuser). The Configuration Manager will attempt to modify the httpd.conf file to configure SSL and add aliases and other directives. If the non-root user wasuser does not have permissions to write to the httpd.conf, the WebSphere Commerce Payments instance will not get created correctly. Important: If the non-root user does not have file permissions to write to the httpd.conf, then the WebSphere Commerce Payments instance creation will fail. To verify the non-root user wasuser has write permissions to the httpd.conf file, do the following: 1. Log on as user root and open an AIX Terminal window. 2. Change to the IBM HTTP Server directory where the httpd.conf exists: # cd /usr/IBMHttpServer/conf 3. List the httpd.conf file to check the owner of the file (user:group): # ls - l httpd.conf 4. To work around the problem of not being able to write to the httpd.conf, we will need to change ownership of this file. In our example, we added the non-root user wasuser created during the WebSphere Commerce Payments installation to the httpgrp. Add the wasgroup to be the owner of the /usr/IBMHttpServer/conf/httpd.conf file: # chown root:wasgroup /usr/IBMHttpServer/conf/httpd.conf 5. Change the file permissions for the httpd.conf to include write permission for the wasgroup, which wasuser is a part of. # cd /usr/IBMHttpServer/conf # chmod 664 httpd.conf 6. Verify that you can log on with the wasuser, and write to the httpd.conf file. # su - wasuser $ cd /usr/IBMHttpServer/conf $ vi httpd.conf Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 715 Test that you can save the httpd.conf file when logged on as wasuser. 18.5.10 Create the WebSphere Commerce Payments instance To create the WebSphere Commerce Payments instance, do the following: 1. Ensure the DB2 Server is started. 2. Ensure you have installed the fixes listed in 18.5.7, “Install WebSphere Application Server V5 fixes” on page 710 (requirement of the WebSphere Commerce V5.5 Readme file). 3. Log on as user root and open an AIX Terminal window. 4. Start the Configuration Manager server as the non-root user created during the WebSphere Commerce Payments installation. # su - wasuser $ cd /usr/WebSphere/CommerceServer55/bin $ ./config_server.sh You should see the following messages: Registry created. CMServer bound in registry. Note: If the Configuration Manager Server is listening on a different port from the default (1099), then specify the port when starting the server as follows: ./config_server.sh -port 5. Start the Configuration Manager Client. In a UNIX environment, it is common for the systems to be rack mounted and/or located remotely from the console of the administrator. This step allows for the installation of software on the target node (WebSphere Commerce Payments node) from a remote console by setting the remote console display as follows: a. On the WebSphere Commerce Payments node, set the authorization for X client (host name) to access the X server where WebSphere Commerce will be installed. # xhost b. Export the DISPLAY as follows as the non-root user wasuser. # su - wasuser $ export DISPLAY=:0.0 Where is the host name of the system from which you will be running the installation (could be from a remote node). 716 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: We recommend that you add the following to the non-root user wasuser .profile: export DISPLAY=localhost:0.0 Note: Refer to the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems for details on using the Configuration Manager Client for a remote system. c. Start the Configuration Manager client: $ cd /usr/WebSphere/CommerceServer55/bin $ ./config_client.sh 6. When prompted to log on to the Configuration Manager Client, enter the following and then click OK: – User ID: webadmin – Password: webibm (default) You will be prompted to change the default password. 7. Click OK to confirm successfully modified password. 8. From the Configuration Manager, select Instance List and right-click Create Payments Instance. 9. We entered the following for each of the tabs within the Configuration Manager. Click Next to advance to the next tab. When done, click Finish. – Instance tab: • • • • • • • • Instance name: wpm (default) Check Password required for startup Instance Password: WebSphere Node Name: wcpaix1 (by default host name) Protocol Threads: 8 (default) Service Threads: 6 (default) Minimum Access Role: clerk (default) Site Admin ID: wcadmin (specified by user) – Database tab: • • • • • WebSphere Commerce Payments Database: Select Create a new database or tablespace. Database administrator name: db2inst1 Database administrator password: Database administrator home directory: /home/db2inst1 Database name: wcpay1 (user defined) Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 717 • • • • • Database Type: DB2 Check Remote Database server hostname: db2aix1 Database server port: 50000 Database node name: db2aix1 Note: In our example, we configured the DB2 client-server connection (catalog tcpip node in 18.5.3, “Configure and verify the DB2 client and server” on page 701) manually prior to creating the instance. We still had to enter this info. – Schema tab: • • • Database name: wcpay1 (greyed out, value from Database tab) Database type: DB2 (greyed out, value from Database tab) Database user name: db2inst1 Note: In our example, the DB2 instance owner and database schema owner are the same. It is possible for these to be different users. • • Database user password: Database user home directory: /home/db2inst1 – Web Server tab: • Uncheck User Remote Web Server We did not check for our scenario, since Web server is installed on the same node. • • • • • Hostname: wcpaix1.itso.ral.ibm.com Web Server Type: Select IBM HTTP Server (default) Server Port: 5432 (default) Check Use SSL SSL Port: 5433 (default) – WCSRealm tab: • WC Hostname: webaix1.itso.ral.ibm.com Note: This is the host name of the remote Web Server node used by the WebSphere Commerce node for our example. • • • WC Web Path: /webapp/wcs/stores/servlet (default) WC Web Server Port: 443 (default) Uncheck Use Non-SSL WC Client (default) – Click Finish to create instance. 718 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 10.You should see a message that you will need to restart the Web server, and that the instance was created successfully. Since we will do some additional configuration on the IBM HTTP Server, we did not start the server at this time. 11.Close the Configuration Manager. 18.5.11 Configure the IBM HTTP Server After the WebSphere Commerce Payments instance creation, the IBM HTTP Server httpd.conf is configured for SSL (assuming the SSL check box is checked with Configuration Manager for instance creation on the Web server tab). It is important in most environments that the data exchanged between the remote WebSphere Commerce Payments node and the WebSphere Commerce node is SSL encrypted. For this reason, we recommend that the IBM HTTP Server be SSL enabled and verified. This section is organized as follows: Configure the httpd.conf for SSL support Create an IBM HTTP Server key database Create a certificate for the IBM HTTP Server Restart the IBM HTTP Server Configure the httpd.conf for SSL support The IBM HTTP Server configuration file (httpd.conf) must be modified to enable SSL. The httpd.conf is updated for you when you create the WebSphere Commerce Payments instance if the SSL check box is checked. You can check this at a later time within Configuration Manager. Click Apply and the updates will be made for you as long as the httpd.conf contains the SSL directives (original httpd.conf.sample). Important: To work around a problem discovered at the time of writing this redbook, we needed to manually uncomment (remove #) the following line in the /usr/IBMHttpServer/conf/httpd.conf in order for the IBM HTTP Server to start: AddModule mod_ibm_ssl.c Create an IBM HTTP Server key database To create a key database for the IBM HTTP Server, do the following: 1. Start the IBM Key Management Utility for the IBM HTTP Server by entering the following: # cd /usr/IBMHttpServer/bin # ./ikeyman Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 719 Be aware: There is more than one version of the IBM Key Management Utility, each supporting different key database types. In this case, we want to use the CMS key database file type. 2. From the menu bar, click Key Database File -> New. 3. In the New window, enter the following and then click OK: – Key Database Type: CMS key database file – File name: keyfile.kdb – Location: /usr/IBMHttpServer/ssl This path must match the keyfile path in the httpd.conf. 4. In the Password Prompt window, enter the following and then click OK: – Password: (to protect the key store file). – Check Set expiration time? and enter the number of days before the password will expire. If no expiration is required, do not check. Note: Although not required in a development environment, it is recommended that all key stores used in production environments set an expiration period. – Check Stash the password to a file. Note: The IBM HTTP Server accesses the password-protected key store. 5. When the information window appears with the following message, click OK: The password has been encrypted and saved in the file: /usr/IBMHttpServer/ssl/keyfile.sth 6. Close the IBM Key Management Utility. Create a certificate for the IBM HTTP Server For testing purposes, you can create a self-signed certificate for IBM HTTP Server, using the IBM Key Management Utility. In a production environment a real certificate would be obtained from a company such as VeriSign. To create a self-signed certificate, do the following: 1. From the IBM Key Management Utility menu bar, click Create -> New Self-Signed Certificate. 720 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 2. When the Create New Self-Signed Certificate window appears, we entered the following and then clicked OK: – Key Label: http_ssl – Common Name: (should be there by default). For example, wcpaix1.itso.ral.ibm.com. – Organization: (for example, ibm) 3. To save, simply exit from the IBM Key Management Utility. Restart the IBM HTTP Server To restart the IBM HTTP Server and Adminstration Server, enter the following: # cd /usr/IBMHttpServer/bin # ./apachectl restart Verify SSL configuration of IBM HTTP Server To verify the SSL configuration of the IBM HTTP Server, enter the following in a Web browser: http:// https://:5433 18.5.12 Verify WebSphere Commerce Payments instance After the WebSphere Commerce Payments instance has been created, we recommend that you verify the instance before proceeding. 1. Review the following log files: – /usr/WebSphere/CommerceServer55/instances/wpm/logs/createdb.log – /usr/WebSphere/CommerceServer55/instances/wpm/logs/createdb.err.log Where wpm is the WebSphere Commerce Payments instance name. If the instance creation is successful, the createdb.err.log should be empty. 2. The settings of the instance can be viewed from the Configuration Manager instance properties or directly in the .xml file found in /usr/WebSphere/CommerceServer55/instances/wpm/xml/wpm.xml. 3. Ensure the following are started: – DB2 Server – IBM HTTP Server Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 721 Start the WebSphere Commerce Payments application server Now that the WebSphere Commerce instance database has been created, the member subsystem used to manage users exists. At this point, we can log on to the WebSphere Commerce Payments Console as follows: 1. Ensure the WebSphere Commerce Payments instance application server has been restarted after creating and configuring the WebSphere Commerce instance. a. Stop the WebSphere Commerce Payment instance. # su - wasuser $ cd /usr/WebSphere/AppServer/bin $ ./stopServer.sh wpm_Commerce_Payments_Server You should see the following message: Server wpm_Commerce_Payments_Server open for e-business b. Start the WebSphere Commerce Payment instance. # su - wasuser $ cd /usr/WebSphere/AppServer/bin $ ./startServer.sh wpm_Commerce_Payments_Server c. Start IBMPayServer (needed if password required, default). Tip: When a WebSphere Commerce Payments instance is created in the runtime environment using Configuration Manager, by default a password is required. Note that the default within WebSphere Commerce Studio is no password needed. # su - wasuser $ cd /usr/WebSphere/CommerceServer55/payments/bin $ ./IBMPayServer Where in our example is wpm (not full name created within WebSphere Application Server), and is the password for db2inst1. You should see a message ” wpm started successfully”. 2. Enter the following URL in the Internet Explorer Web browser: https://:5433/webapp/PaymentManager Where is the host name of the Web server used by WebSphere Commerce Payments. For example: https://wcpaix1.itso.ral.ibm.com:5433/webapp/PaymentManager 722 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Tip: If you are having problems starting the WebSphere Commerce Payments instance, we recommend reviewing the contents of the Configurator.1.log file as follows: # tail -f /usr/WebSphere/CommerceServer55/instances/Configurator.1.log 3. Verify that the WebSphere Commerce Payments Adminstration Console logon page appears by entering the following URL in a Web browser: https://:5433/webapp/PaymentManager Note: At this stage, you will not be able to log on to the WebSphere Commerce Payments Administration Console. The user repository is contained within the WebSphere Commerce instance database. This step is done purely to verify that the WebSphere Commerce Payments application server is running. 18.6 WebSphere Commerce node implementation This section describes how to install and configure the WebSphere Commerce node for the AIX three-tier scenario, including the following software components: IBM DB2 Universal Database V8.1, Enterprise Server Edition Administration Client IBM WebSphere Application Server V5.0, Advanced Edition IBM WebSphere Commerce V5.5, Business Edition We will use a combination of manual install and the use of the WebSphere Commerce V5.5 installer. After the software components are installed, we will create the WebSphere Commerce instance. This section is organized as follows: AIX installation Install DB2 UDB V8.1 Client Configure and verify DB2 client and server Create the non-root user(s) Install WebSphere Commerce and supporting software Verify the WebSphere Commerce installation Install WebSphere Application Server V5 fixes Verify the WebSphere Administration Console Configure Web server WebSphere plug-in (optional) WebSphere Commerce instance creation Verify the WebSphere Commerce instance creation Configure the remote Web server for WebSphere Commerce Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 723 Compile WebSphere Commerce tools JSPs Verify the WebSphere Commerce administration tools Configure and verify WebSphere Commerce Payments 18.6.1 AIX installation Refer to 18.2, “AIX installation” on page 680 for details. 18.6.2 Install DB2 UDB V8.1 Client The WebSphere Commerce V5.5 installer is capable of installing the IBM DB2 UDB V8.1 Enterprise Edition Client part of the installation. However, we will install the DB2 client manually before the WebSphere Commerce install for the following reasons: Configure and verify DB2 client/server We have already installed a remote DB2 Server and want to configure and verify the DB2 client/server configuration before installing dependent software such as WebSphere Commerce. WebSphere Commerce installer CD path prereq check We experienced an issue during the installation of WebSphere Commerce when attempting to install DB2 from a shared mount point, because of the WebSphere Commerce install path prereq checking. DB2 UDB V8.1 Fix Pack 1 Prior to installing WebSphere Commerce, we need to install DB2 UDB V8.1 Fix Pack 1. Install DB2 UDB V8.1 Client To install the DB2 Administration Client refer to “Install DB2 UDB V8.1 Client” on page 699 for details. Install DB2 UDB V8.1 Fix Pack 1 Note: The IBM DB2 UDB V8.1 (8.1.1.8) shipped with WebSphere Commerce V5.5 includes Fix Pack1. Therefore, it is not necessary to install DB2 V8.1 Fix Pack 1. This is only necessary for customers using the IBM DB2 UDB V8.1 GA CDs. To install the DB2 V8.1 Fix Pack 1 refer to 18.4.3, “Install DB2 UDB V8.1 Fix Pack 1” on page 695 for details. 724 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 18.6.3 Configure and verify DB2 client and server To configure the DB2 client on the WebSphere Commerce node to communicate with the DB2 Server node, do the following on the WebSphere Commerce node: 1. Ensure DB2 Server is started on the remote DB2 Server node. 2. Log on as user root and open an AIX Terminal window. 3. On the client machine, add the DB2 service name and connection port for your DB2 server instance to the /etc/services file on the client machine while logged in as root. These values must match those in the /etc/services file on the DB2 server. For example: db2c_db2inst1 50000/tcp #Connection port for DB2 instance db2inst1 DB2 service name: Editing the /etc/services file requires root access. As an alternative to adding the service name and port to the services file, specify the actual port number instead of the service name when running the catalog tcpip node command in the steps below. The connection port is defined in the DB2 dbm SVCENAME. To see what the SVCENAME is set to, enter the following: $ db2 get dbm cfg | more 4. On the WebSphere Commerce node, run catalog tcpip node on the DB2 Server as follows: $ db2 catalog tcpip node remote server Where is the local alias for the catalog remote server. For example: # su - db2inst1 $ db2 catalog tcpip node db2aix1 remote db2aix1 server db2c_db2inst1 5. Attach to the DB2 Server as follows: $ db2 attach to user db2inst1 using Where is the catalog tcpip node. # su - db2inst1 $ db2 attach to db2aix1 user db2inst1 using $ exit 18.6.4 Create the non-root user(s) Refer to 18.5.4, “Create the non-root user(s)” on page 702 for details. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 725 18.6.5 Install WebSphere Commerce and supporting software This section describes by example the options we selected to install WebSphere Commerce, and WebSphere Application Server using the WebSphere Commerce V5.5 installer for AIX. To start the WebSphere Commerce install, do the following: 1. Log on as user root and open an AIX Terminal window. 2. Ensure you have done the following: – – – – Installed prerequiste AIX filesets Installed AIX 5.1 maintenace level 4 Allocated file system space Created the non-root user(s) 3. From the AIX Terminal window, export the display. In a UNIX environment, it is common for the systems to be in racks or located remotely from the console of the administrator. This step allows for the installation of software on the target node (WebSphere Commerce node) from a remote console by setting the remote console display as follows: a. On the WebSphere Commerce node, set the authorization for X client (host name) to access the X server where WebSphere Commerce will be installed: # xhost b. Export the DISPLAY as follows: # export DISPLAY=:0.0 Where is the host name of the system from which you will be running the installation (could be from a remote node). 4. Insert the WebSphere Commerce CD 1 and mount the CD drive. For example: # mount -r -v cdrfs /dev/cd0 /mnt 5. Enter the following command to start the WebSphere Commerce installer: # /mnt/setup_aix 726 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: It is is very important that you do not change to the mount point (for example, /mnt) and then run the WebSphere Commerce installer (setup_aix). Do not type the following: # cd /mnt # ./setup_aix If you change to the mount point and then run the installer setup_aix, the CD will be in use (busy) and you will not be able to insert the supporting software CDs during the installation. 6. We accepted the default (English), and then clicked OK. 7. When the Welcome window appears, click Next. 8. Review the license agreement, select I accept the terms of the license agreement, and then click Next. 9. When the Choose the installation type best suited for your needs window appears, select Custom installation and then click Next. 10.When the Choose the components to install on this node window appeared, we did the following and then clicked Next (see Figure 18-4 on page 728): WebSphere Commerce components: – Check WebSphere Commerce Server, including WebSphere Application Server base product – Check WebSphere Commerce example files (optional for production) – Check WebSphere Commerce online help (optional for production) – Uncheck WebSphere Commerce Payments, including WebSphere Application Server base product In our example, WebSphere Commerce Payments is installed on a separate node. – Uncheck Remote WebSphere Commerce Configuration Manager client Supporting software: – Uncheck DB2 Universal Database (not applicable for OS/400 users) In our example, the DB2 Server is installed on a remote DB2 Server node so this option is not needed. The DB2 client will be installed automatically if this option is not selected, which is not obvious from the window text. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 727 – Uncheck IBM HTTP Server, including WebSphere Application Server plug-in (not applicable for OS/400 users). In our example, the IBM HTTP Server is installed on a remote node. – Uncheck WebSphere Application Server Web server plug-in. Figure 18-4 WebSphere Commerce V5.5 component selections for three-tier on AIX 11.When the Choose the database and Web server the WebSphere Commerce will use window appears, we did the following and then clicked Next: – Select database: This option is greyed out as the IBM DB2 Universal Database was selected in a previous window. – Select Web server: Select IBM HTTP Server. In our example, the IBM HTTP Server is installed on a remote Web Server node. Once you check the Remote Web server option below, this option will be greyed out. – Check Remote Web server. 728 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: If you see an error message stating that port 9090 is in use, take the following action. In our example, we noticed that the /etc/services file contained an entry for wsmserver on port 9090 (AIX Web-based Systems Management). This was added as a side effect to the AIX 5.1 maintenance level update. Refer to 18.2.6, “Disable wsmserver on port 9090” on page 684 to work around this problem and then restart the WebSphere Commerce installer. 12.When the Enter the destination paths or accept the default paths window appeared, we accepted the following default paths and then clicked Next (see Figure 18-5). Take note of disk space required and available. – IBM WebSphere Application Server destination path: /usr/WebSphere/AppServer – IBM WebSphere Commerce Server destination path: /usr/WebSphere/CommerceServer55 Figure 18-5 WebSphere Commerce V5.5 install diskspace required Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 729 Note: If you do not have enough free space, the WebSphere Commerce installer will not let you continue. Exit the installer, increase file system space for /usr for the options desired and file system space needed (see Figure 18-5 on page 729). Once you have increased the file system space accordingly, restart the WebSphere Commerce installer. 13.When the Enter the database user ID and password window appeared, we entered the following and then clicked Next: – – – – – Database user ID: db2inst1 Database user Password: Verify database user password: Database user group: db2grp1 Database user home directory: /home/db2inst1 14.When prompted for the Language for online help, we checked English and then clicked Next. 15.When the Enter the non-root user ID information for WebSphere Commerce application server window appeared, we entered the following and then clicked Next: – Non-root user ID: wasuser – Non-root user Group: wasgroup – Full path to the user ID’s home directory: /home/wasuser Note: The WebSphere Commerce installer will fill in the sample values of wasuser and wasgroup for the non-root user. We accepted these default values. We created the non-root user wasuser and group wasgroup prior to the installation in 18.5.4, “Create the non-root user(s)” on page 702. 16.When the Confirm your installation options and parameters window appears, review the settings and then click Next. 17.When prompted to insert the WebSphere Application Server CD, you will need to unmount the existing CD, insert and mount the WebSphere Application Server CD, and then click Next. Note: In a separate window, mount the CD-ROM, remove the WebSphere Commerce CD, inserted and mount the WebSphere Application Server CD. If you are installing from a local file system (shared drives not supported by the installer), you must enter the path for the WebSphere Commerce installer to recognize the directory structure of the CD image. 730 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Important: We noticed that there is no Back button displayed on the insert installation media window. In our case, we wanted to go back and change our settings and found we could not do so. The only option available is to click Cancel and exit the installation and start over. 18.When prompted to insert the WebSphere Commerce CD 1, you will need to unmount the exisying CD, insert and mount the WebSphere Commerce CD 1, and then click Next. 19.When prompted to insert the WebSphere Commerce CD 2, you will need to unmount the existing CD, insert and mount the WebSphere Commerce CD 2, and then click Next. 20.When the installation is complete, you will see a message “The Install Wizard has successfully installed IBM WebSphere Commerce”. Click Next. 21.When the Installation Complete window appears, click Finish. 18.6.6 Verify the WebSphere Commerce installation After the WebSphere Commerce installation, we recommend that you review the WebSphere Commerce installation and supporting software logs prior to creating the WebSphere Commerce instance. Note: Refer to the “Verifying your installation” chapter in Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems for detailed information. 18.6.7 Install WebSphere Application Server V5 fixes Refer to 18.5.7, “Install WebSphere Application Server V5 fixes” on page 710 for details. 18.6.8 Verify the WebSphere Administration Console Refer to 18.5.8, “Verify the WebSphere Application Server” on page 713 for details. 18.6.9 Configure Web server WebSphere plug-in (optional) Before proceeding to the WebSphere Commerce instance creation, we recommend that you verify the configuration of the remote IBM HTTP Server and WebSphere Application Server plug-in with the WebSphere Application Server on the WebSphere Commerce node. This step is optional. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 731 To configure the WebSphere plug-in on the remote Web server to be used by the WebSphere Commerce node, do the following: 1. Start the server1 application server on the WebSphere Commerce node: # su - wasuser $ /usr/WebSphere/AppServer/bin/startServer.sh server1 2. Start the WebSphere Administration Console, by entering the following URL in a Web browser: http://:9090/admin 3. From the WebSphere Application Server Administration Console, select Servers -> Application Servers. Check server1. 4. Select Environment -> Virtual Hosts -> Default Host. 5. Click Host Alias. 6. Click New and enter the following and click OK: – Host name: webaix1 – Port: 80 Repeat this process for the host names and ports listed in Table 18-7. Table 18-7 Host aliases and ports Host alias Port webaix1 80 webaix1.itso.ral.ibm.com 80 webaix1 443 webaix1.itso.ral.ibm.com 443 7. Click Save. Click OK. 8. Regenerate the WebSphere plug-in by clicking Environment -> Update Web Server Plugin. The new configuration information will be written to /usr/WebSphere/AppServer/config/cells/plugin-cfg.xml. 9. Copy the plugin-cfg.xml file from the WebSphere Commerce node to the /usr/WebSphere/AppServer/config/cells directory on the remote Web Server node. Ensure the permissions on the file have read permission. 10.Restart the remote Web Server to read the new plug-in file. 11.Enter the following URL in a Web browser to verify the plug-in: http:///snoop 732 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 18.6.10 WebSphere Commerce instance creation To create the WebSphere Commerce instance, do the following: 1. Ensure the DB2 Server is started. 2. Ensure you have installed the WebSphere Application Server fixes listed in 18.5.7, “Install WebSphere Application Server V5 fixes” on page 710 (requirment listed in WebSphere Commerce V5.5 Readme file). 3. Start the Configuration Manager server as the non-root user wasuser created in 18.5.4, “Create the non-root user(s)” on page 702. # su - wasuser $ cd /usr/WebSphere/CommerceServer55/bin $ ./config_server.sh You should see the following messages: Registry created. CMServer bound in registry. Note: If the Configuration Manager Server is listening on a different port from the default (1099), then specify the port when starting the server as follows: ./config_server.sh -port 4. Start the Configuration Manager Client. In a UNIX environment, it is common for the systems to be in racks or located remotely from the console of the administrator. This step allows for the installation of software on the target node (WebSphere Commerce Payments node) from a remote console by setting the remote console display as follows: a. On the WebSphere Commerce Payments node, set the authorization for X client (host name) to access the X server where WebSphere Commerce will be installed: # xhost b. Export the DISPLAY as follows as the non-root user wasuser: # su - wasuser $ export DISPLAY=:0.0 Where is the host name of the system from which you will be running the installation (could be from a remote node). Note: We recommend that you add the following to the non-root user wasuser .profile: export DISPLAY=localhost:0.0 Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 733 Note: Refer to the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems for details on using the Configuration Manager Client for a remote system. c. Start the Configuration Manager client: $ cd /usr/WebSphere/CommerceServer55/bin $ ./config_client.sh 5. When prompted to log on to the Configuration Manager Client, enter the following: – User ID: webadmin – Password: webibm (default) You will be prompted to change the default password. 6. Click OK. 7. From the Configuration Manager, select Instance List and right-click Create Instance. 8. We entered the following for each of the tabs within the Configuration Manager. Click Next to advance to the next tab. When done, click Finish. – Instance tab: • Instance name: wc1 • Instance’s root path: /usr/WebSphere/CommerceServer55/instances/wc1 • Merchant Key: • URL mapping file: /usr/WebSphere/CommerceServer55/xml/mapping/urlmapper.xml (default) • Site Admin ID: wcadmin • Site Admin Password: • Confirm Site Admin Password: – Database tab: 734 • WebSphere Commerce Database: Select Create a new database or tablespace. • Database administrator name: db2inst1 • Database administrator password: • Database administrator home directory: /home/db2inst1 • Database nane: wc1 (user defined) WebSphere Commerce V5.5 Handbook Customization and Deployment Guide • Database Type: DB2 • Check Remote • Database server hostname: db2aix1 • Database server port: 50000 • Database node name: db2aix1 Note: In our example, we have configured the DB2 client server connection (catalog tcpip node in 18.6.3, “Configure and verify DB2 client and server” on page 725) prior to creating the instance. We still needed to enter this information. – Schema tab: • Database name: wc1 (greyed out, value from Database tab) • Database type: DB2 (greyed out, value from Database tab) • Database user name: db2inst1 Note: In our example, the DB2 instance owner and database schema owner are the same. It is possible for these to be different users. • Database user password: • Database user home directory: /home/db2inst1 • Uncheck Use staging server • Check Set as active database – Languages tab: • We accepted the default, English. – Web Server tab: When creating an instance with a remote Web server configuration, there are a few new options you should be aware of. In WebSphere Commerce V5.5, new support has been added to the Configuration Manager to update the configuration file of the remote Web Server via FTP or a mapped file system. We recommend that you either map a shared drive or copy the Web server configuration file (httpd.conf) to a local file system that matches the directory structure of the remote Web server. We were not able to get the FTP method working. We found that the remote Web server update (in our case failure) was done one hour into instance creation process and caused the entire instance creation to fail. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 735 We then had to manually clean up the failed instance (drop the instance database, and clean up the file system, etc.). Within a production environment, the FTP daemon (port 21) is often disabled and firewalls may be configured to disallow ports 21 access. ITSO recommended method for remote Web server configuration: Check Use Remote Web server. Create the following directories: # mkdir -p /usr/IBMHttpServer/conf # mkdir -p /usr/IBMHttpServer/htdocs/en_US Copy the httpd.conf from the remote Web Server node to the WebSphere Commerce node /usr/IBMHttpServer/conf directory. Change the permissions of directories and files owned by the non-root user: # chown -R wasuser:wasgroup /usr/IBMHttpServer Change permissions on the httpd.conf # chmod 755 /usr/IBMHttpServer/conf/httpd.conf When creating the instance, enter the path to /usr/IBMHttpServer/conf/httpd.conf on the local system (or mapped drive). After the instance is created, copy the httpd.conf to the remote Web Server. • Check Use Remote Web Server In our scenario, the remote Web server is for the WebSphere Commerce node. • Hostname: webaix1.itso.ral.ibm.com Note: In our scenario, this is the remote Web server host name. • Web Server Type: Select IBM HTTP Server (default) • Primary Document Root: /usr/IBMHttpServer/htdocs/en_US • Server Port: 80 (default) • Authentication Mode: Select Basic (default) Note: In our example, we do not really have a mapped drive. However, we will check this option to simulate updating the httpd.conf as if it were on a mapped drive, in combination with checking the Use Remote Web Server option. 736 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide • Remote Server Install Path: /usr/IBMHttpServer In our example, this is really the local file system path we created. • Check Mapped Network Drive Configuration • Mapped Server Directory: /usr/IBMHttpServer In our example, this is really the local file system path we created. – WebSphere tab: • DataSource Name: WebSphere Commerce DB2 DataSource wc1 (default) • JDBC Driver Location: /usr/opt/db2_08_1/java/db2java.zip • Tools Port Number: 8000 • WC Admin Port Number: 8002 • WC OrgAdmin Port Number: 8004 Note: When the WebSphere Commerce instance is created, the httpd.conf will get updated with virtual hosts for each port and aliases under each. – Payments tab: • Hostname: wcpaix1.itso.ral.ibm.com In our example, this is the remote WebSphere Commerce Payments node host name. • Profile Path: /usr/WebSphere/CommerceServer55/instances/wc1/payment (default) • Check Use non-SSL Payments Client (SSL enabled) • Webserver Port: 5433 – Log system tab: • We accepted the default settings. – Messaging tab: • We accepted the default settings. – Auction tab: • We accepted the default settings. – Click Finish to create the instance. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 737 9. After creating the WebSphere Commerce instance, you will get a message stating that you need to restart the Web Server. In our case, this component is installed on the remote Web Server node. Click OK. 10.You should then see a window stating the instance was created successfully. Click OK and close Configuration Manager. Note: In a later step, we will verify the httpd.conf was updated correctly with the WebSphere Commerce virtual hosts, aliases, SSL enabled, and other directives. Then we will copy this file from the WebSphere Commerce node to the remote Web Server node. 18.6.11 Verify the WebSphere Commerce instance creation Refer to the Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems for details on how to verify the WebSphere Commerce instance creation. Understanding the instance creation process There are several reasons for gaining an understanding of what operations are performed during WebSphere Commerce instance creation. First, in the event that the instance creation process does not work properly, possibly because you have entered something that is invalid, you will need to troubleshoot the failure. Second, as a person supporting the infrastructure of a WebSphere Commerce runtime environment, it is important that you understand how the system interacts. During instance creation, the following tasks are performed by the Configuration Manager: 1. Configuration Manager startup. There are two key issues to mention regarding the Configuration Manager startup: – Non-root user – X-Windows Console settings The Configuration Manager has a server and client component. On UNIX systems the Configuration Manager needs to be started as a non-root user (for example, wasuser). As a prerequisite to the WebSphere Commerce installer, the mqm user and mqbrkrs must exist for the WebSphere MQ embedded messaging (refer to 18.5.4, “Create the non-root user(s)” on page 702 for more detailed information). Another consideration of using Configuration Manager is the proper setup of the xhost and display for the console. In a UNIX environment, it is common for 738 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide the systems to be in racks or located remotely from the console of the administrator. This step allows for the installation of software on the target node (WebSphere Commerce Payments node) from a remote console by setting the remote console display as follows: a. On the WebSphere Commerce Payments node, set the authorization for X client (host name) to access the X server where WebSphere Commerce will be installed. # xhost b. Export the DISPLAY as follows: # export DISPLAY=:0.0 Where is the host name of the system from which you will be running the console. 2. Data entry and selections with Configuration Manager. In some cases, the Configuration Manager will validate the user input prior to continuing to the next tab. This can be problematic in some cases. At the time of writing this redbook, we found that in a remote Web Server configuration, the host name must be able to be resolved. If it could not, this caused a problem with the WebSphere Application Server plugin-cfg.xml file, where the transports included the IP address instead of the host name. This causes a problem later when attempting to use the WebSphere Commerce Adminstration Console. In other cases, the validation of the input is not checked until as much as an hour into the instance creation process. For example, in a remote Web server configuration, if you selected the Remote Web Server check box and opt to use FTP, this validation is done towards the end of instance creation. In our case the FTP configuration update of the remote Web Server failed and caused the instance creation to fail, over an hour into the instance creation process. When this happens, you will have to manually roll back the instance creation. For example, we had to manually uncatalog the database on the DB2 client, drop the instance database, and delete the instance directory. For this reason and other production security reasons, we recommend an alternative to using the remote configuration option for configuring the remote Web Server. 3. Tasks done during instance creation: – Create and modify instance configuration files and create an instance directory. – Instance database creation and schema population. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 739 The first task of instance creation is to create the WebSphere Commerce instance database and populate the schema. The script files that are executed can be found in the following directories: • • /usr/WebSphere/CommerceServer55/bin /usr/WebSphere/CommerceServer55/schema The log files createdb.log, create.db2.log, populatedb.log, etc. can be found in the following directory: • /usr/WebSphere/CommerceServer55/instances//logs – Create WebSphere Commerce instance application server. – Deploy WebSphere Commerce Server Enterprise application to the WebSphere Commerce instance application server. – Update the Web Server configuration file with WebSphere Commerce entries (for example, httpd.conf). This includes SSL enablement, virtual hosts, aliases, file permissions and other directives. Verify httpd.conf In our example, we copied the remote Web server configuration file httpd.conf to the WebSphere Commerce node into a directory we created (/usr/IBMHttpServer/conf) to simulate the IBM HTTP Server being installed on the WebSphere Commerce node to allow the Configuration Manager to make the necessary updates to the httpd.conf. Verify that the following key updates were made within the httpd.conf file: 1. On the WebSphere Commerce node, change directories to the location where you have copied the httpd.conf: # cd /usr/IBMHttpServer/conf 2. Open the httpd.conf with a text editor. There are many updates that the Configuration Manager makes to the httpd.conf. 3. SSL enablement look for entries such as the following: LoadModule ibm_ssl_module libexec/mod_ibm_ssl_128.so AddModule mod_ibm_ssl.c Listen 443 SSLEnable SSLClientAuth 0 4. Listen on the ports for virtual hosts for the WebSphere Commerce tools: – Listen 8000 (WebSphere Commerce tools) – Listen 8002 (WebSphere Commerce Administration Console) 740 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – Listen 8004 (WebSphere Commerce OrgAdmin Console) – Listen 443 – Listen 80 5. Virtual hosts and aliases (not a complete listing): Alias /wcstore “/usr/WebSphere/AppServer/installedApps/wcaix1/WC_wc1.ear/Stores.war” 6. Permissions directives. Search on WebSphere Commerce. You should see entries such as the following: Options Indexes AllowOverride Name order allow,deny allow from all 18.6.12 Configure the remote Web server for WebSphere Commerce After the instance creation, you will need to do the following to configure the remote Web Server: Copy httpd.conf to remote Web server Copy WebSphere plug-in to remote Web server Copy WebSphere Commerce static files to remote Web server Remove JSPs and JARs Restart the remote Web server Copy httpd.conf to remote Web server Copy the httpd.conf that has been updated by WebSphere Commerce Configuration Manager from the WebSphere Commerce node to the /usr/IBMHttpServer/conf directory on the remote Web Server node. Note: This step is not needed if you used the Configuration Manager to update the remote Web server configuration file via a shared network drive or FTP. It is needed for our example. Copy WebSphere plug-in to remote Web server During the WebSphere Commerce instance creation, the Configuration Manager added virtual hosts for WebSphere Commerce and host aliases for the remote Web Server (webaix1). In addition, WebSphere plugin-cfg.xml was regenerated and should now include these new remote Web Server host aliases. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 741 Copy the /usr/WebSphere/AppServer/config/cells/plugin-cfg.xml from the WebSphere Commerce node to the same directory on the remote Web Server. Copy WebSphere Commerce static files to remote Web server When using a remote Web server, the static content for WebSphere Commerce tools (and eventually stores) is served by the Web server. Copy the /usr/WebSphere/AppServer/installedApps//WC_.ear directory from the WebSphere Commerce node to the remote Web Server node. For example: /usr/WebSphere/AppServer/installedApps/wcaix1/WC_wc1.ear 1. We used the tar command as follows to package the WC_wc1.ear: # tar -cvf /tmp/WC_wc1.tar /usr/WebSphere/AppServer/installedApps/wcaix1/WC_wc1.ear 2. Create the /usr/WebSphere/AppServer/installedApps/wcaix1/ directory on the remote Web Server node. # mkdir -p /usr/WebSphere/AppServer/installedApps/wcaix1 3. Copy the tar file from the WebSphere Commerce node to the remote Web server /usr/WebSphere/AppServer/installedApps/wcaix1 directory. 4. Unpack the .tar file on the remote Web server. # tar -xvf WC_wc1.tar When done you should see the following directory structure: /usr/WebSphere/AppServer/installedApps/wcaix1/WC_wc1.ear 5. Ensure the directories and files have the proper owner and permissions. Remove JSPs and JARs Remove JSPs and JAR files from all directories found within WC_wc1.ear on the remote Web Server node. Restart the remote Web server After copying the httpd.conf and plugin-cfg.xml, you will need to restart the Web Server. For example: # /usr/IBMHttpServer/bin/apachectl restart 742 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 18.6.13 Compile WebSphere Commerce tools JSPs We recommend that you precompile your JSPs for the WebSphere Commerce tools. Compiling the JSPs will significantly reduce the amount of time needed to load the WebSphere Commerce tools the first time they are accessed. By default, the WebSphere Application Server will compile the JSPs the first time the JSP is requested. WebSphere Commerce V5.5 has separate Web modules for the administration tools: WebSphere Commerce Administration Console: SiteAdministrator.war WebSphere Commerce Accelerator: CommerceAccelerator.war WebSphere Commerce Organization Administration Console: OrganizationAdministration.war WebSphere Commerce Stores: Stores.war (not published yet) Syntax: JspBatchCompiler.sh JspBatchCompiler -enterpriseapp.name [-webmodule.name ] [-cell.name ] [-node.name ] [-server.name ] [-classloader.parentFirst ] [-classloader.singleWarClassloader ] [-filename ] [-keepgenerated ] [-verbose ] [-deprecation ] Refer to the WebSphere Application Server V5 InfoCenter at the following for more information (search on JspBatchCompiler): http://publib7b.boulder.ibm.com/webapp/wasinfo1/index.jsp?deployment=Appl icationServer&lang=en To batch compile JSPs for the WebSphere Commerce tools, do the following: 1. Ensure that the WebSphere Commerce instance application server is started. 2. From a command prompt, log on as the non-root user wasuser, and run the following script: # su - wasuser $ cd /usr/WebSphere/AppServer/bin Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 743 3. WebSphere Commerce Administration Console (SiteAdministration.war): $ ./JspBatchCompiler.sh -enterpriseapp.name WC_wc1 -webmodule.name SiteAdministration.war -server.name WC_wc1 -node.name wcaix1 -cell.name wcaix1 4. Repeat the previous step for each of the following Web modules: – CommerceAccelerator.war – OrganizationAdministration.war – Stores.war At this point, a WebSphere Commerce store has not been published. After the store is published, the Web module can be batch compiled. Tip: We recommend that you create a script to perform the compile of the JSPs. The script will need to be run anytime the cache is flushed for the application server. For example: Create a script wctools_jsp.sh in the /usr/WebSphere/CommerceServer55/bin directory such as the following: #!/bin/ksh $ ./JspBatchCompiler.sh -enterpriseapp.name WC_wc1 -webmodule.name SiteAdministration.war -server.name WC_wc1 -node.name wcaix1 -cell.name wcaix1 Execute the wctools_jsp.sh script while logged in as wasuser: # su - wasuser $ cd /usr/WebSphere/CommerceServer55/bin $ ./wctools_jsp.sh 18.6.14 Verify the WebSphere Commerce administration tools Now that the remote Web server has been configured, we can verify the functionality of the WebSphere Commerce tools. Start WebSphere Commerce application server To start the WebSphere Commerce instance application server, do the following: 1. Log on as the non-root user wasuser on the WebSphere Commerce node: # su - wasuser 2. Start the WebSphere Commerce application server: $ cd /usr/WebSphere/AppServer/bin $ ./startServer.sh WC_wc1 744 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide You should see the following message: Server WC_wc1 open for e-business Note: Review the status of the server startup in the startServer.log as follows: tail -f /usr/WebSphere/AppServer/logs//startServer.logs Start WebSphere Commerce Administration Console To start the WebSphere Commerce Administration Console, do the following: 1. Ensure the WebSphere Commerce application server is started. 2. Enter the following URL in the Microsoft Internet Explorer V5.5 or V6 Web browser: https://:8002/adminconsole Were: – https not http (configured for SSL) is used. – The hostname in this case is the remote Web server’s name. – The port (8002) is specified when creating the WebSphere Commerce instance for the host alias for the virtual host within WebSphere Application Server (WebSphere Commerce node), and the virtual host and alias within the httpd.conf for the IBM HTTP Server (remote Web Server node). – Need to use Microsoft Internet Explorer V5.5 or higher (we used V6). 3. Log on to the WebSphere Commerce Administration Console with the site user ID entered during instance creation. For example, we entered wcadmin. Start WebSphere Commerce Accelerator To start the WebSphere Commerce Accelerator, enter the following in the Internet Explorer: https://:8000/accelerator Start WebSphere Commerce Organization Admin Console To start the WebSphere Commerce Organization Administration Console, enter the following in the Internet Explorer: https://:8004/orgadminconsole Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 745 18.6.15 Configure and verify WebSphere Commerce Payments Now that the WebSphere Commerce instance database has been created, the member subsystem is used to manage users exits. At this point, we can log on to the WebSphere Commerce Payments Console as the site administrator entered during instance creation (for example, wcadmin). Verfiy WebSphere Commerce Payments For details refer to 18.5.12, “Verify WebSphere Commerce Payments instance” on page 721. Configure WebSphere Commerce Payments Before enabling the WebSphere Commerce Payments for use with WebSphere Commerce you must configure the payment methods accepted by a store. Note: When you a publish a sample store, a number of sample payment methods are automatically configured and the instructions in this section can be skipped. We found that the payment information was not available in the sample store when using a remote WebSphere Commerce Payments node. To configure WebSphere Commerce Payments, do the following: 1. Ensure that the WebSphere Commerce Payments server is started. – wpm_Commerce_Payments_Server application server – IBMPayServer wpm 2. Log in to WebSphere Commerce Payments using the Site Administrator user ID and the password. You can access the WebSphere Commerce Payments log in page by entering the following in a browser: http://:5432/webapp/PaymentManager or https://:5433/webapp/PaymentManager Where host_name is the fully qualified TCP/IP host name of the Web server associated with WebSphere Commerce Payments. If WebSphere Commerce Payments is SSL-enabled, use the secure (https) URL. Otherwise, use the non-secure (http) URL. If you see the IBM WebSphere Commerce Payments Logon page, your configuration of the remote WebSphere Commerce Payments machine was successful. 3. From the left pane, click Merchant Settings. In the right window, click Add a Merchant. 746 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 4. Enter a Merchant Name for your sample store. The Merchant Number must be the same as the storeId for your sample store (for example, 10001). Check the OfflineCard check box and click Create Merchant. You should see the message “A Merchant created successfully”. 5. In the left pane, click Merchant Settings again. 6. In the right-hand window, beside the name of your new merchant, the green cassette status icon (under the OfflineCard column) indicates that the OfflineCard cassette is enabled and running for that merchant. Click the green icon. 7. You must now create an account for each currency supported by your store. Click Accounts. 8. Click Add an Account. Enter the following and then click Create Account: – – – – Account name: account101 Account number: 101 Financial Institution Name: Bank 101 Currency: Select US Dollar When selecting currency for Europe, make sure that you select Euro. There are two options listed: euro, European Currency Unit (obsolete). – Batch Close Time: (we left this field blank) 9. In the Accounts window, click the name of your new account, then click Brands. 10.Click Add a Brand. Enter a brand name (for example, VISA) and click Create Brand. 11.Repeat for all other brands to be used with this account. Repeat the above three steps to add accounts for all other currencies to be supported by your store. 18.7 Verify the runtime environment After the runtime has been configured, we recommend that you verify the configuration by publishing a sample store to test the components of the runtime. Within the ITSO test environment, we performed the following high-level steps to verify the AIX three-tier runtime environment: Back up the databases Publish a sample store archive (SAR) Configure the Web server static content Compiling WebSphere Commerce store JSPs (optional) Verify WebSphere Commerce administration tools Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 747 Verify functionality of sample store Restore databases (optional) Remove the published sample store (optional) 18.7.1 Back up the databases When verifying the runtime, we recommend that you back up the WebSphere Commerce instance database and WebSphere Commerce Payments database before publishing a sample store to verify the runtime environment. After testing the sample store, we will later restore the pristine database. In our example, we performed a DB2 backup of the following databases: WebSphere Commerce instance database (wc1) WebSphere Commerce Payments database (wcpay1) Note: For details on how to back up DB2 databases, refer to “DB2 backup and restore” on page 988. To perform a DB2 backup of the WebSphere Commerce instance database and WebSphere Commerce Payments database, do the following: 1. Ensure that the application servers on the WebSphere Commerce node and WebSphere Commerce Payments node are stopped. 2. When configuring the DB2 Server, we created a separate file system for databases called /db2data, owned by db2inst1:db2grp1. We need to create a directory to store the backup (for example, db2bak). # mkdir -p /db2data/db2bak # chown -R db2inst1:db2grp1 /db2data/db2bak 3. Log on as the DB2 instance owner on the DB2 Server node. # su - db2inst1 4. Terminate all connections to the DB2 Server: $ db2 force applications all $ db2 terminate 5. Back up the WebSphere Commerce instance database. $ db2 backup db wc1 to /db2data/db2bak 6. Back up the WebSphere Commerce Payments database: $ db2 backup db wcpay1 to /db2data/db2bak 748 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 18.7.2 Publish a sample store archive (SAR) Now that the WebSphere Commerce instance database and WebSphere Commerce Payments database have been backed up, we can publish a sample store to verify the runtime environment. We will use the B2B Direct business model, B2BDirect.sar (ToolTech). 1. Ensure the following servers are started: – DB2 Server node: • DB2 Server – WebSphere Commerce node: • WebSphere Commerce application server (WC_wc1) – Remote Web Server node: • IBM HTTP Server – WebSphere Commerce Payments node: • IBM HTTP Server • WebSphere Commerce Payments application server (wpm_Commerce_Payments_Server) • IBMPayServer wpm 2. Start the WebSphere Commerce Administration Console. See “Start WebSphere Commerce Administration Console” on page 745. 3. Log on with the site administrator ID (for example, wcadmin). 4. Select Site and click OK. 5. From the menu, select Store Archives -> Publish. 6. From the Store Archives page, the view is set to Default, which lists the composite (full-featured store archives) for each business model supplied with WebSphere Commerce. Check B2BDirect.sar and then click Next. 7. On the Parameters page, notice by default the parameters store directory and identfier are set to read only. For the purposes of testing this is fine, but when creating a store you will want to modify this behavior, as described in Chapter 12, “Create a store” on page 341. Click Next. 8. When the Summary page appears, click Finish to begin the publishing process for the store archive. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 749 9. Store publishing will schedule a job, since this is a long-running task. You can monitor the store publish on the Publish Status page by clicking Store Archives -> Publish Status. If successful, the publishing status will change to Successful. When publishing a store archive when using a remote Web Server with WebSphere Commerce, you will need to manually configure the static content for the store on the remote Web server. 18.7.3 Configure the Web server static content This section describes the steps needed to copy and configure the remote Web Server for the WebSphere Commerce store after publishing. Copy WebSphere Commerce static files to remote Web server When using a remote Web server, the static content for WebSphere Commerce stores is served by the Web server. Copy the following directory from the WebSphere Commerce node to the remote Web Server node: /usr/WebSphere/AppServer/installedApps//WC_.ear/Stores.war For example: /usr/WebSphere/AppServer/installedApps/wcaix1/WC_wc1.ear/Stores.war We performed the following steps to package, copy, and unpackage the Stores.war: 1. We used the tar command as follows to package the Stores.war: # tar -cvf /tmp/Stores.tar /usr/WebSphere/AppServer/installedApps/wcaix1/WC_wc1.ear/Stores.war 2. Copy the .tar file from the WebSphere Commerce node to the remote Web server /usr/WebSphere/AppServer/installedApps/wcaix1/WC_wc1.ear directory. 3. Unpack the .tar file on the remote Web server. # tar -xvf Stores.tar When done you should see the following directory structure: /usr/WebSphere/AppServer/installedApps/wcaix1/WC_wc1.ear/Stores.war 4. Ensure the directories and files have the proper owner and permissions. Removing dynamic content from the Web server Remove JSPs and JAR files from all directories found within Stores.war on the remote Web Server node. 750 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 18.7.4 Compiling WebSphere Commerce store JSPs (optional) For details on compiling store JSPs, refer to 18.6.13, “Compile WebSphere Commerce tools JSPs” on page 743, and use Store.war for the webmodule.name parameter for the WebSphere Application Server JspBatchCompiler.sh. Note: This is strongly recommended in a production environment. 18.7.5 Verify WebSphere Commerce administration tools Refer to 18.6.14, “Verify the WebSphere Commerce administration tools” on page 744 for details. 18.7.6 Verify functionality of sample store Verify that you can register a user and complete a transaction, and verify that your payment information was processed and sent to the WebSphere Commerce Payments node. 1. From a Web browser, we entered the following to access the B2B Direct (ToolTech) sample store: http://webaix1.itso.ral.ibm.com/webapp/wcs/stores/servlet/ToolTech/index .jsp Alternatively, click the Launch button from the Store Archives Status page. 2. Register a new user. For example, we create a test01 user. 3. Log on to the store as test01. 4. Purchase a product as the test01 user. When prompted to enter the credit card information, we entered 0000000000000000 (16 0s) as a test number for Visa. Note: If you do not have a credit card type visible from the store checkout, most likely the WebSphere Commerce Payments application server (and IBMPayServer) were not running at the time of publishing. The sample store archives contain default payment information for credit card types for the offline payment cassette. To resolve this problem, republish the store or manually create an account, credit card type, etc. on the WebSphere Commerce Payments node. 5. Once the order is complete within WebSphere Commerce, log on to the WebSphere Commerce Payments Console. Your order should be listed under Approve. Approve the order. Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 751 18.7.7 Restore databases (optional) Now that the WebSphere Commerce runtime environment has been verified, we need to restore the clean database that was previously backed up after instance creation. The restore of the pristene instance database for WebSphere Commerce and WebSphere Commerce Payments is a preparatory step for your store deployment. For details on how to restore a DB2 databases, refer to “DB2 backup and restore” on page 988. 18.7.8 Remove the published sample store (optional) After verifying the functionality of the WebSphere Commerce runtime environment by using one of the sample stores, the sample store is no longer needed. In a production environment, we recommend that the store be removed. To remove the files for a sample store after it has been published, do the following: 1. On the WebSphere Commerce node, change to the Stores.war directory: # cd /usr/WebSphere/AppServer/installedApps/wcaix1/WC_wc1.ear/Stores.war 2. Remove the sample store archive directory (for example, ToolTech): # rm -R ToolTech 3. You will need to perform the same steps on the remote Web Server node. After restoring the database, and removing the published sample store directory, you will have a clean instance and database that has been tested and ready for a production store deployment. 18.8 Additional configuration There are several other configuration items that we will not cover in detail but we want to mention because they are important for a production environment: Review the security of the WebSphere Commerce installation. Refer to the Security Guide, IBM WebSphere Commerce V5.5 for details. SSL enable the HTTP transport for WebSphere (optional) When using a remote Web Server configuration, it is important to understand that by default, the communication between the remote Web Server node and the WebSphere Commerce node is not encrypted. This type of configuration may not be suitable where security is an issue. 752 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide To address this security issue, the IBM HTTP Server on the remote Web Server node and the WebSphere Application Server and WebSphere Commerce can be configured on the WebSphere Commerce node to SSL enable the HTTP transport. Refer to the following for more information: – WebSphere Application Server V5 InfoCenter – WebSphere V5.0 Applications: Ensuring High Performance and Scalability, SG24-6198 – IBM WebSphere Application Server V5.0 Systems Management and Configuration: WebSphere Handbook Series, SG24-6195 Chapter 18. AIX: Three-tier using DB2 and IBM HTTP Server 753 754 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 19 Chapter 19. OS/400: Two-tier remote database server This chapter provides procedures for installing and configuring a WebSphere Commerce V5.5 for iSeries in a two-tier remote database runtime environment and then publishing an example store. The scenario documented in this chapter is intended to be used with the procedures documented in the Installation Guide, IBM WebSphere Commerce V5.5 for OS/400. The chapter is organized as follows: Scenario overview and planning Pre-installation steps WebSphere Commerce installation process PTF installation Configuration Instance creation Enabling SSL for IBM HTTP Server Start the application servers Publish a store Back up WebSphere Commerce and components Uninstall WebSphere Commerce © Copyright IBM Corp. 2003. All rights reserved. 755 19.1 Scenario overview and planning This section highlights the necessary steps to implement WebSphere Commerce V5.5 for iSeries and defines the hardware and software used within the ITSO to set up a WebSphere Commerce two-tier runtime environment with remote database for iSeries. 19.1.1 Skill requirements People who will be installing and configuring WebSphere Commerce should have knowledge in the following areas: IBM iSeries and the OS/400 operating system IBM DB2 Universal Database ™ for iSeries Basic Command Language commands Basic SQL commands The Internet Understanding of TCP/IP, HTTP and SSL protocols IBM HTTP Server administration skills Understanding of relational database concepts Ability to perform basic SQL queries 19.1.2 Hardware and software requirements For detailed and updated information on WebSphere Commerce V5.5 hardware and software requirements, refer to the Installation Guide, IBM WebSphere Commerce V5.5 for OS/400 or visit: http://www-3.ibm.com/software/genservers/commerce/wcbe/library/lit-tech-gen eral.html http://www-3.ibm.com/software/genservers/commerce/wcbe/requirements 19.1.3 Hardware used in the ITSO runtime environment We used the following iSeries hardware within the ITSO two-tier runtime environment: WebSphere Commerce node: – Hostname: TORASCUB.TOROLAB.IBM.COM – IBM iSeries Model 825-7418 • 3 processors with a CPW rating of 3600 • 24 GB of main memory • 635 GB disk space • 1 IBM Ethernet adapter, 100 MB 756 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Database Server node: – Hostname: TORASSTR.TOROLAB.IBM.COM – IBM iSeries Model 730-2B6D • 4 processors with a CPW rating of 2000 • 4 GB of main memory • 77 GB disk space • 1 IBM Ethernet adapter, 100 MB 19.1.4 Software used in the ITSO runtime environment Within the ITSO test environment for a two-tier runtime environment, we used the following: WebSphere Commerce node: – OS/400 Version 5 Release 2 (V5R2M0) • • • • • • Host Servers:5722SS1 option 12 QShell Interpreter: 5722SS1 option 30 Portable App Solutions Environment: 5722SS1 option 33 Digital Certificate Manager: 5722SS1 option 34 International Components for Unicode: 5722SS1 option 39 IBM Java Developer Kit, Version 1.3: 5722JV1 option 5 – IBM HTTP Server Powered by Apache: 5722DG1 – Crypto Access Provider 128-Bit for AS/400®:5722AC3 – TCP/IP Connectivity Utilities: 5722TC1 – iSeries Access: 5722XW1 options *BASE and 1 – DB2 Query Manager and SQL Development Kit: 5722ST1 – WebSphere Application Server V5 : 5733WS5 option *Base, 1 and 2 – WebSphere Commerce V5.5 – WebSphere Commerce Payments V5.5 DataBase Server node: – OS/400 Version 5 Release 2 (V5R2M0) • Host Servers: 5722SS1 option 12 • TCP/IP Connectivity Utilities: 5722TC1 • iSeries Access: 5722XW1 options *BASE and 1 • DB2 Query Manager and SQL Development Kit: 5722ST1 Chapter 19. OS/400: Two-tier remote database server 757 19.1.5 Software installation paths and root directories The following list shows the directories and stream files that are created during the WebSphere Commerce installation and configuration process. Payments Product directory:/QIBM/ProdData/CommercePayments/V55 Payments UserData directory:/QIBM/UserData/CommercePayments/V55 WebSphere Application Server Product directory:/QIBM/ProdData/WebAS5/Base WebSphere Application Server UserData directory: /QIBM/UserData/WebAS5/Base/WAS_instance_name WebSphere Commerce Product directory:/QIBM/ProdData/CommerceServer55 WebSphere Commerce UserData directory:/QIBM/UserData/CommerceServer55 The following file contains the configuration settings for the WebSphere Commerce server: /QIBM/ProdData/CommerceServer55/instance_root/xml/instance_name.xml The IBM HTTP Server document root directory: QIBM/UserData/CommerceServer55/instance_root/web The directory containing the IBM HTTP Server configuration file (httpd.conf): /QIBM/UserData/CommerceServer55/instance_root/conf In our scenario: /QIBM/UserData/CommerceServer55/instances/wc2/conf Note: All the data used by WebSphere Commerce that can be modified or that needs to be configured by the user is placed in the UserData subdirectory and all of the WebSphere Commerce proprietary data is placed in the ProdData subdirectory. This has been done to make a clear distinction between the two types of information, to make future migration as simple as possible, and to facilitate the servicing of files therein. 19.2 Pre-installation steps Before you proceed with the WebSphere Commerce V5.5 installation, the following pre-installations steps must be completed: Verify user profiles required during the installation Create a remote database entry Create an instance user profile 758 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 19.2.1 Verify user profiles required during the installation To install and configure WebSphere Commerce, a user profile with USRCLS(*SECOFR) is needed. You can also use the QSECOFR user profile. Before you install WebSphere Commerce, ensure that you have access to the QSECOFR user profile, or an iSeries user profile of USRCLS(*SECOFR). This user profile must have a CCSID other than 65535, and should either have English language settings or language settings that match the default language you will choose for your instance. 19.2.2 Create a remote database entry In order to use a remote database, the remote database name needs to be defined in the relational database directory. Use the following command to add an entry: ADDRDBDIRE RDB(remote_DB) RMTLOCNAME(remote_DB_hostname *IP) Where: remote_DB is the name of the remote database. remote_DB_hostname is the name or IP address of the remote host for the remote database. Note: On iSeries the remote database name and the remote host name are the same. In our example: ADDRDBDIRE RDB(TORASSTR) RMTLOCNAME(TORASSTR *IP) TEXT('Remote Database System TORASSTR') 19.2.3 Create an instance user profile Create a user profile on the remote iSeries system. The user profile must have the same name as the instance name that you are creating. Configure the user profile so that its language settings match the language you intend to choose as the default language for your WebSphere Commerce instance. The password for this user profile must be the same as on the *LOCAL system (WebSphere Commerce node). This is the password that will be entered while configuring the Instance Logon Password field in the Configuration Manager. In our example working we have created a user CRTUSRPRF USRPRF(WC2). Chapter 19. OS/400: Two-tier remote database server 759 19.3 WebSphere Commerce installation process In this section we cover the installation process for WebSphere Commerce for OS/400 (iSeries). Custom installation process Verify a custom installation WebSphere Application Server installation log WebSphere Commerce installation log Note: To install and configure WebSphere Commerce, you must use an iSeries user profile with USRCLS(*SECOFR) or use the QSECOFR user profile. 19.3.1 Custom installation process The installation of WebSphere Commerce V5.5 can be done from a Windows 2000 system using the graphical installation GUI. The following list describes the necessary steps: 1. Insert WebSphere Commerce CD 1 into the CD-ROM drive on a Windows system. 2. Navigate to the CD-ROM drive and double-click iSeriesServer.bat to launch the installer. 3. After a few moments, the iSeries Logon Information window displays. Enter the System Name, User Profile, and Password for the iSeries system on which you are installing WebSphere Commerce components. Ensure that you log on to your iSeries system as a user with SECOFR class authority. Click Next. 4. Select the installation language and click OK. 5. Read the Welcome window and click Next. 6. The Software License Agreement window displays. Select I accept the terms in the license agreement and then click Next. 7. Select Custom Installation and click Next. 8. Select the component(s) you want to install on the node. Click Next. In our scenario we selected all the components. 9. A confirmation window appears indicating the location where WebSphere Commerce will be installed. Click Next. 10.Select the language for the online help you want installed and click Next. 760 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 11.Confirm your installation choices and click Next. (To modify your choices, click Back.) 12.. Insert the WebSphere Application Server for iSeries Disk 1 CD into the CD-ROM drive on the Windows system and click Next. A command line window opens. The details of the WebSphere Application Server product installation are displayed. 13.. In the same command line window the following message displays: Insert disk 2 of 2.Please press Enter key when ready. Insert the WebSphere Application Server for iSeries Disk 2 CD into the CD-ROM drive on the Windows system and then press Enter. The following messages should appear when the installation is complete: Installation completed successfully. Please read the Installation and Initial Configuration documentation. Please press the Enter key to end the installation program. After you press Enter, the command line window closes. 14.Navigate back to the WebSphere Commerce install window. Wait until you see the following message: Insert the IBM WebSphere Commerce CD 1 into the CD-ROM drive Remove the WebSphere Application Server CD from the drive and insert the WebSphere Commerce Disk 1 CD into the CD-ROM drive. Click Next. 15.. The WebSphere Commerce installation begins. A window indicating the percentage that has been completed is shown in the bottom corner of the screen. 16.. On the InstallShield wizard window, click Next to continue. 17.. From the Installation Complete window, you can access more information about WebSphere Commerce or exit the Installation wizard by clicking Finish. 19.3.2 Verify a custom installation To verify that your custom installation of WebSphere Commerce was successful, check the following: 1. The following libraries should exist on your iSeries system: – For WebSphere Commerce Server, WebSphere Commerce example files or WebSphere Commerce online help: library QWEBCOMM55 – For WebSphere Commerce Payments: libraries QCPYMS and QCPYMS55 – For WebSphere Application Server: library QEJBAS5 Chapter 19. OS/400: Two-tier remote database server 761 2. Depending on the components installed, the Integrated File System (IFS) on your iSeries system will have one or more of the following directories: – /QIBM/ProdData/CommerceServer55 – /QIBM/ProdData/CommercePayments/V55 – /QIBM/ProdData/WebAS5 3. (optional) Use iSeries Navigator to show what products have been installed on your iSeries system: a. On a PC where iSeries Navigator can be accessed, click Start -> Programs -> IBM iSeries Access for Windows -> iSeries Navigator. b. In the iSeries Navigator window, expand Management Central -> Endpoint Systems. c. Right-click the applicable iSeries system and click Inventory -> Collect. d. A new window opens. Ensure that the Software box is checked. Click OK to start the collection. e. Expand Management Central -> Task Activity -> Inventory. f. In the right-hand pane, a task for your iSeries system should be listed. Press the F5 key (refresh) until the Status shows Completed. g. Click Management Central -> Endpoint Systems -> iSeries_system_name -> Configuration and Service -> Software Inventory -> Installed Products. h. The right-hand pane will show a listing of products. Scroll to the bottom to view the WebSphere Commerce products. Note: For detailed verification, review the Installation Guide, IBM WebSphere Commerce V5.5 for OS/400. 19.3.3 WebSphere Application Server installation log The location of the WebSphere Application Server installation log file (LOG) can be found in either of the following directories: For a graphical install, the log file will be located on the Windows PC from where the install was completed. The log file will be located in the temporary folder of the PC user that was signed on when the installation was started. For example, on a Windows 2000 PC, the log file may be located in the :/Documents and Settings/PC_user/Local Settings/Temp/WebSphere directory. For a console install, the log file will be located on the iSeries system, in the /tmp/WebSphere directory. 762 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide The WebSphere Application Server installation is complete if the following message appears in the log file: Installation completed successfully 19.3.4 WebSphere Commerce installation log This log contains messages generated by the WebSphere Commerce installation wizard. The default location on the iSeries for this log file is /tmp/InstallLogs/install_datestamp_timestamp.log. Scroll to the bottom of this log file. The following messages should be shown (the following messages have been split across several lines for display purposes): CMN7704S:IBM WebSphere Commerce Installer has successfully copied file from \tmp \InstallShield \uninstall.qsh to \qibm \ProdData \CommerceServer55 \_uninst \uninstall.qsh CMN7720S:IBM WebSphere Commerce Installer internal Generic Catch Warning caught:COMMAND ENDED NORMALLY WITH EXIT STATUS 0. /QIBM/ProdData/CommerceServer55/bin/iSeriesFileAuth.sh 19.4 PTF installation After the installation of all the products described in the previous steps, you need to install the latest available cumulative PTF package, group PTFs and single PTFs. The cumulative PTF package level and single PTF levels are subject to change. Refer to the following product support page for the most current PTF information: http://www.ibm.com/software/webservers/commerce/wc_be/support.html In the order listed, we installed the following PTFs: 1. Cumulative PTF package. At the time of writing this redbook, we applied the cumulative PTF package level C3161520 to the iSeries server. 2. WebSphere Application Server runtime group PTFs: – V5R2 WebSphere Group PTF SF99245-2 (5733WS5), which includes: • V5R2 Java Group PTF SF99169-12 (5722JV1) • V5R2 Database Group PTF SF99502-8 (5722SS1) • V5R2 HTTP Group PTF SF99098-10 (5722DG1) – In addition to the Group PTF we applied an individual PTF for plug-in update. • SI09283 Chapter 19. OS/400: Two-tier remote database server 763 3. Hiper PTFs Group: – V5R2M0 GROUP HIPER PTF SF99519-64 4. WebSphere Commerce V5.5.0.1 Fix Pack and PTFs. At the time of writing this redbook, we installed the Fix Pack 1 that can be downloaded from the following URL: http://www-1.ibm.com/support/docview.wss?rs=494&uid=swg24005022 Note: The remote Configuration Manager client fix level must be the same as your Commerce Server. Download the appropriate fix pack for your Configuration Manager client and install the fix pack. For detailed information, refer to the fix pack documentation. In addition to the installation of Fix Pack 1, we also applied the following PTFs: – – – – – – – 5733PYS SI09321 VisaNet 5.5.0.1 PTF level 5733PYS SI09331 Configurator 5.5.0.1 PTF level 5733PYS SI09332 RedeployPayments script 5733PYS SI09465 Client API 5.5.0.1 PTF level 5733PYS SI09466 Framework 5.5.0.1 PTF level 5733PYS SI09467 WCSRealm 5.5.0.1 PTF level 5722SS1 SI04008 Java applications cannot use Network File System (NFS) mounted file systems – 5733WS5 SI09050 Fix for PQ74316 for WCS 5. We also applied the following microcode and operating system individual PTFs: – – – – – – – – – – – – – 764 MF30714 MF30734 MF30735 MF30736 MF30948 MF30847 MF30781 MF30675 MF30652 MF30650 SI08923 SI09664 SI09189 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 19.5 Configuration After installing the WebSphere Commerce components and PTFs, the environment must be configured. This section includes the following configuration steps to support the instance creation and to publish a store: Considerations before creating the instance Updating SQL packages Installing the Configuration Manager client Starting the Configuration Manager 19.5.1 Considerations before creating the instance The following list of considerations is intended as a guide prior to creating the WebSphere Commerce instance: The installation process creates an application server in the default WebSphere Application Server administrative domain. In our working example we are using a remote database iSeries server. On the iSeries system where WebSphere Commerce V5.5 is installed, use the WRKRDBDIRE command to ensure that there is an entry for the remote database where your instance’s schema will be created. Refer to 19.2.2, “Create a remote database entry” on page 759 for a detailed description. Ensure that your Java Virtual Machine is started with the correct file.encoding property file that matches the localized settings for the instance user profile created in 19.2.1, “Verify user profiles required during the installation” on page 759. To do this, complete the following steps: Use the DSPUSRPRF command to determine the Home Directory (HOMEDIR) of your SECOFR user profile. Ensure that the HOMEDIR exists. If it does not, create it. The HOMEDIR must contain a file named SystemDefault.properties, tagged as 819 and containing ASCII data. This file must specify the file.encoding property that matches your user profile. The file.encoding property must be specified on one line, must contain no spaces, and is case sensitive. If this file already exists, use the EDTF command to set the file.encoding property to one of the following values: Japanese Korean Simplified Chinese Traditional Chinese All other languages file.encoding=SJIS file.encoding=KSC5601 file.encoding=Cp1381 file.encoding=Cp950 file.encoding=ISO8859_1 Chapter 19. OS/400: Two-tier remote database server 765 If this file does not exist, copy it into your HOMEDIR using one of the following commands: Simplified Chinese: COPY OBJ(’/QIBM/ProdData/CommerceServer55/config/SystemDefault_CN.properties ’) TOOBJ(’home_directory/SystemDefault.properties’) TOCCSID(819) Korean: COPY OBJ(’/QIBM/ProdData/CommerceServer55/config/SystemDefault_KR.properties ’) TOOBJ(’home_directory/SystemDefault.properties’) TOCCSID(819) Traditional Chinese: COPY OBJ(’/QIBM/ProdData/CommerceServer55/config/SystemDefault_TW.properties ’) TOOBJ(’home_directory/SystemDefault.properties ’) TOCCSID(819) Japanese: COPY OBJ(’/QIBM/ProdData/CommerceServer55/config/SystemDefault_JP.properties ’) TOOBJ(’home_directory/SystemDefault.properties’) TOCCSID(819) All other languages: COPY OBJ(’/QIBM/ProdData/CommerceServer55/config/SystemDefault.properties’) TOOBJ(’home_directory/SystemDefault.properties’) TOCCSID(819) Once the new file is created, ensure that it contains the proper ASCII data. IBM recommends that you create WebSphere Commerce and WebSphere Payment instances within the default WebSphere Application Server instance. When you create either the WebSphere Commerce or WebSphere Payment instance, always specify the fully qualified host name in the appropriate Configuration Manager windows. You can create more than one WebSphere Commerce instance when the Configuration Manager GUI is open, as long as they are created under the same WebSphere Application Server instance. Before creating a WebSphere Commerce instance under a different WebSphere Application Server instance, you need to stop and then restart the Configuration Manager. 19.5.2 Updating SQL packages This step is required for remote database scenarios only and describes how to update the SQL packages. 766 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 1. Ensure that you do not have any of the following SQL packages in the remote database system by typing: WRKOBJ OBJ(QGPL/QSQ*) If you have any of the following SQL packages, delete them: – – – – – QSQCLIPKGA QSQCLIPKGC QSQCLIPKGL QSQCLIPKGN QSQCLIPKGS 2. Recreate the SQL packages by typing the following command in the Commerce system. This command will create the SQL packages in the remote Database server: RUNJVA CLASS(com.ibm.db2.jdbc.app.DB2PackageCreator) PARM(rdb_name user password) Where: – is the remote database name you specified in the WRKRDBDIRE command. – is any iSeries user who has authority to create new objects on the remote system. – is the password for the user profile used for the user parameter. In our example: RUNJVA CLASS(com.ibm.db2.jdbc.app.DB2PackageCreator) PARM(TORASSTR CAPPLAN ITS0RAL0) This command needs to be run only once, and creates the SQL packages needed to connect to the remote system. Note: The above step is required if you want to use a remote DataBase server. This command opens up a Java Shell Display. The following message should be displayed after the command has completed: Java program completed 3. Verify the creation of the SQL packages in the remote database system by typing: WRKOBJ OBJ(QGPL/QSQ*) Chapter 19. OS/400: Two-tier remote database server 767 19.5.3 Installing the Configuration Manager client Before you create or modify a WebSphere Commerce instance with Configuration Manager, you will need to install the Configuration Manager Client on a Windows system. Note: Ensure that the Windows 2000 system you will be using to install the Configuration Manager client code has Service Pack 3 or later installed. Install the Configuration Manager client as follows: 1. Insert the WebSphere Commerce CD 1 into the CD-ROM drive on your remote Windows system. 2. Navigate to the CD-ROM drive and double-click iSeriesClient.bat to start the InstallShield wizard. 3. Select the installation language, and click OK. 4. The Welcome window is displayed; click Next. 5. The Software License Agreement window displays. Select I accept the terms in the license agreement, and then click Next. 6. You can choose to select the default destination path \Program Files \WebSphere \CommerceServer55 or select Browse for another destination path. Once you have selected your destination path, click Next to continue. 7. Confirm your installation choices and click Next. (To modify your choices, select Back.) 8. The installation begins. A window indicating the percentage that has completed is shown in the bottom corner of the screen. 9. On the InstallShield wizard window, select Next to continue. 10.From the Installation Complete window, you can access more information about WebSphere Commerce or click Next. 11.To complete the installation, your Windows system must be restarted. Click the appropriate button to either restart now or restart later and click Finish. Note: The directory on the Windows system where the Configuration Manager Client code is installed will be denoted by in the remaining sections of this chapter. 768 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: Although the Configuration Manager client code can be installed on more than one Windows PC, creating a WebSphere Commerce instance or WebSphere Commerce Payments instance must be limited to one PC at any given time. Attempting to create instances from two or more PCs at the same time is not supported. 19.5.4 Starting the Configuration Manager To start the WebSphere Commerce Configuration Manager on iSeries, do the following: 1. Start the Configuration Manager server by doing the following: a. Log on to the iSeries ensuring that the profile has a *SECOFR user class, and is set up with the language-specific settings of either English or the language that you will choose as the default language for your instance. b. Start a QShell session by entering the following command: STRQSH Do the following in the QShell session: Change to the WebSphere Commerce server bin directory by issuing the following command: cd /QIBM/ProdData/CommerceServer55/bin c. Start the configuration manager server program by issuing the following command: config_server.sh [-port server_port_number ] The server_port_number parameter is optional. If you do not specify this parameter, the default port of 1099 is used. The Configuration Manager server will listen using this port number. If you specify the server_port_number, the value must be between 1024 and 65535 and not currently in use on the iSeries system. In our example: config_server.sh Note: If you are using a system where your primary language is not the same as the language in which you are creating your instance, then you must add the QSYSlanguage_feature_number library into your user profile’s library list. Otherwise the profile will try to locate it under QSYS . To add the language feature library, use the EDTLIBL command. Chapter 19. OS/400: Two-tier remote database server 769 d. If this is the first time that Configuration Manager is run on the system, you will see the following messages: Attaching Java program to /QIBM/ProdData/CommerceServer55/lib/ConfigManager.JAR. Attaching Java program to /QIBM/ProdData/CommercePayments/V55/wc.mpf.ear/lib/ibmjsse.JAR. Attaching Java program to /QIBM/ProdData/CommerceServer55/lib/Utilities.JAR. Attaching Java program to /QIBM/ProdData/CommerceServer55/lib/Enablement-BaseComponentsLogic.JAR. Attaching Java program to /QIBM/ProdData/CommerceServer55/lib/jtopen.JAR. Attaching Java program to /QIBM/ProdData/CommerceServer55/lib/xerces.JAR. Attaching Java program to /QIBM/ProdData/CommerceServer55/lib/sslite.ZIP. e. When the following messages are posted: Registry created. CMServer bound in registry. 2. Start the Configuration Manager client on the Windows system where the Configuration Manager client code was installed. Note: Be sure that the Windows system has been restarted after the installation of the Configuration Manager client code. a. Using a command line window on the Configuration Manager client system, change to the cfgmgr_installdir /bin directory. b. Start the Configuration Manager client by running the following command: configClient.bat -hostname iSeries_Host_name [-port server_port_number] Where: • iSeries_Host_name is the fully qualified host name of the server. • iserver_port_number Is the port number on the iSeries server on which the ConfigurationManager is listening. You only need to specify this value if the server is listening on a non-default port. • The port parameter is optional, but if it was specified in the config_server.sh command, it needs to be specified here. In our example, we typed the following from the D:\Program Files\WebSphere\CommerceServer55\bin directory: configClient.bat -hostname TORASCUB.TOROLAB.IBM.COM 770 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: The host name specified is all capital letters. c. Log in to Configuration Manager. The initial ID is webadmin and the initial password is webibm. If this is the first time you are logging in to Configuration Manager, you will be asked to change the password. d. Once your password has been accepted, the Configuration Manager window opens. 19.6 Instance creation Once you have installed all the required software, you can create a WebSphere Commerce instance and a WebSphere Commerce Payments instance. These instances can be created using the Configuration Manager. The following list describes all the tasks involved. Instance creation requirements when using a remote database Create a WebSphere Commerce instance Verifying the instance creation Completing the configuration Create a WebSphere Commerce Payments instance Completing the configuration for the Payments instance Verifying the instance creation 19.6.1 Instance creation requirements when using a remote database You will need to set up the database for remote access. To configure your iSeries system to use a remote database, ensure that there is an entry for the remote database where your instance’s schema will be created. 1. Ensure you have run the command commented in 19.5.2, “Updating SQL packages” on page 766.” 2. Start the DDM TCP/IP server on the remote iSeries system using either of the following: – The Network option under your remote iSeries system in iSeries Navigator – The following OS/400 command: STRTCPSVR SERVER(*DDM) Note: To check if the DDM server job is running on your iSeries, check for job QRWTLSTN in subsystem QSYSWRK. Chapter 19. OS/400: Two-tier remote database server 771 3. Create a user profile on the remote iSeries system. See 19.2.3, “Create an instance user profile” on page 759 4. Ensure that the instance user profile that you just created on the remote iSeries system has authority to the *SQLPKG objects in library QGPL by running the following command on one line: GRTOBJAUT OBJ(QGPL/*ALL) OBJTYPE(*SQLPKG) USER(instance_user_profile) AUT(*CHANGE) In our test example: GRTOBJAUT OBJ(QGPL/*ALL) OBJTYPE(*SQLPKG) USER(WC2) AUT(*CHANGE) During instance creation, it is recommended that you select Use iSeries Toolbox driver in the WebSphere window. 19.6.2 Create a WebSphere Commerce instance To create a new WebSphere Commerce instance, follow the steps described below: 1. Start the WebSphere Commerce Configuration Manager. For details, refer to 19.5.4, “Starting the Configuration Manager” on page 769 2. Under WebSphere Commerce, expand -> Commerce. 3. Right-click Instance List and select Create Instance. 4. Complete the Instance Creation wizard. For help with completing the windows and fields in the Instance Creation wizard, click Help on the Instance creation wizard. A Help button is available on each window of the wizard. The Help windows apply to all supported WebSphere Commerce platforms. In our scenario: – Instance tab: • Instance Name: wc2 • Instance’s root path: /QIBM/UserData/CommerceServer55/instances/wc2 • Merchant Key: • Site Admin: webadmin • Site Admin Password: – Schema tab: • • 772 Relation Database: TORASSTR Instance Password: WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – Web Server tab: • Hostname: TORASCUB.TOROLAB.IBM.COM • WebServer type: Select IBM HTTP Server • Primary Document Root: /QIBM/UserData/CommerceServer55/instances/wc2/web • Server Port: 80 • Configuration File Directory: /QIBM/UserData/CommerceServer55/instances/wc2/con – WebSphere tab: • • Data Source Name: WebSphere Commerce DB2 DataSource wc2 WebSphere Application Server Instance: default – Payments tab: • • Hostname: TORASCUB.TOROLAB.IBM.COM Profile Path: /QIBM/UserData/CommerceServer55/instances/wc2/xml/payment 5. When you have completed the necessary information, the Finish button is enabled. Click Finish to create the WebSphere Commerce instance. The time required to create an instance depends on the speed of your system. The progress bar that displays when you start creating the instance will indicate when the process has finished. In our scenario it took 40 minutes. 6. When instance creation is complete, a window appears containing a summary. Click OK to close the window. 7. Exit Configuration Manager by clicking Console and Exit. The following message is displayed: For security reasons,the Config Manager Server will now be stopped. Click OK to close Configuration Manager. 8. Exit from the command-line window where the Configuration Manager client was started. 9. Exit from the QShell session, on your iSeries system, where the Configuration Manager server was started. 19.6.3 Verifying the instance creation The configuration information for the new WebSphere Commerce instance is stored in the /QIBM/UserData/CommerceServer55/instances/instance_name /xml/instance_name .xml file. Chapter 19. OS/400: Two-tier remote database server 773 In our example, this is /QIBM/UserData/CommerceServer55/instances/wc2/xml/wc2.xml. Confirm that this file exists before checking the log files produced during instance creation. Creating a WebSphere Commerce instance produces the following log files located in the /QIBM/UserData/CommerceServer55/instances/instance_name /logs directory: auction.log createdb.log createdb.production.log GenPluginCfg.log messages.txt populatedb.err.log populatedb.log populatedb2.err.log populatedb2.log populatedbnl.err.log populatedbnl.log RESWCSID.txt Schema.log trace.txt WASConfig.log WASConfig.err.log In our example: /QIBM/UserData/CommerceServer55/instances/wc2/logs The database population part of instance creation is successful if the following logs are empty: populatedb.err.log populatedb2.err.log populatedbnl.err.log WASConfig.err.log Also, review the contents of the following logs to confirm they do not contain any errors: createdb.log messages.txt 774 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 19.6.4 Completing the configuration Ensure that on the remote system you change the instance user profile so that the instance library is set to the current library. To complete these changes, run the following command: CHGUSRPRF USRPRF(instance_name) CURLIB(instance_name ) Where instance_name is the name of the WebSphere Commerce instance. In our example: CHGUSRPRF USRPRF(wc2) CURLIB(wc2) 19.6.5 Create a WebSphere Commerce Payments instance For information about WebSphere Commerce Payments cassettes, refer to WebSphere Commerce Store Development Guide. To create a new WebSphere Commerce Payments instance, do the following: 1. Start the WebSphere Commerce Configuration Manager. For details, see 19.5.4, “Starting the Configuration Manager” on page 769 In cases where WebSphere Commerce Payments is on a separate node from WebSphere Commerce, ensure the you start the Configuration Manager server on the WebSphere Commerce Payments node. 2. Under WebSphere Commerce expand -> Payments. 3. Right-click Instance List. 4. From the resulting pop-up menu, select Create Payments Instance. The Payments Instance Creation wizard starts. 5. Complete the Payments instance creation wizard information. For help with completing the windows and fields in the Payments instance creation wizard, click Help in the Instance Creation wizard. A Help button is available on each panel of the wizard. The Help windows apply to all supported WebSphere Commerce platforms. Important: When completing the WebSphere Commerce Payments instance creation wizard, ensure that the value you enter in the Site Admin ID field is the WebSphere Commerce Site Administrator ID. Instance tab: – General tab: • • Instance name: WPM Instance Password: Chapter 19. OS/400: Two-tier remote database server 775 – OS/400 tab: • • • WebSphere Application Server Instance: default WebSphere node name: TORASCUB WebServer Instance name: wpm – DataBase tab: • • • Remote DataBase name: TORASSTR DataBase user name: capplan DataBase user password: its0ral0 – WebServer tab: • • Hostname: TORASCUB.TOROLAB.IBM.COM WebServer Type: IBM HTTP SERVER – WCRealm tab: • • WC Hostname: TORASCUB.TOROLAB.IBM.COM WebServer Type:IBM HTTP SERVER 6. When you have completed all the necessary information, the Finish button is enabled. Click Finish to create the WebSphere Commerce Payments instance. The time required to create an instance depends on the speed of your system. The progress bar that displays when you start creating the instance will indicate when the process has finished. In our case, this took 25 minutes. 7. Exit Configuration Manager by clicking Console and Exit. 8. Click OK when you receive the message “Security reasons,the Config Manager Server will now be stopped”. 9. Exit from the command-line window where the Configuration Manager client was started. 10.Exit from the QShell session on your iSeries system where the Configuration Manager server was started. 19.6.6 Completing the configuration for the Payments instance Ensure that on the remote system you change the instance user profile so that the instance library is set to the current library. To complete these changes, run the following command: CHGUSRPRF USRPRF(Payment_instance_name) CURLIB(payment_library) Where payments_instance_name is the name of the WebSphere Commerce Payments instance. 776 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide In our case: CHGUSRPRF USRPRF(CAPPLAN) CURLIB(WPM) 19.6.7 Verifying the instance creation The configuration information for the new WebSphere Commerce Payments instance is stored in the /QIBM/UserData/CommerceServer55/instances/payments_instance_name /xml/payments_instance_name.xml file. Creating a WebSphere Commerce Payments instance produces a log file called Configurator.1.log in the /QIBM/UserData/CommerceServer55/instances directory. Instance creation is successful if the Configurator.1.log file is empty. 19.7 Enabling SSL for IBM HTTP Server PrioOr to start the WebSphere Commerce server you have to enable the SSL in your HTTP Server. For detailed information on how create a local Certificate Authority, obtain a server certificate, and verify the CA trust using OS/400 V5R2, refer to the IBM HTTP Server (powered by Apache) for iSeries, SG24-6716 redbook. 19.8 Start the application servers Once you have created successfully the WebSphere Commerce and WebSphere Commerce Payments instances, they can be started by following the procedures found in this section. Important: Prior to start the application servers instances (Commerce and Payment), ensure that IBM HTTP Server and the HTTP instances for WebSphere Commerce and WebSphere Commerce Payments have been started. To start or stop an application server on iSeries, do the following: 1. Ensure the WebSphere Application Server subsystem is started. Chapter 19. OS/400: Two-tier remote database server 777 2. Start a QShell session by entering the following from an OS/400 command line: => QSH 3. Do one of the following: To start an application server, issue the following command: /QIBM/ProdData/Webas5/Base/bin/startServer application_server_name -instance WAS_instance_name In our example: /QIBM/ProdData/Webas5/Base/bin/StartServer server1 To stop an application server, issue the following command: /QIBM/ProdData/Webas5/Base/bin/stopServer application_server_name -instance WAS_instance_name Where application_server_name is the name of the application server you want to start. 19.8.1 Start the WebSphere Commerce Payment instance To start or stop the Payment Instance on iSeries, do the following: 1. Ensure the WebSphere Application Server subsystem is started. a. Ensure the Commerce Application Server is started. b. Ensure the HTTP Payment Server is started. 2. Start a QShell session by entering the following from an OS/400 command line: => QSH a. To start the WebSphere Commerce Payments application server, issue the following command: QIBM/ProdData/WebAS5/Base/bin/startServer wpm_application_server_name In our example: /QIBM/ProdData/WebAS5/Base/bin/startServer wpm_Commerce_Payments_Server b. Change to the /QIBM/ProdData/CommercePayments/v55/bin directory and enter the following: IBMPayServer wpm _instance_name instance_password In our example: IBMPayServer wpm its0ral0 778 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 19.8.2 Stop the WebSphere Commerce Payments instance To stop an WebSphere Commerce Payments application server, issue the following commands. 1. Stop the WebSphere Commerce Payments application server: /QIBM/ProdData/Webas5/Base/bin/stopServer wpm_application_server_name -instance WAS_instance_name Where wpm_application_server_name is the name of the WebSphere Payment application server you want to start. In our example: /QIBM/ProdData/WebAS5/Base/bin/stopServer wpm_Commerce_Payments_Server 2. Stop the IBM Payment Server™ from: /QIBM/ProdData/CommercePayments/v55/bin/StopIBMPayServer PaymentsInstanceName [PaymentsInstancePassword] In our working example: /QIBM/ProdData/CommercePayments/v55/bin/StopIBMPayServer wpm its0ral0 19.8.3 Start the WebSphere Commerce instance To start the WebSphere Commerce instance application server, do the following: 1. Ensure the WebSphere Application Server subsystem is started. 2. Start a QShell session by entering the following from an OS/400 command line: => QSH To start an application server, issue the following command: /QIBM/ProdData/Webas5/Base/bin/startServer WC_application_server_name -instance WAS_instance_name In our example: /QIBM/ProdData/Webas5/Base/bin/StartServer WC_wc2 19.8.4 Stop the WebSphere Commerce instance To stop the WebSphere Commerce application server, issue the following command: /QIBM/ProdData/Webas5/Base/bin/stopServer WC_ application_server_name -instance WAS_instance_name Where WC_application_server_name is the name of the application server you want to stop. Chapter 19. OS/400: Two-tier remote database server 779 19.9 Publish a store This section describes the steps for publishing the B2BDirect.sar (ToolTech) sample store using WebSphere Commerce Administration Console. 1. From a windows system start the Internet Explorer and access the following URL: http://:8002/adminconsole Where is the name of your commerce system. In our example: http://torascub.torolab.ibm.com:8002/adminconsole 2. From WebSphere Commerce console using the wcadmin user. 3. Select Site and click OK. 4. From the menu bar, select Store Archives -> Publish Store. 5. Select B2BDirect.sar (ToolTech) and then click Next. 6. Click Next on the Summary page and then click Finish. 7. Click OK in the New Web window and the Publishing process will begin to run. If you want to check the publishing status, you can click Refresh. Once the Store has been published you can test it. Note: Ensure that the commerce_instance.xml configuration file is properly configured to use Payment. The file is located in the following directory: /QIBM/UserData/CommerceServer55/intances/instance_name/xml/instance_name. xml Verify the Payment Manager admin user is set to the one you specified during the instance creation. In our scenario the value is: PMAdminId="wcadmin" Additionally, verify that Use Payment entry is set to true. Stop and start the Commerce Payments Server Instance and WebSphere Commerce instance StopServer wpm_Commerce_Payments_Server StartServer wpm_Commerce_Payments_Server StopServer WC_wc2 StartServer WC_wc2 Stop and Start IBM Payment Server by typing the following command: 780 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide StopIBMPayServer “PaymentInstance“ “password” IBMPayServer “PaymentInstance“ “password” In our working example we entered: StopIBMPayServer wpm its0ral0 IBMPayServer wpm its0ral0 Note: Run StopIBMPayServer and IBMPaySever located in the /QIBM/ProdData/CommercePayments/V55/bin directory. 19.9.1 Pre-compile the JSPs files Compiling the JavaServer Pages will significantly reduce the amount of time needed to load the WebSphere Commerce tools and stores. To batch compile JavaServer Pages (JSP) files, do the following: 1. Log on to the iSeries server using the *QSEOFR user profile. 2. To mass compile the JSP files run the following commands using the QSHELL (on one line each): a. Enter the following command: STRQSH b. Change to the /QIBMProdData/webas5/base/bin/ directory. c. Run the JspBatchCompiler command. JspBatchCompiler -enterpriseapp.name [-instance ] [-webmodule.name ] [-cell.name ] [-node.name ] [-server.name ] [-classloader.parentFirst ] [-classloader.singleWarClassloader ] [-filename ] [-keepgenerated ] [-verbose ] [-deprecation ] In our example we ran the following commands from the QShell prompt: JSPBatchCompiler -enterpriseapp.name WC_wc2 -webmodule.name Stores.war -server.name WC_wc2 Note: Several errors will be logged during this process, which we ignored. 19.10 Back up WebSphere Commerce and components This section describes how to create a backup for WebSphere Commerce and its components. Chapter 19. OS/400: Two-tier remote database server 781 Ensure that your iSeries backup strategy includes all things related to WebSphere Commerce, not only the product, but also all objects related to your WebSphere Commerce node. In our examples, we used the following commands: Directory User Data WebSphere Commerce SAV DEV('/qsys.lib/wcbkp.lib/INST_wcUR.file') OBJ(('/qibm/UserData/commerceserver55') WebSphere Payment SAV DEV('/qsys.lib/wcbkp.lib/INST_wpUR.file') OBJ(('/qibm/UserData/CommercePayments') WebSphere Application Server SAV DEV('/qsys.lib/wcbkp.lib/INST_wasUR.file') OBJ(('/qibm/UserData/webas5') Where: – wcbkp is our library created for backups – INST_wcUR is a save created for WebSphere Commerce UserData Directory – INST_wpUR is a save created for WebSphere Payment UserData Directory – INST_wasUR is a save created for WebSphere Application Server UserData Directory DataBase Library In our scenario we used: SAVLIB LIB(WC2) DEV(*SAVF) SAVF(WCBKP/WCLIB) ACCPTH(*YES) SAVLIB LIB(WPM) DEV(*SAVF) SAVF(WCBKP/WPMLIB) ACCPTH(*YES) Where: – WCBKP is our library created for backups – WCLIB is a save created for DataBase Library backup – WPMLIB is a save created for Payments Library backup For more detailed information about backup on iSeries, see the Backup and Recovery Guide, found by selecting the System Management link in the iSeries Information Center at: http://publib.boulder.ibm.com/pubs/html/as400/infocenter.html 782 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 19.11 Uninstall WebSphere Commerce This section describes how to uninstall various WebSphere Commerce components. 19.11.1 Uninstall WebSphere Commerce Note: Uninstalling WebSphere Commerce from your iSeries system will also uninstall WebSphere Commerce Payments if the Payments product is installed on the same iSeries system. To uninstall WebSphere Commerce, do the following: 1. Start a QShell session by entering the following command: STRQSH 2. Change your current directory to the WebSphere Commerce uninstall directory: cd /QIBM/ProdData/CommerceServer55/_uninst 3. Run the uninstall command: uninstall.qsh 4. When the Welcome message displays, enter 1 to get the next window. 5. The WebSphere Commerce directory displays along with the features that will be uninstalled. Press Enter to begin uninstalling the product. Note: The listing will show many features that may not be OS/400 specific, or may duplicate an OS/400 entry. These extra entries can be ignored and will not cause any problems during the uninstall. The uninstallation of WebSphere Commerce begins with the message: Uninstalling product... When the uninstallation is complete, the following message will be displayed: The InstallShield Wizard has successfully uninstalled IBM WebSphere Commerce. Choose Finish to exit the wizard..... InstallShield Wizard has successfully uninstalled IBM WebSphere Commerce. Choose Finish to exit the wizard. Press Enter to exit the wizard. 6. Press the F3 function key to exit the QShell session. Chapter 19. OS/400: Two-tier remote database server 783 19.11.2 Uninstalling Configuration Manager client To uninstall the Configuration Manager client on the Windows PC where the Configuration Manager client is installed, do the following: 1. Navigate to the cfgmgr_installdir directory, where cfgmgr_installdir is the directory where the Configuration Manager client is installed. 2. In the cfgmgr_installdir directory, navigate to the _uninst directory. 3. Double-click the file uninstall.exe. 4. A WebSphere Commerce window displays. Select the preferred language and click OK. 5. On the Welcome Page, click Next. 6. The next window shows the cfgmgr_installdir directory. 7. Click Next to begin uninstalling the Configuration Manager client code. 8. On the InstallShield Wizard window, click Finish to close the wizard. Alternatively, you can select the Add/Remove Programs option from the Control Panel on the Windows PC. Clicking Change/Remove will begin the uninstall program. Follow steps 4 through 8 as above. Note: The cfgmgr_installdir directory may remain after the uninstallation completes. At this time, you can delete this directory on your Windows PC. 19.11.3 Uninstalling WebSphere Application Server For information on uninstalling WebSphere Application Server, refer to the installation and initial configuration guide available through the iSeries WebSphere Application Server library, found at: http://www.ibm.com/servers/eserver/iseries/software/websphere/wsappserver/d ocs/docws50.html 784 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Part 5 Part 5 Integration and customization scenarios This part of the redbook provides IT architects, IT specialists and developers with the knowledge required to implement and customize integrated solutions including WebSphere Commerce Analyzer, MQ, and e-mail. © Copyright IBM Corp. 2003. All rights reserved. 785 786 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 20 Chapter 20. Commerce analytics This chapter contains information pertaining to the WebSphere Commerce analytical tools. The topics covered in this chapter include a commerce analytics overview, WebSphere Commerce Analyzer architecture, integrating WebSphere Commerce Analyzer with WebSphere Commerce, and the customization of analytical reports. The business analytics overview outlines the importance of such analytical tools in business scenarios, describes the new analytical features included with WebSphere Commerce V5.5, and illustrates the system architecture used throughout this chapter. The integration of WebSphere Commerce Analyzer is discussed in various steps, which are specific to the working example detailed in this chapter. The chapter concludes with a discussion of the reporting framework and the customization-based business reports. Data should be a company’s greatest asset; this chapter is dedicated to explaining why. This chapter includes the following topics on commerce analytics: Commerce analytics overview WebSphere Commerce Analyzer integration Create customized reports © Copyright IBM Corp. 2003. All rights reserved. 787 20.1 Commerce analytics overview This section provides a general overview of commerce analytics and how it relates to WebSphere Commerce V5.5. By definition, the term analytics means a method of logical analysis. The purpose of commerce analytics is to learn of trends in customer data through a defined method by analyzing the data to make business decisions. Through the use of timely commerce analytics, enterprises can increase their profitability. This section includes the following topics: Business drivers for commerce analytics WebSphere Commerce analytical features Reports overview Analytics to action WebSphere Commerce Analyzer architecture Where to find more information 20.1.1 Business drivers for commerce analytics It is no longer enough to have a basic commerce Web site. In order to remain competitive and construct successful business solutions, businesses must understand the trends from their transactional data and use this information to make business decisions. The knowledge needed to make these well-informed business decisions is the result of obtaining and analyzing commerce data. Successfully acquiring data intelligence directly influences overall success in targeting customers, searching for answers, and forming future strategies. There are many important factors that drive businesses in the direction of analytics, such as the following: Data volumes increasing Data sources expanding Market sophistication and expectations increasing It is no longer enough to have a basic e-commerce Web site in a competitive marketplace. There is a need to deliver timely analytics, as you would expect from mission-critical applications. Growing competition Competition will typically increase analytical processes and intelligence gathering in order for companies to stay in business. For example, Company A significantly increases its sales of a certain product, whereas rival Company B’s sales of the same product remain constant (both products are being sold 788 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide at the same price). The growing competition will force Company B to increase data analysis in order to uncover possible reasons for the reduction in sales. Shortened time frames Today’s competitive markets demand quick and timely reactions from businesses. The fact that businesses are forced to make critical adjustments in smaller time frames is not always the result of competition. For example, a company that sells clothing is constantly in need of adjusting its products because clothing styles tend to change at a rapid pace. A company such as this can use business analytics to uncover a similar change in customer preferences and adjust accordingly. Customer indistinctness Customer indistinctness can make it difficult for a company to recognize its most profitable customers for specific products. Using data to make decisions can help match products to different customer markets. These markets are often based on multiple factors, including age, interests, and location. For example, an online book store that utilizes business analytics could conclude that people from city A tend to purchase mostly magazine subscriptions from their commerce Web site. The business could then create an effective marketing campaign to specifically target those customers. 20.1.2 WebSphere Commerce analytical features IBM WebSphere Commerce V5.5 includes the following analytical products: IBM WebSphere Commerce Analyzer V5.5 IBM DB2 Universal Database V8.1 (includes warehousing component) IBM DB2 Intelligent Miner for Data V8.1.1 Tivoli Web Site Analyzer V4.2 Figure 20-1 on page 790 depicts the evolution of features provided in releases of WebSphere Commerce Analyzer. Chapter 20. Commerce analytics 789 WC V5.5 2Q 2003 WC V5.4 1Q 2002 WCS V5.1 1Q 2001 WCS V4.1 1Q 2000 Operational Reporting WCA Entry WCA Advanced Edition V1.1 Datamart Integrated 3rd Party Reporting (Brio) WCA Entry V5.4 WCA Advanced Edition V1.2 Datamart Integrated 3rd Party Reporting (Business Objects) B2B Reporting WCA V5.5 In-the-box Reporting Pre-constructed Datamart fully expandable) Data Extract, Transform & Load fully customizable Integrated Data Mining & Custom Modeling Integrated Clickstream Analytics Figure 20-1 WebSphere Commerce Analyzer features by release IBM WebSphere Commerce Analyzer V5.5 Unlike its predecessor, WebSphere Commerce Analyzer Entry Edition, WebSphere Commerce Analyzer V5.5 uncovers customer trends and behavior through detailed data analysis. This is made possible because of various analytical tools, including data mining and data warehousing technology. One of the major advantages of implementing WebSphere Commerce Analyzer is the output: predefined and customizable business reports. These reports give business managers the opportunity to analyze customer trends and characteristics, draw meaning from the data, and create effective business decisions as a result. WebSphere Commerce Analyzer offers various data analysis and data reporting features including: A data mart installed on a host separate from WebSphere Commerce. Data structuring tools for extracting data from the WebSphere Commerce database, structuring the data in more useful, analytical forms, and transferring the data to the data mart. Data mining tools for recognizing different trends within the extracted data. Reporting framework for creating and analyzing both predefined and customizable business reports. The reporting framework is discussed in greater detail in 20.3, “Create customized reports” on page 868. 790 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: For a more detailed description about these tools and how they work, refer to 20.1.5, “WebSphere Commerce Analyzer architecture” on page 798. IBM DB2 Universal Database V8.1 IBM DB2 Universal Database V8.1, Enterprise Server Edition includes a data warehousing component that is used to manage the replication of transactional data from the WebSphere Commerce instance database to the WebSphere Commerce Analyzer datamart database. IBM DB2 Intelligent Miner for Data V8.1.1 Data mining has become one of the most significant aspects in increasing one’s business intelligence. DB2 Intelligent Miner for Data V8.1.1 uses data mining technology to extract customer trends and characteristics within the data mart. Intelligent Miner includes 26 predefined mining models and an unlimited number of user-definable models. Data mining allows a business to customize and structure data, providing marketing information to successfully target customers and maximize customer satisfaction. Tivoli Web Site Analyzer V4.2 Tivoli Web Site Analyzer V4.2 focuses on Web site driven data, including Web navigation, site content, usage statistics, etc. This produces additional data, which is useful when merged with transactional data. The relationship between customer transactions and site navigation become more clear. For example, a commerce site may have an outdated component of the infrastructure that is costing the business a substantial amount of money to operate. Using Tivoli Web Site Analyzer functions, the business is able to track and analyze the popularity of the Web site component along with customer transactional data (possibly total generated revenue from that site component) and develop a strategy based on this intelligence. Chapter 20. Commerce analytics 791 Web Server + Plugin W e b S p h e re C o m m e rc e node W e b S p h e re A p p lic a tio n S e rv e r W e b S p h e re C o m m e rc e A n a ly z e r n o d e W e b S p h e re C o m m e rc e A n a ly z e r W e b S p h e re C o m m e rc e in sta n ce a p p lic a tio n se rv e r W e b S p h e re C o m m e rc e P a y m e n ts a p p lic a tio n s e rv e r D B 2 In te llig e n t M in e r fo r D a ta D B 2 S e rv e r W C P a y m e n ts d a ta b a s e W C in s ta n c e d a ta ba se D B 2 S e rv e r D a ta m a rt d a ta b a s e D B 2 C o n tro l d a ta b a s e Figure 20-2 Solution components for WebSphere Commerce V5.5 analytics Figure 20-2 depicts the software solution components of WebSphere Commerce V5.5 analytics. 20.1.3 Reports overview This section describes the WebSphere Commerce reporting framework, operational reports, business intelligence reports, and ISV partner report integration kits. WebSphere Commerce report framework The WebSphere Commerce report framework allows you to define a report by using XML and create the report input and output views using JavaServer Pages (JSPs). Out of the box, there are two report types included with WebSphere Commerce that use the WebSphere Commerce report framework: WebSphere Commerce operational reports WebSphere Commerce business intelligence reports The reports, predefined or custom, reside on the WebSphere Commerce node, and are accessible from different locations within the WebSphere Commerce Accelerator. WebSphere Commerce operational reports The WebSphere Commerce operational reports use the report framework to retrieve transactional data from the WebSphere Commerce instance database. 792 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide The operational reports are driven by parameters and roles. To access the operation reports, log on to the WebSphere Commerce Accelerator and select Sales -> Operational Reports. The operational reports are categorized as follows, as seen in Figure 20-3: Store Activity Reports Order Status Reports Orderitem Status Report Product Sales Report Region Report Figure 20-3 WebSphere Commerce operational reports In addition to the listed operational reports, there are order management reports accessible by selecting Sales -> Order Management Reports, which include the following categories: Order Summary Overdue Backorders WebSphere Commerce Analyzer business intelligence reports If WebSphere Commerce Analyzer is installed and configured, the business intelligence reports are accessible from the WebSphere Commerce Accelerator. The business intelligence reports differ from the operational reports, in that the data displayed in the reports is retrieved from the WebSphere Commerce Analyzer datamart database. Chapter 20. Commerce analytics 793 The data in the datamart is replicated from the WebSphere Commerce instance database, data mined and stored in a structured fashion. Like the operational reports, the business intelligence reports use the report framework technologies of XML files containing SQL queries, and JSPs for input and output views stored on the WebSphere Commerce node. To access the business intelligence reports for the WebSphere Commerce Analyzer, log on to the WebSphere Commerce Accelerator and select Store -> Business Intelligence Reports. The business intelligence reports are categorized as seen in Figure 20-4. Figure 20-4 WebSphere Commerce Analyzer business intelligence reports Each of the business intelligence reports categories listed has many reports and filters. For example, the Product business intelligence reports are related to sales trends of products. By clicking Product reports, you will then see Units Sold, Sales Value and Units Sold, Sales Value, and Units Abandoned reports. Each report has the ability to be generated by date qualifiers. WebSphere Commerce Analyzer report integration kits In addition to providing a reporting framework that allows for predefined and customized reports (operational and business intelligence), the WebSphere Commerce Analyzer has Independent Software Vendor (ISV) partner support for the following reporting integration kits: Brio 794 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Business Objects Crystal The ISV partner reporting tools provide for more customization and graphical reports. 20.1.4 Analytics to action The business driver example in 20.1.1, “Business drivers for commerce analytics” on page 788, which discusses the idea of creating a marketing campaign based on the data analysis, highlights the concept of a closed loop or analytics to action. This idea is relatively simple, but requires some further detail. Continuing to use the online book store as an example, the following general scenario takes place. Customers purchase products off the Web site in the form of books, magazines, etc. In doing so, they create numerous types of data, including personal, transaction, etc. The data is stored in a database and is then transformed into useful information. Business managers and marketing managers analyze this information in order to uncover customer trends, transactional information, etc. Once analyzed, the managers create a business campaign that targets customers and reflects their findings. When the customers return to the online store, they react to the campaign and generate new customer data. This is called a closed-loop cycle or analytics to action. Within the commerce analytics domain, there are three user types that we will highlight: System administrator/site administrator Business analysts Business managers In an actual business environment, it is common to see more than three people fill these roles. The system administrator is in charge of all technical issues, including installation and configuration of software components, DB2 database management, and system maintenance. The business analyst mines the data and creates reports analyzing the output extracted from the WebSphere Commerce Analyzer tools. In turn, the business manager evaluates these data reports in order to develop more effective business strategies. Depending on the effectiveness of the strategies, customers will react in a specific way and generate new data in the system. Chapter 20. Commerce analytics 795 1 Capture Customer Shopping/Ordering Activity 2 Extract, Transform, Load Data WebSphere Commerce node Web Server + Plugin WebSphere Application Server WebSphere Commerce Analyzer node WebSphere Commerce Analyzer WebSphere Commerce instance application server WebSphere Commerce Payments application server DB2 Intelligent Miner for Data DB2 Server WC Payments database 5 WC instance database DB2 Server Datamart database DB2 Control database Customer 3 Mine and Analyze Data for Trends Create Campaign/Promotion 4 Data Trends used to Create Customer Profiles Figure 20-5 Analytics-to-action The main objective in business analytics is to create effective marketing campaigns to promote the sale of products, based on analyzing the trends in customer data. The five steps in the analytics-to-action (closed-loop) are as follows (see Figure 20-5): 1. Capture Customer Shopping/Ordering Activity (automatic) After the data capture function is enabled on the WebSphere Commerce node, customer data is captured in the WebSphere Commerce instance database. When a shopper accesses the WebSphere Commerce store, the following types of data are captured: – Customer profile data – Transaction/shopping data – Navigational data Depending on the format of the site, a customer will either register before purchasing products online or during the transaction. The customer profile 796 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide data includes information such as name and address and demographic information such as gender, age group, and interests. This information can be used as a qualifier when mining specific criteria of the user information. Transactional shopping data can be analyzed to understand customer buying behavior. Transactions also help the business analysts understand which products and campaigns are effective. Navigational data demonstrates the path taken by a user to navigate the site to the desired information and which products have been viewed during Web visits. 2. Extract, Transform and Load Data (automatic) Once the data has been captured during the customer shopping activity in the WebSphere Commerce instance database, the data is extracted to a remote WebSphere Commerce Analyzer node datamart database using the DB2 replication functionality. The extraction interval and database tables to replicate are configurable. This process can be configured to run automatically as a scheduled event. During this extraction process, the customer data is structured (transformed and loaded) into tables and stored in the datamart database. The data is organized in a way that will become useful in creating business reports. Since the business reports will typically address a specific interest of the company, the data is structured categorically. For example, certain tables may contain transaction history, whereas others include user registration data. 3. Mine and Analyze Data for Trends The business managers use the data mining technology provided by the IBM DB2 Intelligent Miner for Data, included with WebSphere Commerce V5.5, to run a user-defined mining model. The way in which managers choose to mine customer data is very flexible. Data mining basically allows managers to customize their methods of organizing data in a way that uncovers desired customer trends. In other words, if interested in finding trends in why customers remove items from their shopping carts, managers are able to mine data in a way that helps identify this trend based on certain criteria. 4. Data trends used to Create Customer Profiles Once the data is mined, predefined or customized reports are used to present and identify patterns and trends in the customer data. These data patterns can be imported into a software program used for marketing purposes and are representative of customer characteristics. 5. Create Campaigns/Promotions Based on trends in the data, managers are able to create a new customer profile and use it in a marketing campaign. This includes initiatives such as suggestive selling, cross-sell, up-sell, advertise discount, and advertise Chapter 20. Commerce analytics 797 coupons. When the original customer returns to visit the online store or is contacted via e-mail activity, they are targeted based on the data gathered from previous visits. 20.1.5 WebSphere Commerce Analyzer architecture Thus far we have looked at the commerce analytics functionality from a high-level perspective. In this section we will take a closer look at the low-level architecture of how WebSphere Commerce Analyzer is integrated with WebSphere Commerce. In the previous section, we highlighted the five steps for analytics-to-action. In this section, we will limit the WebSphere Commerce Analyzer architecture discussion to the following steps: Extract, transform and load data Mine data Figure 20-6 on page 799 depicts how the components interact in the WebSphere Commerce Analyzer architecture. The e-Commerce ETL (extract, transform and load) box shown in Figure 20-6 on page 799 represents the DB2 UDB replication of data from the WebSphere Commerce instance database to the WebSphere Commerce Analyzer datamart database. For a more complete understanding of how DB2 UDB replication works, refer to Figure 20-7 on page 800. IBM DB2 Intelligent Miner for Data V8.1.1 mines the data in the WebSphere Commerce Analyzer datamart database. It discovers patterns or trends in the data. These patterns can be analyzed by the business analyst and business manager to determine the course of action to take based on the trend found. 798 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Customer Shop Store Web Server + Plugin WebSphere Commerce node Marketing Manager Accelerator Reports WebSphere Application Server WebSphere Commerce instance application server DB2 UDB Server WC instance database WebSphere Commerce Analyzer node DB2 UDB Server Mining results and scores DB2 Intelligent Miner for Data Mining models DB2 UDB Warehouse Center e-Commerce ETL Datamart database Miner process automation DB2 Control database WebSphere Commerce Analyzer Figure 20-6 WebSphere Commerce Analyzer architecture Figure 20-7 on page 800 defines four servers including source, capture control, apply control, and target. The source server corresponds to the WebSphere Commerce node where the WebSphere Commerce instance database (source) resides. The capture control server is also running on the WebSphere Commerce node. This server manages the capture of customer shopping activity in the table spaces that have been added to the WebSphere Commerce instance database during the configuration for the WebSphere Commerce Analyzer. The apply control server is the DB2 UDB Warehouse Center, which resides on the WebSphere Commerce Analyzer node. The apply control server (Warehouse Center) is used to manage the replication of data between the WebSphere Commerce instance database on the WebSphere Commerce node and the datamart database on the WebSphere Commerce Analyzer node. The target server is the WebSphere Commerce Analyzer node where the datamart database resides. Chapter 20. Commerce analytics 799 Figure 20-7 DB2 UDB replication 20.1.6 Where to find more information Refer to the following for more information on commerce analytics and supporting software: IBM WebSphere Commerce Analyzer V5.5 – Additional Software Guide, IBM WebSphere Commerce V5.5, chapter on IBM WebSphere Commerce Analyzer – Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide – Datamart Reference, IBM WebSphere Commerce Analyzer V5.5 product guide – Technical Reference, IBM WebSphere Commerce Analyzer V5.5 product guide Readme.txt found on the WebSphere Commerce Analyzer V5.5 CD Enhance Your Business Applications: Simple Integration of Advanced Data Mining Functions, SG24-6879 redbook IBM DB2 Intelligent Miner for Data V8.1.1, found at: http://www.ibm.com/software/data/iminer/fordata/index.html 800 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide IBM DB2 Universal Database V8.1, Enterprise Server Edition, found at: http://www.ibm.com/software/data/db2/udb Detailed information on DB2 replication can be found in the Replication Guide and Reference, IBM DB2 UDB V8.1 product guide found at the following URL under the Administration heading: http://www.ibm.com/cgi-bin/db2www/data/db2/udb/winos2unix/support/v8pubs.d2 w/en_main 20.2 WebSphere Commerce Analyzer integration This section provides a working example scenario on how to integrate IBM WebSphere Commerce Analyzer V5.5 and IBM WebSphere Commerce V5.5, Business Edition. The ITSO scenario provides a first-hand account about what we did to implement the solution, including tips and workarounds. The real value in the redbook procedure is that it provides context with example values specific to the given scenario. This information can be applied and referenced in combination with the product documentation for your given customer scenario. Note: The scenario documented in this section is intended to be used with the procedures found in the following WebSphere Commerce product guides: Additional Software Guide, IBM WebSphere Commerce V5.5, chapter on IBM WebSphere Commerce Analyzer Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide. The objectives of the ITSO integration scenario for WebSphere Commerce Analyzer and WebSphere Commerce are as follows: Outline the necessary steps for successfully integrating WebSphere Commerce Analyzer with WebSphere Commerce. Avoid integration pitfalls by providing key information in note boxes in the ITSO documented procedure. Discuss the significance of the background processes being executed during the configuration. The WebSphere Commerce Analyzer integration procedure is organized as follows: WebSphere Commerce Analyzer integration scenario overview WebSphere Commerce node configuration WebSphere Commerce Analyzer node installation Chapter 20. Commerce analytics 801 WebSphere Commerce Analyzer pre-configuration WebSphere Commerce Analyzer database configuration Prepare promote steps WebSphere Commerce Analyzer business options configuration Post-configuration steps Accessing out-of-box Accelerator reports Change passwords 20.2.1 WebSphere Commerce Analyzer integration scenario overview The ITSO provided integration scenario includes the WebSphere Commerce node and the WebSphere Commerce Analyzer node as depicted in Figure 20-8. The ITSO scenario requires that the WebSphere Commerce node is already installed and configured. This section is organized as follows: Hardware and software prerequisites Hardware used in the ITSO runtime environment Software used in the ITSO runtime environment Software installation paths and variables WebSphere Commerce node WebSphere Commerce Analyzer nodeCommerce WebSphere node (wc55be) WebSphere Commerce instance application server WebSphere Commerce Payments application server DB2 Server WC Payments db (wcpay1) WC instance db (wc1) Web Server + Plugin 1 Web Server + Plugin WebSphere Application Server DB2 Control db (dwctrldb) WebSphere Commerce Analyzer WebSphere Commerce Analyzer node (wca1) DB2 Intelligent Miner for Data WebSphere Application Server WebSphere Commerce Analyzer DB2 Server WebSphere Commerce instance application server Datamart db (wcamart) DB2 Control db (wcactrl) WebSphere Commerce Payments application server DB2 Intelligent Miner for Data DB2 Server WC Payments db (pay1) WC instance db (wc1) DB2 Server Datamart db (wcamart) DB2 Control db (wcactrl) Figure 20-8 ITSO integration scenario for WebSphere Commerce Analyzer Within our test environment, we choose to build the solution with two nodes. In a production environment, it is very common for the Database Server node to be separate and techniques such as Web clusters and application clusters used. 802 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Hardware and software prerequisites For detailed information on WebSphere Commerce V5.5 hardware and software requirements, refer to the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide. Hardware used in the ITSO runtime environment We used the following hardware within the ITSO runtime environment for the WebSphere Commerce Analyzer and WebSphere Commerce integration: WebSphere Commerce node – IBM ^ xSeries 230 (8658-61Y) • 1 CPU, Intel PIII 1 GHz • 1152 MB main memory • 18 GB DASD • 1 IBM Ethernet adapter • Hostname: wc55be.itso.ral.ibm.com WebSphere Commerce Analyzer node – IBM ^ xSeries 230 (8658-61Y) • 1 CPU, Intel PIII 1 GHz • 1152 MB main memory • 18 GB DASD • 1 IBM Ethernet adapter • Hostname: wca1.itso.ral.ibm.com Software used in the ITSO runtime environment The ITSO runtime environment was implemented using the software levels listed in Table 20-1 and Table 20-2 on page 804. Table 20-1 WebSphere Commerce node Software Version Microsoft Windows 2000 Server 2000 + Service Pack 3 Microsoft Windows Internet Explorer 6 + Service Pack 1 IBM DB2 UDB, Enterprise Server Edition 8.1 + Fix Pack 1 IBM HTTP Server 1.3.26 WebSphere Application Server 5.0 + Fixesa WebSphere Commerce, Business Edition * including WebSphere Commerce Payments * WebSphere Commerce store 5.5 Chapter 20. Commerce analytics 803 a. Fixes: WebSphere Commerce V5.5 requires many WebSphere Application Server V5 fixes to be installed to work properly. Table 20-2 WebSphere Commerce Analyzer node Software Version Microsoft Windows 2000 Server 2000 + Service Pack 3 IBM DB2 UDB, Enterprise Server Edition 8.1 + Fix Pack 1 + Patches IBM DB2 Intelligent Miner for Data 8.1.1 + Fixes IBM WebSphere Commerce Analyzer 5.5 Software installation paths and variables Table 20-3 lists the software installation paths and variables used to implement the WebSphere Commerce Analyzer node and WebSphere Commerce node. Table 20-3 Software installation paths and variables Software ITSO install path Variable DB2 UDB Enterprise Edition c:\ibm\sqllib DB2 Intelligent Miner for Data c:\ibm\im IBM HTTP Server c:\ibm\ihs WebSphere Application Server c:\ibm\was WebSphere Commerce c:\ibm\wc WebSphere Commerce Analyzer c:\ibm\wca 20.2.2 WebSphere Commerce node configuration This section describes the tasks and requirements that need to be completed to fully implement the WebSphere Commerce node in preparation for integration with WebSphere Commerce Analyzer. The WebSphere Commerce node implementation includes the following high-level steps: 804 WebSphere Commerce node base implementation WebSphere Commerce instance database backup Enable listeners Enable instance for WebSphere Commerce Analyzer Verify the data population for the CURCONVERT table Verify catalog structure is a tree WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Verify remote ODBC connectivity WebSphere Commerce node base implementation The ITSO documented integration procedure requires that the WebSphere Commerce node is already installed and configured. We also strongly recommend that a backup be created of the WebSphere Commerce instance database prior to configuring WebSphere Commerce Analyzer with WebSphere Commerce. The following are the key tasks to complete on the WebSphere Commerce node: WebSphere Commerce and supporting software installed and configured WebSphere Commerce and WebSphere Commerce Payments instances have been created WebSphere Commerce store has been published successfully WebSphere Commerce store has been verified through the completion of an order Note: For detailed information on how to install and configure WebSphere Commerce, refer to the following: On Windows: – Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000 – Chapter 16, “Windows: Migrate a single-tier to a multi-tier” on page 553 On AIX and Solaris: – Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems – Chapter 17, “Solaris: Three-tier environment using Oracle9i and Sun ONE Web Server” on page 599 – Chapter 18, “AIX: Three-tier using DB2 and IBM HTTP Server” on page 675 WebSphere Commerce instance database backup We strongly recommend that you create a backup of the WebSphere Commerce instance database prior to the WebSphere Commerce Analyzer database configuration. Later in the configuration of WebSphere Commerce Analyzer, 92 table spaces will be added to the WebSphere Commerce instance database to capture transactional data. This capture data is then replicated to the datamart and mined. Refer to “DB2 backup and restore” on page 988 for details on how to back up a DB2 database. Chapter 20. Commerce analytics 805 Enable listeners After the WebSphere Commerce instance database has been backed up, we need to enable the following listeners to capture transaction data via the WebSphere Commerce Configuration Manager: UserTrafficEventListener (enabled by default) CampaignRecommendationListener (enabled by default) CampaignRecommendationStatisticsListener (enabled by default) Note: Refer to the Additional Software Guide, IBM WebSphere Commerce V5.5 product guide for more information. To enable the listeners to capture data, do the following on the WebSphere Commerce node: 1. Stop the WebSphere Commerce application server. 2. Ensure the WebSphere Commerce instance database backup has been completed. 3. Start the WebSphere Commerce Configuration Manager. 4. Log on as webadmin and the password you defined. 5. Select and expand -> Commerce -> Instance List -> -> Components. 6. For each of the following listeners, complete the steps below: – UserTrafficEventListener – CampaignRecommendationListener – CampaignRecommendationStatisticsListener a. From the General tab, check the Enable Component check box (default) b. From the Advanced tab, check Start. c. Click Apply. 7. Do not close the Configuration Manager, since it is needed in the next step. Enable instance for WebSphere Commerce Analyzer To enable the WebSphere Commerce instance for use with WebSphere Commerce Analyzer, do the following: Note: Refer to the Additional Software Guide, IBM WebSphere Commerce V5.5 product guide for more information. 1. From the Configuration Manager, select and expand -> Commerce -> Instance List -> -> Commerce Accelerator. 806 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 2. Enable WebSphere Commerce Analyzer from the Commerce Accelerator page as seen in Figure 20-9 on page 808, then click Apply to save changes: – Statistics Source: wc55be.itso.ral.ibm.com This is the host name for the WebSphere Commerce node. – Is WebSphere Commerce Analyzer Installed? Select Yes – Reports document root: c:/ibm/wc/instances/wc1/WCA/reports We accepted the default. – Is IBM DB2 Intelligent Miner for Data Installed? Select Yes This option will only become visible after you select Yes in answer to “Is WebSphere Commerce Analyzer installed?” – WCA DataSource: WCA DataSource We accepted the default. Note: Towards the end of the configuration, we will create the WCA DataSource within the WebSphere Application Server for the WebSphere Commerce Analyzer datamart database (wcamart) in “Configure data source to datamart” on page 862. The data source is found within the WebSphere Commerce Configuration manager, .xml files, and the WebSphere Application Server. By default, the data source name is WCA DataSource. The WCA DataSource value is hard coded into the .xml files. If you want to change the data source name, modify the data source name within the WebSphere Commerce Configuration Manager. The data source name will be resolved between the Configuration Manager setting and the data source name WCA DataSource within the .xml files. For this reason, only update the data source name within Configuration Manager or, better yet, accept the default data source name, WCA DataSource. Whatever data source name you decided to use within the Configuration Manager, the name must be the same within the WebSphere Application Server. Chapter 20. Commerce analytics 807 Figure 20-9 Enable WebSphere Commerce Analyzer within Configuration Manager 3. Close the Configuration Manager. 4. Restart the WebSphere Commerce instance application server for changes to take effect. Verify the data population for the CURCONVERT table WebSphere Commerce Analyzer uses currency conversion to compare the sales value of orders within or between stores. The CURCONVERT table within the WebSphere Commerce instance database contains information used by WebSphere Commerce Analyzer to perform the currency conversion. Use the DB2 Control Center to verify that the CURCONVERT table has been populated with the correct currency conversion before you install WebSphere Commerce Analyzer. Refer to the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 for more information. 808 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Verify catalog structure is a tree Verify that at least one catalog within the WebSphere Commerce instance database is structured as a tree. By default, the master catalog uses a tree structure. Note: WebSphere Commerce Analyzer cannot effectively generate reports with an item that belongs to two or more categories. Refer to the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 for more information. Verify remote ODBC connectivity Later in the WebSphere Commerce Analyzer configuration, database sources will be created within WebSphere and Windows, which needs Open Database Connectivity (ODBC). This configuration will be done for you, but it is important to understand that ODBC will be needed. 20.2.3 WebSphere Commerce Analyzer node installation During the configuration procedure, WebSphere Commerce Analyzer requires that specific users, groups, and privileges for those users have been created and assigned. This section describes what we did to install WebSphere Commerce Analyzer on the WebSphere Commerce Analyzer node. The WebSphere Commerce Analyzer installation includes the following high-level steps: Windows 2000 Server Create users and groups WebSphere Commerce Analyzer installation DB2 UDB V8.1 patches (readme.txt) Update SQL scripts for usrtraffic_r replication Windows 2000 Server WebSphere Commerce Analyzer V5.5 requires that Windows 2000 Server and Service Pack 3 be installed. We also downloaded and installed the latest available Windows 2000 fixes at the time of writing to address security issues with Windows 2000. Create users and groups Before installing or configuring WebSphere Commerce Analyzer, it is important to create the users and groups listed in Table 20-4 on page 810 on the Chapter 20. Commerce analytics 809 WebSphere Commerce Analyzer node. These users and groups are needed during the configuration of WebSphere Commerce Analyzer. Table 20-4 WebSphere Commerce Analyzer users and groups Member of Group User Role martuser WebSphere Commerce Analyzer user to run configuration WCA WCAADMIN Administrators ctrluser WebSphere Commerce Analyzer control database owners WCA Administrators Important: If you do not create the users and groups listed in Table 20-4, you will get an error when attempting to replicate the data from the WebSphere Commerce node to the WebSphere Commerce Analyzer node in a later section in the procedure. The WebSphere Commerce Analyzer provided scripts are dependent on martuser. We found that we had to manually assign privileges to the groups/users for the WebSphere Commerce Analyzer Configuration Manager to work properly when using the Fast Load option (recommended). To create the groups and users required by WebSphere Commerce Analyzer, do the following: 1. Create groups WCA and WCAADMIN. a. On the WebSphere Commerce Analyzer node, select Start -> Settings -> Control Panel -> Administrative Tools -> Computer Management. b. Click Local Users and Groups, and then the Groups folder. c. Right-click the window and select New Group. d. Create two groups named WCA and WCAADMIN. 2. Create users martuser and ctrluser. a. From the Computer Management window, click the Users folder. Note: During the configuration procedure, you will be prompted with the option to specify you want to use the Fast Load option for configuring WebSphere Commerce Analyzer. If you want to use the Fast Load option, which we strongly recommend, the martuser and ctrluser are required for the Fast Load option scripts. 810 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide b. Right-click and select New User. c. Create two users named martuser and ctrluser. d. Set the password for user martuser to password martuser, and user ctrluser password to ctrluser. Note: Setting the passwords as specified is a hardcoded requirement of the WebSphere Commerce Analyzer Fast Load scripts. Refer to the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 for more information. 3. Assign users to groups. a. Assign martuser and ctrluser to the groups WCA and Administrators. b. Assign the user martuser to the group WCAADMIN. 4. Set the user right assignments for the martuser and ctrluser: a. Click Start -> Settings -> Control Panel -> Administrative Tools -> Local Security Policy -> Local Policies -> User Rights Assignment. b. Ensure the martuser and ctrluser have user right assignments for the following Windows Local Security Policies needed for DB2: • • • • • Act as part of the operating Create a token object Increase quotas Log on as a service Replace a process level token WebSphere Commerce Analyzer installation This section provides the high-level steps we performed to install WebSphere Commerce Analyzer and supporting software on the WebSphere Commerce Analyzer node. The WebSphere Commerce Analyzer installation will install the following software components: IBM WebSphere Commerce Analyzer V5.5 IBM DB2 Universal Database V8.1, Enterprise Server Edition IBM DB2 Intelligent Miner for Data V8.1.1 Note: For detailed instructions on installing WebSphere Commerce Analyzer, refer to the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide. To install WebSphere Commerce Analyzer, we did the following: Chapter 20. Commerce analytics 811 1. Ensure the WebSphere Commerce node has been installed and configured, and that a backup has been created for the WebSphere Commerce instance database. Refer to “WebSphere Commerce node base implementation” on page 805. 2. Ensure the users and groups have been created for WebSphere Commerce Analyzer. Refer to “Create users and groups” on page 809. 3. Run setup from the WebSphere Commerce Analyzer CD. We accepted the default options unless specified below. Note: The WebSphere Commerce Analyzer InstallShield incorrectly reports an error during the install. The Readme.txt documents this DB2 silent install error for DBCS systems, but in our case, we experienced this problem on several occasions on SBCS systems. – When prompted, verify the installation of prerequisite products. In our example, we have not pre-installed IBM DB2 UDB V8.1, Enterprise Server Edition or IBM DB2 Intelligent Miner for Data V8.1. Check the IBM DB2 Intelligent Miner for Data V8.1 check box and then click Next. Note: After checking the IBM DB2 Intelligent Miner for Data V8.1 check box, you will see the following message: If you choose to silently install Intelligent Miner, your system may reboot unexpectedly because it requires a new version of the Windows installer. When this reboot completes, simply start the WCA installer again and proceed with the silent install. – You will be prompted for the location of the install media for IBM DB2 Universal Database V8.1, Enterprise Server Edition. – When prompted to enter the IBM DB2 UDB V8.1, Enterprise Server Edition destination directory, we entered c:\ibm\sqllib. – When prompted for the DB2 instance owner, we accepted the default db2admin. – When prompted to enter the IBM DB2 Intelligent Miner for Data V8.1 destination directory, we entered c:\ibm\im. – When prompted to enter the WebSphere Commerce Analyzer destination directory, we entered c:\ibm\wca. – When prompted to enter the Data Directory, we entered c:\ibm\wca. 812 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: When the WebSphere Commerce Analyzer InstallShield installs IBM DB2 UDB, the Warehouse component is installed. 4. During the installation you should receive messages that DB2 UDB, DB2 Intelligent Miner for Data, and WebSphere Commerce Analyzer silent install were successful. Follow the instructions and insert the CDs. 5. After the installation is complete, review the Readme file and restart your system. DB2 UDB V8.1 patches (readme.txt) After installing WebSphere Commerce Analyzer and before configuration, the following DB2 UDB V8.1 patches must be installed, as described in the WebSphere Commerce Analyzer Readme file: iwh2serv.exe db2_vw.jar db2XTrigger.jar Note: For more detailed information, refer to the Readme.txt found on the WebSphere Commerce Analyzer V5.5 CD. The iwh2serv.exe and db2XTrigger.jar files will only be found on a DB2 system in which the DB2 Warehouse component is installed. This is the default for DB2 installed by WebSphere Commerce Analyzer, but not so for WebSphere Commerce. To install the DB2 patches, do the following: 1. Stop all DB2 Windows services. 2. Back up the following original files: – \bin\iwh2serv.exe – \tools\db2_vw.jar – \tools\db2XTrigger.jar 3. Copy the DB2 patches found on the WebSphere Commerce Analyzer CD in the \db2patches directory to the following locations on the WebSphere Commerce Analyzer node: – \bin\iwh2serv.exe – \tools\db2_vw.jar – \tools\db2XTrigger.jar Note: Refer to the Readme file about additional fixes for iSeries. Chapter 20. Commerce analytics 813 4. Update the Windows system classpath to include db2vwcom.jar, which is already installed by default. a. Select Start -> Settings -> Control Panel -> System -> Advanced -> Environment Variables. b. Under System variables, select the classpath variable, and click Edit. c. Append the following to the end of the CLASSPATH variable value field: c:\ibm\sqllib\tools\db2vwcom.jar; Where c:\ibm\sqllib is the directory where we installed DB2. d. Click OK, OK, and OK again. 5. Restart all DB2 Windows services. Note: Refer to the Readme.txt for additional steps needed for the iSeries platform. Update SQL scripts for usrtraffic_r replication At the time of writing the redbook, we discovered that the BRAGENT column in the usrtraffic_r table was not created or referenced correctly from within several SQL scripts (incorrectly spelled BRAGNT - no E). This problem was discovered during replication (see the error message in Figure 20-10 on page 817). To work around this issue, do the following to update the BRAGENT column name in several SQL scripts before they are run during the configuration: 1. The following SQL scripts found in the \bin\db2\55be_ext directory need to be updated: – – – – create_wca_apply_tables.sql ins_fact_visits.sql pop_browser.sq upd_as400.sql (iSeries only) 2. Back up the files listed prior to making changes. 3. Modify the create_wca_apply_tables.sql to change the BRAGNT column name to BRAGENT (include E), as seen in Example 20-1. a. Search for BRAGNT found under CREATE TABLE IWH.USRTRAFFIC_R. b. Change the column name BRAGNT to BRAGENT (with E) as seen in Example 20-1. Example 20-1 Sample updated create_wca_apply_tables.sql CREATE TABLE IWH.USRTRAFFIC_R ( USRTRAFFIC_ID BIGINT NOT NULL, USERS_ID BIGINT, 814 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide PREVURL STMP SERVNAME BRAGENT RESULT REDIR REMADDR REFURL PATHINFO QUERYSTRING SESSIONID LOAD_STATUS IBMSNAP_INTENTSEQ IBMSNAP_OPERATION IBMSNAP_COMMITSEQ IBMSNAP_LOGMARKER LONG VARCHAR, TIMESTAMP, VARCHAR(64), VARCHAR(254), CHAR(1), VARCHAR(254), VARCHAR(254), LONG VARCHAR, VARCHAR(254), LONG VARCHAR, CHAR(64), INTEGER DEFAULT -1, CHAR(10) FOR BIT DATA NOT NULL, CHAR(1) NOT NULL, CHAR(10) FOR BIT DATA NOT NULL, TIMESTAMP NOT NULL ); 4. Modify ins_fact_visits.sql to change the BRAGNT column name to BRAGENT (include E), as seen in Example 20-2. a. Search for BRAGNT found in the where clause of the insert. b. Change the column name BRAGNT to BRAGENT (with E) as seen in Example 20-2. Example 20-2 Sample updated ins_fact_visits.sql WHERE WCA.BROWSER.BROWSER = IWH.USRTRAFFIC_R.BRAGENT AND IWH.USRTRAFFIC_R.USERS_ID = IWH.USERS_R.USERS_ID AND WCA.PERIOD.CALENDAR_DATE = date( IWH.USRTRAFFIC_R.STMP) and 5. Modify pop_browser.sql to change the BRAGNT column name to BRAGENT (include E), as seen in Example 20-3. Important: You will need to be careful about what is updated. Some internal column names still need to be called BRAGNT (no E). a. Search for IWH.USRTRAFFIC_R.BRAGNT. b. Only change IWH.USRTRAFFIC_R.BRAGNT to IWH.USRTRAFFIC_R.BRAGENT (with E) as seen in Example 20-3. Do not change other occurences of BRAGNT in this case (internally used). Example 20-3 Sample updated pop_browser.sql Chapter 20. Commerce analytics 815 insert into WCAETL.BROWSER1_INFO ( SELECT DISTINCT IWH.USRTRAFFIC_R.BRAGENT AS BRAGNT FROM IWH.USRTRAFFIC_R WHERE iwh.process_row('L', ibmsnap_operation,load_status,ibmsnap_logmarker )=1 and IWH.USRTRAFFIC_R.BRAGENT is not null); Note: We believe that the upd_as400.sql file will also need to be updated for iSeries. Note: If you do not perform the updates listed to the SQL scripts, you will experience an error during the replication of data from the WebSphere Commerce node to the WebSphere Commerce Analyzer node in a later step. We will see an error message as Figure 20-10 on page 817. In a nutshell, the SQL scripts contain a typo in the column name BRAGNT (incorrect) instead of BRAGENT (correct - E). The update to the SQL scripts must be performed before the promote steps are run. 816 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 20-10 SQL error for BRAGENT column in the IWH.USRTRAFFIC table 20.2.4 WebSphere Commerce Analyzer pre-configuration Prior to configuring WebSphere Commerce Analyzer, we completed the following tasks for the ITSO integration scenario: Configure DB2 code page Deciding what type of storage to use Using Fast Load or Custom Load Replication options Chapter 20. Commerce analytics 817 Note: For more information on the pre-configuration of WebSphere Commerce Analyzer, refer to the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide in the “Before you configure WCA” chapter. Configure DB2 code page The Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide describes the situations when you will need to set the DB2 instance variable to the UTF-8 code page. In our scenario, we did set the UTF-8 code page (not required). The WebSphere Commerce instance database also uses UTF-8. To verify the setting for the DB2CODEPAGE to the UTF-8 code page 1208 on the WebSphere Commerce Analyzer node, do the following: 1. Open a DB2 command window on the WebSphere Commerce Analyzer node. 2. Verify that the variable is an instance variable by typing the following in the DB2 command window and then pressing Enter: db2set -all 3. If the output does not have the following line, do the following: [i] DB2CODEPAGE=1208 a. Type the following to set the DB2CODEPAGE to 1208 and then press Enter: db2set DB2CODEPAGE=1208 b. Verify that the variable is an instance variable by typing the following in the DB2 command window and then pressing Enter: db2set -all 4. In order for the settings to take effect, disconnect all applications to all databases within the DB2 instance and restart the DB2 instance. db2 force applications all db2 terminate db2stop db2start Deciding what type of storage to use Refer to the “Before you configure WCA” chapter in the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide for details. There are two types of data storage within DB2: 818 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Database Managed Storage (DMS): Table space managed by the administrator (default). System Managed Storage (SMS): Operating system manages table space limited by hard disk size. In our example, we accepted the default database managed storage. The database storage type will be a configuration option in a later step. Using Fast Load or Custom Load Refer to the “Before you configure WCA” chapter in the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide for details. There are two options available for the extraction scripts: Fast Load: This extraction script is executed quickly, because predefined extraction scripts are used. This option is recommended. Custom Load: You can specify your own database names, user IDs, and other values for the extraction script, but this script takes significantly longer. In our example, we used the Fast Load option. There are several manual steps that accompany the Fast Load option found in the “Configuration task details” appendix of the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide. Replication options Refer to the “Before you configure WCA” chapter in the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide for details. There are two replication options: Continuous replication: When replication completes, a new replication starts. Non-continuous replication: Replication starts only when scheduled or started manually. In our example, we selected continuous replication. The replication method will be set during the configuration (promoting the Warehouse steps to production). 20.2.5 WebSphere Commerce Analyzer database configuration The majority of the WebSphere Commerce Analyzer configuration takes place in the WebSphere Commerce Analyzer Configuration Manager. This section outlines the configuration process used for this working example. Several of the major steps describe the importance and behind the scenes functionality for the specific WebSphere Commerce Analyzer features. Configuring WebSphere Commerce Analyzer can be broken down into two main Chapter 20. Commerce analytics 819 tasks: configure WebSphere Commerce Analyzer databases and configure options. The focus of this section is on WebSphere Commerce Analyzer database configuration. The configuration tasks to configure databases used by WebSphere Commerce Analyzer are as follows: Log on as martuser Start the Configuration Manager Tail the _log.html Configure WebSphere Commerce database access Create WebSphere Commerce Analyzer datamart Configure replication Configure and schedule data mining Configure DB2 Warehouse Center Control database Log on as martuser Prior to configuring WebSphere Commerce Analyzer, you must log on to Windows WebSphere Commerce Analyzer node as user martuser created in “Create users and groups” on page 809. Start the Configuration Manager To start the WebSphere Commerce Analyzer Configuration Manager, click Start -> Programs -> IBM WCA -> Configuration. Tail the _log.html Throughout the database configuration, messages will be logged to the WebSphere Commerce Analyzer data directory created during the installation. In our example, this is the c:\ibm\wca\log directory. We downloaded GNU tools that included the tail utility for Windows. 1. Open a command window and change the data directory, for example: cd c:\ibm\wca\log 2. Tail the log file as follows to monitor the status throughout the configuration: tail -f log.html Note: You will need to wait until you have clicked Configure Databases from within the Configuration Manager before the log file will get created. Configure WebSphere Commerce database access To configure WebSphere Commerce Analyzer to access the WebSphere Commerce instance database using WebSphere Commerce Analyzer Configuration Manager, do the following: 820 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: To gain a better understanding of what is going on behind the scenes to configure the WebSphere Commerce database access refer to “What is happening behind the scenes” on page 825. 1. Close all running programs. 2. From Configuration Manager, click Configure Databases. 3. When the Configure WebSphere Commerce Database Access window appears, we entered the following as seen in Figure 20-11 on page 822: – Database Name: wc1 In our example, wc1 is the WebSphere Commerce instance database name on the WebSphere Commerce node (location of DB2 Server). – User Name: admin In our example, admin is the DB2 user and instance owner on the WebSphere Commerce node. – Password: – Database Type: Select DB2 – Data Source: (greyed out) – Platform: Select Windows Note: Some of the fields in Figure 20-11 do not become populated until after you click Connect in the next step. Chapter 20. Commerce analytics 821 Figure 20-11 Configure WebSphere Commerce database access 4. Click Connect. 5. When the Create a connection to the database window appears, we entered the following and then clicked OK (see Figure 20-12 on page 823): The first time you attempt to establish a connection between the WebSphere Commerce Analyzer node (DB2 client) to the WebSphere Commerce node (DB2 server), the Configuration Manager will provide a data entry window to create the connection. Note: The information provided is used behind the scenes to perform a db2 catalog tcpip node. – Hostname: wc55be This is the host name of the WebSphere Commerce node (DB2 server). – Port Number: 50000 822 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide This is the DB2 connection port in the services file on the WebSphere Commerce node (DB2 server). Figure 20-12 TCP/IP connection to WebSphere Commerce node (DB2 server) 6. You should see the following message. Click OK. Your connection to the WebSphere Commerce Server database has been successfully created. Select a schema, then press the Next button to proceed to the next step. Note: The Configuration Manager connect has just performed a db2 catalog tcpip node in the background. In addition, the remote WebSphere Commerce instance database has been cataloged. You can verify your configuration by opening a DB2 command window and entering the following command: db2 list db directory You should see the remote WebSphere Commerce instance database listed. 7. Once a connection is made to the WebSphere Commerce instance database, the schema field will be filled in with the same values as the User Name, as seen in Figure 20-13 on page 824. Click Next. Chapter 20. Commerce analytics 823 Figure 20-13 Configure WebSphere Commerce database access 8. Click View Log. During the WebSphere Commerce Analyzer configuration, each window will provide the user the option to view the log file by clicking View Log. This can be useful when trying to work through errors. The log file is located in the \log\.html. For example, the user may accidentally type an incorrect password and not be aware of the specific error until viewing the log. The following statement is extracted from the log file after the an attempt at establishing a connection that has failed due to a misentered password: SQL1092N “MARTUSER” does not have the authority to perform the requested command. If this error occurs, refer to “Create users and groups” on page 809 and verify the user martuser has been properly created. In addition to locating errors, the log file is also an excellent way to verify that the configuration step has successfully completed. In the case of making a 824 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide WebSphere Commerce database connection, a successful connection should result in something similar to Figure 20-14. Notice the WebSphere Commerce server path includes the WebSphere Commerce node host name wc55be. Figure 20-14 View log result for WebSphere Commerce database access configuration What is happening behind the scenes In each one of the configuration steps, it is important to understand what is happening behind the scenes. When connecting to the WebSphere Commerce instance database, the makeconn.bat script is run in the background. In our example, all of the WebSphere Commerce Analyzer configuration batch files are located in the c:\ibm\wca\bin\db2 directory. When viewing the makeconn.bat file, it will become apparent what is taking place when connecting to the database. In our example, the script is making a DB2 connection to a remote WebSphere Commerce node by performing the following tasks: After accepting the parameters (that is, database name, database user, etc.), the system ODBC data source, the WebSphere Commerce database, and the WebSphere Commerce node are uncataloged. The uncatalog step occurs in the event that the node is already cataloged. Basically, running uncatalog will clear any previous data and start with a clean platform. Recall the example where the log file displayed a user rights error pertaining to martuser. This is an example of an error picked up during the uncatalog process. The system ODBC data source and the database are cataloged. This step makes the remote database appear local. Chapter 20. Commerce analytics 825 There is an attempt to establish a connection to the WebSphere Commerce instance database on the remote WebSphere Commerce node using the DB2 user and password. Create WebSphere Commerce Analyzer datamart This step creates the DB2 datamart on the WebSphere Commerce Analyzer node. The datamart database (wcamart) is used to store the WebSphere Commerce Analyzer is replicated customer data into structured tables as part of the extraction process. Once the data is organized in the datamart, the DB2 Intelligent Miner for Data is used to mine the data in the datamart, analyze the data, and make it available for generating business reports. Note: To gain a better understanding of what is going on behind the scenes to create the WebSphere Commerce Analyzer database refer to “What is happening behind the scenes” on page 828. To create the WebSphere Commerce Analyzer datamart database on the WebSphere Commerce Analyzer node, do the following: 1. From the Create WebSphere Commerce Analyzer Datamart window, we entered the following, as seen in Figure 20-15 on page 827: – Datamart Name: wcamart (default) – Datamart User: martuser The datamart user name must be martuser if you plan on using the Fast Load option. – Datamart Password: martuser The datamart user password must be martuser if you plan on using the Fast Load option. – Datamart Location: Select C – Table Space Type: Select DMS (default) For information on determining the table space type, refer to “Deciding what type of storage to use” on page 818. 826 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: In our example, the user logged into the Windows on the WebSphere Commerce Analyzer node is martuser. This is a requirement for using the Fast Load option. It is important that before attempting to configure the datamart, that you are logged into Windows as martuser and the proper administrative privileges have been assigned. For information on creating the martuser refer to “Create users and groups” on page 809. Figure 20-15 Create WebSphere Commerce Analyzer datamart database 2. Click Customize if you chose the DMS table space type as we have in our example. 3. When the Modify Initial DMS Values window appears, we accepted the following default values: – Schema Name: Select WCA (default) Chapter 20. Commerce analytics 827 – Table space Location: c:\wca_data (create directory manually) Note: The Table space Location directory must exist. If the directory does not exist, create it manually and then click Apply. 4. You should get a message stating “The script to create table spaces has been successfully updated”. Click OK. 5. When you return to the Create WebSphere Commerce Analyzer Datamart window, click Configure to create the WebSphere Commerce Analyzer datamart database (wcamart). 6. You should get a message stating “The WebSphere Commerce Analyzer Datamart was successfully prepared. Press Next to proceed to the next step”. Click OK, and then click Next to continue to the next step. What is happening behind the scenes The first part of the datamart configuration creates the datamart database wcamart by running the makemart.bat. In order to make the DB2 datamart database, the sequence of events that take place is somewhat similar to those when making a connection to the WebSphere Commerce instance database. The sequence of events is as follows: 1. If there is an existing datamart database, it is uncataloged, and dropped to clean the system before performing the remaining functions. The same is true for the system ODBC data source. 2. A new database is created by calling on the batch file dbConfig.bat. 3. A connection is made to the new database and log files are created. 4. Database administrative authority is granted to the WCAADMIN group. WCAADMIN is one of the Windows groups created in “Create users and groups” on page 809. 5. After the datamart has been successfully created, the loadmart.bat file is run, which loads the DB2 datamart database that was just created. The loadmart.bat file is rather lengthy, and therefore the specifics to each step will be omitted. However, if errors occur when creating the datamart, it is recommended that you view this batch file. Configure replication When customers begin using the store and purchasing products, the transactions will generate a large amount of data. This data is immediately stored in the WebSphere Commerce instance database. The WebSphere Commerce Analyzer then replicates this data and stores it among temporary tables on the WebSphere Commerce Analyzer node in the datamart database (wcamart). 828 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: To gain a better understanding of what is going on behind the scenes to configure replication, refer to “What is happening behind the scenes” on page 830. To configure replication of data from the WebSphere Commerce instance database on the WebSphere Commerce node to the datamart database on the WebSphere Commerce Analyzer node, do the following: 1. From the Replication Setup for Source Database window, we entered the following as seen in Figure 20-16 on page 830: – – – – – Datamart Name: wcamart (greyed out, based on previous setting) Check Commerce Replication Commerce Database Name: wc1 (greyed out, based on previous settings) Table Space Size: Select Normal (default) Table Space Path: c:\wcstspath\ (must create directory manually on the WebSphere Commerce node and entered with trailing \) Important: Manually create the Table Space Path entered on the WebSphere Commerce node c:\wcstspath. Be aware that when you click Apply, the Configuration Manager will add 92 table spaces to the WebSphere Commerce instance database. The DB2 table spaces will be stored in the c:\wcstspath directory specified. This is one of the reasons that we recommend that you back up your WebSphere Commerce instance database prior to the WebSphere Commerce Analyzer configuration. Adding the table space for WebSphere Commerce Analyzer in the c:\wcstspath directory on the WebSphere Commerce node consumes approximately 400 MB of storage. Chapter 20. Commerce analytics 829 Figure 20-16 Replication Setup for Source Database 2. When complete, you should see the message “The replication setup has been successfully completed”. Click OK. Note: For more information on table space size, refer to the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide. What is happening behind the scenes In order to better understand the replication configuration, it may be beneficial to look through the script that runs during this process. The batch file replication.bat completes the following steps: 1. Using the provided login information, there is an attempt to connect to the WebSphere Commerce instance database (wc1). Once connected, the file checks certain database parameters. An example of a parameter in this instance would be a verification that the schema name is in all capital letters. 830 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 2. After creating several .sql files, the configuration checks for the existence of tables denoted by the schema ASN. It then drops all tables (with the schema REPL) from the wc1 database. 3. New tables and table spaces used for replication are then created. 4. The Configuration Manager checks whether any replication tables already exist. If they do, the prune control and register entries that reference WebSphere Commerce Analyzer are deleted. A portion of this batch file code is shown in Example 20-4. This code depicts how the prune control entries would be dropped if the replication tables exist. Example 20-4 Sample of replication.bat :: drop the pruncntl entries @set cno=13 @echo BAT_REPL_DEL_PRUNCTL >>%PRGRSLOG% @set cmd=db2 -tvf delprune_cd.sql @%JLOG% cmd [--%cno%--] %cmd% >>%LOG% @ %cmd% >>%LOG% 2>&1 @if errorlevel 5 goto log_error @set cno=14 @set cmd=cd %WORK_DIR% @%JLOG% cmd [--%cno%--] %cmd% @ %cmd% >>%LOG% 2>&1 @if errorlevel 1 goto log_error >>%LOG% 5. After completing the configure replication step, check the table space path on the WebSphere Commerce node in the instance database to make certain it is populated with table spaces. Click View Log to verify replication configuration was successful. Note: At any point during configuration, it is possible to use a command prompt window in an attempt to manually run a step. Most of the steps include a command line in the log file. In the following example, the command is running the replication batch file: cmd /c db2cmd -c -i -w C:\IBM\WCA\bin\db2\replication.bat The parameters entered in the configuration interface are then passed through. 6. Click Next to advance to the next configuration step. Chapter 20. Commerce analytics 831 Configure and schedule data mining In this step, the user is able to configure data mining and data scheduling capabilities using DB2 Intelligent Miner for Data, which is installed on the WebSphere Commerce Analyzer node. Data mining takes place after the data is extracted from the WebSphere Commerce instance database and replicated to the WebSphere Commerce Analyzer datamart. Data mining is used to extract useful information and utilize the data in strategic business decisions. Once in the datamart, the data is mined and structured in order to uncover hidden data patterns. Data mining technology is especially beneficial because it can find inconsistencies in the data. These inconsistencies can be the result of a customer error, false information, etc. DB2 Intelligent Miner for Data is capable of ignoring these externalities and focusing on the overall data patterns. Note: To gain a better understanding of what goes on behind the scenes when configuring and scheduling data mining, refer to “What is happening behind the scenes” on page 833. To configure the data mining environment and schedule when the mining will take place, complete the following steps: 1. From the Schedule Mining window, we entered the following as seen in Figure 20-17 on page 833: – Mining Base Name: mine1 – Mining User Name: martuser The mining user name is the name of the datamart user martuser, and logged into the Windows system. The martuser was created in “Create users and groups” on page 809. – Mining Password: martuser In our example, the martuser password is martuser as a requirement for the Fast Load scripts. – Check Activate Mining – Mining Training Interval: 7 (default) – Mining Apply Interval: 1 (default) – Check Activate Closed Loop Tip: The Activate Closed Loop check box is used to configure mining to automatically be included as a step when replication is performed. For example, if Activate Closed Loop is checked and you manually replicate or schedule replication, mining will be performed. 832 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 20-17 Schedule Mining 2. Click Apply for the schedule mining settings to be configured. 3. You should see a message “The data minit parameters have been successfully setup”. Click OK. 4. Click Next in the Schedule Mining window to continue to the next step. What is happening behind the scenes After submitting the information found in Figure 20-17, the script updwcamb.bat will run by clicking Apply. The updwcamb.bat script configures the WebSphere Commerce Analyzer data mining tools by: Updating the mining base Loading data into DB2 Intelligent Miner for Data Chapter 20. Commerce analytics 833 Figure 20-18 Resulting log file after configuring mining base In order to verify if the configuration was successful or to view the manual command that runs updwcamb.bat, click View Log. You should see something like the log file in Figure 20-18. Configure DB2 Warehouse Center Control database Data Warehouses provide a basis for data mining and analytical tools. The Data Warehouse Center Control database manages the data replication and extraction process and stores data that will eventually be used in making business decisions. The Data Warehouse Center Control database differs from other databases because of its ability to focus on business subject areas as opposed to operational data. It is dedicated solely to improving business decisions and not operational application use. Therefore, not all operational data pertains to a Data Warehouse. Note: To gain a better understanding of what is going on behind the scenes when configuring the DB2 Warehouse Center Control database, refer to “What is happening behind the scenes” on page 836. To configure the Warehouse Center Control database, do the following: 1. From the Configure DB2 Warehouse Center Control Database window, we entered the following as seen in Figure 20-19 on page 835: – Warehouse Database Name: wcactrl (default) 834 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – Warehouse Administrator User ID: ctrluser (default) The ctrluser was created in “Create users and groups” on page 809. – Warehouse Administrator Password: ctrluser The ctrluser password must be ctrluser for the Fast Load option. – Warehouse Schema Name: IWH (greyed out) – Warehouse Database Location: C – Datasource Name: wc1 (greyed out) The data source name should be the same as WebSphere Commerce instance name. – Datamart Name: wcamart Figure 20-19 Configure DB2 Warehouse Center Control Database 2. Click Configure Warehouse. 3. When the Confirm Warehouse Load Options window appears, we selected Fast Load and then clicked OK. Chapter 20. Commerce analytics 835 For more information on the selection of Fast Load or Custom Load, refer to “Using Fast Load or Custom Load” on page 819. Note: The Custom Load option allows a user more flexibility in assigning names but can take up to three days to complete. The Fast Load option is relatively quick because it is using the predefined scripts. 4. When the Fast Load is complete, you should see a message, “The WebSphere Commerce Analyzer scripts were successfully configured. Press Next to proceed to the next step”. Click OK and then Next. What is happening behind the scenes After clicking Configure Warehouse and selecting the load type, two batch files are run in the background. The first file to run, makewcdb.bat, creates the DB2 Warehouse Center instance in the following steps: 1. The system ODBC data source is uncataloged. 2. Depending on whether the user chooses to keep an existing database or drop it, the file reacts accordingly. In this case, there is no existing database named wcactrl. Therefore, the control database wcactrl is created. 3. The parameters entered into the interface are used to test a connection to the wcactrl database. 4. The control database is cataloged and the connection is tested once more. 836 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 20-20 Resulting log file after creating Warehouse Center control database Once makewcdb.bat has completed, the loadwcdb.bat runs if you have chosen Custom Load. In choosing Custom Load, the user can specify database names and user IDs that will be used for the extraction scripts. These scripts will load with the control database when loadwcdb.bat runs. In this example, the Fast Load option is chosen and the Warehouse Center is loaded. 20.2.6 Prepare promote steps The next series of steps branch away from the Configuration Manager interface and require the user to prepare the environment before promoting the Chapter 20. Commerce analytics 837 Warehouse. Each of the steps outlined in this section are performed on the WebSphere Commerce Analyzer node, with the exception of starting the capture on the WebSphere Commerce node. This section includes the following tasks: Initialize the Warehouse Center Control database Modify information for the Data Warehouse Center Modify Fast Load settings Configure the DB2 Warehouse External Trigger Server Start data capture on WebSphere Commerce node Figure 20-21 displays each of the preparation steps that you must manually complete and check off when done. Figure 20-21 Prepare Promote Steps Note: Refer to the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 for more detailed information on completing these steps. 838 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Initialize the Warehouse Center Control database To initialize the Warehouse Center Control database on the WebSphere Commerce Analyzer node, do the following: 1. Click Start -> Programs -> IBM DB2 -> Set-up Tools -> Warehouse Control Database Management. 2. When the Data Warehouse Center - Control Database Management window appears, we entered the following, as seen in Figure 20-22, and then clicked OK: – – – – – New control database: wcactrl Schema: IWH User ID: ctrluser Password: ctrluser Verify Password: ctrluser Figure 20-22 Initialize Warehouse Center Control database 3. When complete, you should see the message “Processing completed successfully”. Click Close. 4. Check OK next to Warehouse Initialization on the Prepare Promotes Steps window. Chapter 20. Commerce analytics 839 Modify information for the Data Warehouse Center To modify information for the Data Warehouse Center Control database, do the following: 1. Select Start -> Programs -> IBM DB2 -> Business Intelligence Tools -> Data Warehouse Center. 2. You will be prompted to log on. Enter the following and then click Advanced: – User ID: ctrluser – Password: ctrluser Note: This is the same information entered for“Initialize the Warehouse Center Control database” on page 839. 3. From the Advanced window, enter the following and then click OK: – Control database: wcactrl In this case, this is the Warehouse Center Control database we created (wcactrl) not the default DB2 control database (dwctrldb). – Server host name: localhost (default) – Server service name: vwkernal (default) Note: If you do not change the Warehouse Center Control database to wcactrl, then you will get a DB2 select error due to not having proper privileges when attempting to connect to the dwctrldb control database created during DB2 installation and owned by the user logged in during installation. To resolve this problem, enter the wcactrl database from Advanced. 4. When you return to the Data Warehouse Center Logon, click OK. Modify Warehouse Sources To modify the Data Warehouse Center Sources, do the following: 5. Select and expand Warehouse Sources from the Data Warehouse Center. 6. Right-click WebSphere Commerce and select Properties. 7. Click the Database tab and modify the following values for your WebSphere Commerce instance and then click OK (see Figure 20-23 on page 841): – Database name: wc1 In our example, wc1 is the WebSphere Commerce instance database name. 840 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – System name: (leave this field blank) In our example, wc55be is the host name of the WebSphere Commerce node. This was cataloged in “Configure WebSphere Commerce database access” on page 820. For this reason, this field is left blank. – User ID: admin This is the DB2 user that has schema access for the WebSphere Commerce instance database. In our example, the DB2 instance owner and schema user are the same. – Password: – Verify Password: Figure 20-23 Data Warehouse configure source database Modify Warehouse Targets To modify the Data Warehouse Center targets, do the following: 8. Select and expand Warehouse Targets. 9. Right-click Advanced Target Tables and select Properties. 10.Click the Database tab and modify the following values for your WebSphere Commerce Analyzer datamart database (wcamart) and then click OK (see Figure 20-24 on page 842): – Database name: wcamart Chapter 20. Commerce analytics 841 In our example, wcamart is the WebSphere Commerce Analyzer datamart database name. – System name: (leave blank) In our example, wca1 is the host name of the WebSphere Commerce Analyzer node. The wcamart database is local to the WebSphere Commerce Analyzer node; therefore we left this field blank. – User ID: martuser This is the DB2 user that has schema access for the WebSphere Commerce Analyzer datamart database (wcamart). In our example, the DB2 instance owner and schema user are the same. – Password: – Verify Password: Figure 20-24 Data Warehouse configure target database 11.Check OK next to Password Changes on the Prepare Promotes Steps window. 842 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Modify Fast Load settings To modify the Fast Load settings by changing the schema name for the WebSphere Commerce instance database tables, do the following: 1. From the Data Warehouse Center, select and expand Warehouse Sources -> WebSphere Commerce. 2. Click Tables. 3. A list of tables will be displayed. For each table except the IBMSNAP table, do the following: a. Right-click each table and select Properties. b. In the Table schema field, type the name of the schema of the WebSphere Commerce instance database for each table. Important: During the WebSphere Commerce instance creation via the Configuration Manager, the WebSphere Commerce instance database (for example, wc1) is created as the user logged in at the time of creation. In our example, this is user admin. Each table created as part of the schema creation and population is by default given the schema name of the user logged in (in our example, admin). The default schema (hardcoded) for WebSphere Commerce Analyzer is wcsadmin. For this reason, unless you have logged into Windows as wcsadmin on the WebSphere Commerce node before WebSphere Commerce instance creation, you will have to manually modify the schema name for all the tables listed as we have done for this example (over 100 tables). The quickest times to change the schema name are as follows (average person approximately 10-15 minutes): 7:37 RDK 8:39 NDN 8:42 JMG 10:37 SI c. When complete, view the list of tables to ensure you have modified all tables with the correct schema name. 4. Check OK next to Fast Load Changes on the Prepare Promotes Steps window. Chapter 20. Commerce analytics 843 Configure the DB2 Warehouse External Trigger Server The last step in completing the Warehouse Center control database configuration is to start the DB2 External Trigger Server as follows on the WebSphere Commerce Analyzer node: 1. Add the following to your classpath: a. Click Start -> Settings -> Control Panel -> System -> Advanced tab -> Environment Variables. b. Under System Variables, select Classpath and click Edit. c. Ensure the following classpath entries exist. If not append to the end of the classpath value and then click OK: c:\ibm\sqllib\tools\db2XTrigger.jar;c:\ibm\sqllib\java\common.jar; In our example, we installed DB2 UDB to the c:\ibm\sqllib directory. 2. Type the following command to start the DB2 External Trigger Server. %IWDA_DIR%\jre\bin\java db2_vw_xt.XTServer 11004 Where 11004 is the default port number for the DB2 External Trigger Server. 3. You should see the following message if the server started successfully: Data Warehouse External Trigger Server running. Hostname = wca1 Important: The DB2 Data Warehouse External Trigger Server must be running on the WebSphere Commerce Analyzer node for the replication process to work properly. 4. Check OK next to DB2 Warehouse External Trigger Server on the Prepare Promotes Steps window. Start data capture on WebSphere Commerce node Prior to replication of the WebSphere Commerce instance database data (from WebSphere Commerce node) to the WebSphere Commerce Analyzer datamart database (WebSphere Commerce Analyzer node), you must start the data capture on the WebSphere Commerce node. Note: Detailed information on DB2 replication can be found in the Replication Guide and Reference, IBM DB2 UDB V8.1 product guide found at the following URL under the Administration heading: http://www.ibm.com/cgi-bin/db2www/data/db2/udb/winos2unix/support/v8pubs. d2w/en_main 844 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 1. Before capture: Before starting the data capture, we configure the LOGRETAIN value to Recovery and back up the WebSphere Commerce instance database as follows on the WebSphere Commerce node where the WebSphere Commerce instance database resides (DB2 server on this node): a. Open a DB2 command window, and enter the following to connect to the instance database: db2 connect to Where is the WebSphere Commerce instance database (for example, wc1). b. Check the database configuration by entering the following in the DB2 command window: db2 get db cfg for c. Check that the LOGRETAIN value is set to RECOVERY. If it is not (the default), then set the value as follows: db2 update db cfg for using LOGRETAIN RECOVERY d. After making the database configuration update, disconnect all connections to the WebSphere Commerce instance database. For example, stop the WebSphere Commerce instance application server. e. In order to configure the capture program, you must first create a backup of the WebSphere Commerce instance database. Refer to “DB2 backup and restore” on page 988 for details. f. Start the WebSphere Commerce instance application server. 2. Configure the capture program: The following steps are only required when you configure the capture program on the WebSphere Commerce node: a. Open the DB2 Replication Center by clicking Start -> Programs -> IBM DB2 -> General Administration Tools -> Replication Center. If the Replication Center Launchpad opens, close it. b. Select and expand Replication Definitions from the left-hand side of the window. c. Select and right-click Capture Control Servers and select Add. d. When the Add Capture Control window appears, check the Capture Control Server box next to the WebSphere Commerce instance database alias (for example, wc1) in the database alias column as seen in Figure 20-25 on page 846. Chapter 20. Commerce analytics 845 Figure 20-25 Datasource to add to Capture Control Server e. Enter the user ID and password for the database and click OK. 3. Start the data capture program: To start the data capture program, do the following: a. From the Replication Center, select and expand Operations from the left-hand window. b. Click Capture Control Servers. c. Select and right-click the Database Alias name defined in the previous step (for example, wc1) from the right-hand pane, and click Start Capture. d. When the Start Capture window appears, we entered the following parameters: • CAPTURE_PATH: c:\capture Directory must exist before capture. • 846 STARTMODE: WARMSI (see note box below) WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: Refer to the Hint box for a brief description of each of the following start modes: WARMSI: This will automatically switch to COLD when it starts initially, and to WARM start in subsequent times (DB2 default). WARMNS: You have started the capture before, but do not want to start in cold. WARMSA: If an error occurs and cannot start as WARM, it will start as COLD. COLD: Clear all previous information and start a full refresh of all target tables. For detailed information, refer to the Replication Guide and Reference, IBM DB2 UDB V8.1 product guide. e. When done, click OK. f. When the Run now or Save command window appears, enter the following under Run Specifications and then click OK: • • • • System name: WC55BE User ID: admin Password: Directory: c:\capture Command-line start capture: To start the capture program from the command line on the WebSphere Commerce node, do the following: 1. Create a capture log directory (for example, c:\capture) before running the command. 2. Enter the following command to start the capture: asncap CAPTURE_SERVER= STARTMODE= CAPTURE_PATH= For example: asncap CAPTURE_SERVER=wc1 STARTMODE=cold CAPTURE_PATH=c:\capture More detailed information on the anscap command can be found in the Replication Guide and Reference, IBM DB2 UDB V8.1 product guide. Chapter 20. Commerce analytics 847 Note: To stop the capture (only when you desire), right-click the Database alias and select Stop. Promote Warehouse steps to production mode Recall that the WebSphere Commerce Analyzer configuration is broken down into two major processes: Configure Databases and Configure Options. Both of these phases take place in the Configuration Manager, and promoting the Warehouse steps to production mode is the final step in the Configure Databases process with the exception of testing the replication. Workaround: While developing our working example, we discovered that using the procedure in the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5, we could not test the replication successfully until we promoted the steps. This is due to the stores_r table not existing, which is needed for the test replication. The stores_r table is created by running the create_wca_apply_tables.sql. During an earlier step, the loadmart.bat, which contains a step to call create_wca_apply_tables.sql, is run, but it gets skipped because wcapatch2 is set to 1, which never allows this to be run. To work around this problem, we will promote the steps and then test the replication. To promote the steps, do the following on the WebSphere Commerce Analyzer node: 1. From the WebSphere Commerce Analyzer Configuration Manager, click Next on the Prepare Promote Steps window. 2. When the Promote Steps window appears, we entered the following, as seen in Figure 20-26 on page 849: – Warehouse Database Name: wcactrl – Warehouse Administrator User ID: ctrluser – Warehouse Administrator Password: ctrluser – Warehouse Server Port: 11004 The port of the External Trigger Server is configured in the DB2 Warehouse External Trigger Server. – Host Name: wca1 This is the host name of the WebSphere Commerce Analyzer node. 848 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: Ensure you enter only the host name (not fully qualified). – Extraction File Location: c:\ibm\wca\log This is the directory where the extraction files will be temporarily located. The c:\ibm\wcadata was created during the WebSphere Commerce Analyzer installation. – Uncheck Continuous Replication In our example, we want to schedule when replication is run so we do not check Continuous Replication. Refer to the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 and the Technical Reference, IBM WebSphere Commerce Analyzer V5.5 for more information. Figure 20-26 Promote Steps for WebSphere Commerce Analyzer 3. Click Start Promotion. Chapter 20. Commerce analytics 849 This will call the promotables.bat file runs, which will in turn call the create_wca_apply_tables.sql (create stores_r table needed for test replication). 4. You may see a message, “Review the host name and press ‘Start Promote’ to continue”. Click OK. In our example, the host name field is greyed out (no ability to change if we wanted to). Click Start Promotion again. 5. You should receive a message “Steps have been successfully promoted. See log for details and continue with task ‘Configure Options’”. Click OK. 6. Click Cancel to return to the main Configuration Manager window. Verify creation of stores_r table After the promote steps have completed, the stores_r table should have been created by the create_wca_apply_tables.sql script. Verify that the stores_r table exists in the wcamart database from the Data Warehouse Center or from a DB2 command window. At this stage the stores_r table will not contain any data, but should exist. The stores_r table is used in the test replication in the next step. To verify the stores_r table, do the following: 1. From the Data Warehouse Center, select and expand Subject Areas -> Replication WebSphere Commerce -> Processes. 2. Select store WCS. 3. Check the data in the STORE table by right-clicking the STORE_R table and selecting Sample Contents. There will be no data, but the columns within the table will be visible in the window. If you cannot sample contents within the STORE_R table (without error, no data), the table may not have been created. Test replication In order to continue with the configuration process, it is necessary to test data replication from the WebSphere Commerce instance database (wc1) on the WebSphere Commerce node to the datamart (wcamart) on the WebSphere Commerce Analyzer node. Note: Refer to “Configure replication” on page 828 for more information on what is being tested. Make sure this step has been completed before testing replication. 850 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Much like the other steps in configuring the Warehouse Center Control database, testing the replication of data is performed in the Data Warehouse Center. The basic process is as follows: Observe the data in a sample table. Run a test to replicate the data from the sample table. Verify the data has been replicated into another table. In order to successfully complete the replication test, do the following: 1. From the Data Warehouse Center, select and expand Subject Areas -> Replication WebSphere Commerce -> Processes. 2. Select store WCS. 3. Check the data in the STORE table by right-clicking the STORE table and selecting Sample Contents. Note: In this step, it is necessary to observe the data in the sample table. This is the data that will be replicated into another table after the test is complete. 4. In order to successfully run the test, the mode needs to set to test. Right-click R WCSc Store and click Mode -> Test. 5. Run a test to replicate the data from the STORE table into sample replication table titled STORE_R. Complete this test by right-clicking R WCSc Store and select Test to begin the replication test. 6. Verify the data has been replicated to STORE_R by right-clicking STORE_R and selecting Sample Contents. Note: If you do not see data, try switching the mode from Test to Development and back to Test and try the test again. We noticed that sometimes DB2 did not work properly unless we did this. – If the replication is successful, continue to the next step. – If there is no data in the STORE_R table refer to “Configure replication” on page 828. The configuration step was not successfully completed. On the other hand, if an error occurs during replication, such as the error shown in Figure 20-27 on page 852, it is necessary to verify specific information. Chapter 20. Commerce analytics 851 Figure 20-27 Replication Error DWC07356E Note: More detailed information on troubleshooting can be found in the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide. 7. Change from Test to Production mode by right-clicking R WCSc Store and selecting Mode -> Production. Note: It appears that you cannot change the mode from Production to Development. You must move from Production to Test and then from Test to Development. 8. Remove the sample data by typing the following in a DB2 command window: db2 connect to wcamart db2 delete from IWH.STORE_R The STORE_R table should now contain no data. 20.2.7 WebSphere Commerce Analyzer business options configuration This section describes the high-level procedure to configure the business options within the WebSphere Commerce Analyzer Configuration Manager. We accepted the default settings for the majority of the business options. 852 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: For detailed information on configuring the business options, refer to the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide. The Configure Options section of the product guide is very straightforward and for the most part we accepted the default options. For this reason, we only provided the high-level steps in the redbook. 1. From the WebSphere Commerce Analyzer Configuration Manager, click Configure Options. 2. From the Business Options Configuration Path window, we selected Full customization and then clicked Next. Based on our experience, we believe that most customers will need to use the Full customization setting so that they can modify the mining model settings. The mining model settings are not accessible from the Limited customization and are available from Full customization (and also from the Parameter Manager; click Start -> Programs -> IBM WCA -> Parameter Manager). Important: If you select Limited customization, be aware that you will need a campaign initiative scheduled to avoid data mining errors. In addition, you will need to modify the mining model settings. For example, by default the mining model settings and Product report Units Sold will only display products that have been shipped. 3. From the Connect to Database window, we entered user ID martuser and password martuser for the datamart database (for example, wcamart), and user ID admin for the WebSphere Commerce instance database (for example, wc1). Click Next. 4. From the Select Online Stores and the Language Currency for Reports window, we entered the following and then clicked Apply Choices: – Checked the ToolTech store, which is the sample store we published on the WebSphere Commerce node. – The language by default is set to English. – Currency USD. After clicking Apply Choices, click Next. 5. From the Select Catalog window, we checked catalog ID that corresponded to the ToolTech store (for example, 10001 Store master catalog) and then clicked Apply Choices. Click Next. 6. From the Load References and Financial Periods window, we accepted the default settings and clicked Load. Chapter 20. Commerce analytics 853 Note: At the time of writing this redbook, we were not able to select the year 2003 as the Load Period to start. The most current year listed is for 2002 (see Figure 20-28). This may be an issue for customers that have legacy databases migrated from previous releases. Do not click Load more than once, unless you are selecting a new language. The Load Periods from Year field is used to indicate indexed dates within the database. Figure 20-28 Configure Options: Load References and Financial Periods 7. Click Next to advance to the Select Mining Models window. 8. From the Mining Models window, we unchecked the following model names and then clicked Apply as seen in Figure 20-29 on page 855 (see note below for explanation): – Uncheck WCAINTCHAR01 – Uncheck WCAINTCHAR02 854 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – – – – Uncheck WCAMEMBINT01 Uncheck WCAMEMBINT02 Uncheck WCAMEMBMETA01 Uncheck WCAMEMBMETA02 The following model names are not visible in Figure 20-29, but also need to be unchecked. – – – – – – Uncheck WCAACNTCHAR01 Uncheck WCAACNTCHAR02 Uncheck WCACNTRCHAR01 Uncheck WCACNTRCHAR02 Uncheck WCAACNTWRFQ01 Uncheck WCAACNTWRFQ02 Figure 20-29 Select Mining Models - Configure Business Options Chapter 20. Commerce analytics 855 Important: We believe the logical order is to understand the trend (commerce analytics) and then schedule a campaign initiative to close the loop. At the time of writing, we found that if you did not have a scheduled campaign initiative before the Start Extract step (chains replication and mining), the data mining step will fail because there is no campaign data to mine. To work around this problem, we unchecked the mining model names associated with campaigns listed above. Later we will enable these settings after having created and scheduled a campaign initiative. 9. Click Next to advance to the Configure Order Status Mappings. 10.On the Configure Order Status Mappings window, we accepted the default settings, which maps the WebSphere Commerce order status codes to numerical values within the WebSphere Commerce Analyzer datamart. The only thing that can be changed is the description of the mappings. Click Apply and then click Next. 11.From the Select Order Status Attributes window, we did the following as seen in Figure 20-30 on page 858 (see tip note box for explanation): – Check the check box in the cell for Payment Authorized in the Billed column. – Click Apply. 856 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Tip: When developing and testing a WebSphere Commerce store, it is common for a developer to complete an order through payment. This changes the order status to the value C. The default Business Intelligence reports ignore order status C. For the purposes of development and testing to validate the WebSphere Commerce Analyzer environment, you could do one of the following to see data within the reports: Modify the Order Status Attribute mapping This requires modifying the default attribute mappings so that orders in order status C (payment authorized) are displayed as completed orders in the Business Intelligence reports. We chose this option for simplicity in validating the integration of WebSphere Commerce Analyzer and WebSphere Commerce. This method offers the cleanest solution to validate the environment. Modify the SQL within the standard Business Intelligence reports This requires customization of the Business Intelligence reports, which is covered in 20.3, “Create customized reports” on page 868. Change the order status to match the SQL in the report. This requires additional transaction processing to change the order status. For example, the order status would need to change to Shipped, which typically requires back-end integration. Manually update the order status within the database. This method should only be used in development and can be error prone. Chapter 20. Commerce analytics 857 Figure 20-30 Select Order Status Attributes 12.Click Next to advance to the Select Orders to be Totaled for RFM window. 13.From the Select Orders to be Totaled for RFM window, we accepted the default values by clicking Apply and then Next. 14.From the Define Associates between Orders and Coupons/Initiatives/Metaphors window, we accepted the default values by clicking Apply and then Next. 15.From the Select Member Attributes window, we accepted the default values by clicking Apply and then Next. 16.From the Select Abandoned Order Properties window, we accepted the default values by clicking Apply and then Next. 17.From the Select Properties for Request for Quotation (RFQ) window, we accepted the default values by clicking Apply and then Next. 18.From the Select Contract Properties window, we accepted the default values by clicking Apply and then Next. 858 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 19.From the Maintain WCA Parameters window, we accepted the default values by clicking Apply. – If you are done, click Cancel to return to the main WebSphere Commerce Analyzer Configuration Manager window. – If you are not done, click Back to adjust settings. 20.2.8 Post-configuration steps After you have configured WebSphere Commerce Analyzer and the WebSphere Commerce node, you will need to perform the replication and extraction, which includes the following steps: 1. 2. 3. 4. 5. 6. Start data capture on the WebSphere Commerce node Start Trigger Server on WebSphere Commerce Analyzer node Create customer transactions to generate sample data Run replication and extraction Schedule replication and extraction to run Configure data source to datamart Start data capture on the WebSphere Commerce node If not already started, start the data capture on the WebSphere Commerce node. Refer to “Start data capture on WebSphere Commerce node” on page 844. This is done within the DB2 Replication Center. As mentioned, there are several different STARTMODE options for starting the capture (cold, warmsi, warmns, warmsa). You can check the Windows Task Manager processes for the asncap.exe to see if the capture is running. Start Trigger Server on WebSphere Commerce Analyzer node If not already started, start the DB2 Warehouse External Trigger Server on the WebSphere Commerce Analyzer node. For details, refer to “Configure the DB2 Warehouse External Trigger Server” on page 844. Create customer transactions to generate sample data In order to analyze information, we need to generate customer transactional data. This section requires that the WebSphere Commerce and WebSphere Commerce Payments application servers on the WebSphere Commerce node have been started. Register users We registered the following users: – testuser1 Chapter 20. Commerce analytics 859 – testuser2 – testuser3 Complete several transactions for each user We completed several transactions for each registered (shopping flow through payment approval). Run replication and extraction To run the replication and extraction on the WebSphere Commerce Analyzer node, do the following: 1. From the DB2 Data Warehouse Center, click Warehouse -> Work In Progress from the menu bar. 2. From the Work In Progress window, click Work In Progress -> Run New Step from the menu. Note: Click Name to sort the available steps by name. Should be sorted by default. 3. In the Available Steps column of the Run New Step window, select Start Extraction. Click the > to add the item to the Selected Steps column. Tip: Start Extraction includes the step of replication. Do not select the separate Start Replication item. 4. Click OK to begin the replication and extraction. 5. You should see a series of items listed with status successful or in progress. When no more items are listed as a status of In Progress, the replication and extraction is most likely complete. Verify that the Windows Task Manager CPU usage is low. Tip: To monitor the progress of the replication, from the Work in Progress window click the Run ID heading (toggle) to sort in descending order. The result of this tip is that the most current step being executed will be listed first in the list. For B2B stores, there are approximately 210 steps in the sequence. For B2C stores, there are approximately 159 steps in the sequence. The number of steps for both B2B/B2C is only an approximation, but should provide some guidance for monitoring the status of the replication. 860 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: If you selected Activate Closed Loop in the schedule mining configuration, the mining procedure will automatically be a step that is executed by the Start Extraction step. Tip: Replication failure If you experience a replication failure, we recommend that you do the following: Select the failed step. Right-click Show Log. Refer to the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 troubleshooting appendix to identify and resolve the problem. After fixing the problem, rerun the failed step by selecting the step and right-clicking Run Now. When the step is completed successfully, it will chain to the next step in the sequence. Once you have a failure, you will not be able to simply select Start Extraction and Run Now to execute all chained steps again. 6. The first time replication and extraction is performed (Start Extraction), no data is available for the Business Intelligence reports. To generate data for the reports, you will need to run the Start Extraction step a second time. This is only required during the initial configuration. Note: If you do not run the Start Extraction a second time during the initial setup, no data will be displayed in the Business Intelligence reports. Schedule replication and extraction to run To schedule replication and extraction, do the following on the WebSphere Commerce Analyzer node: 1. Ensure the data capture program asncap is running on the WebSphere Commerce node. For details, refer to “Start data capture on WebSphere Commerce node” on page 844. 2. Ensure the DB2 Warehouse External Trigger Server is running on the WebSphere Commerce Analyzer node. For details refer to “Configure the DB2 Warehouse External Trigger Server” on page 844. 3. From the DB2 Data Warehouse Center window, select and expand Subject Areas -> Advanced Start and End -> Processes. 4. Under Processes, select Start Extraction. Chapter 20. Commerce analytics 861 5. On the right side of the window, if Start Extraction is not in the Development mode, move it into Development mode by right-clicking 1. Start Extraction -> Mode -> Development. 6. Right-click 1. Start Extraction and select Schedule. 7. When the Schedule – 1. Start Extraction window appears, complete the fields necessary to schedule the processes when you want them to run. a. For example, we scheduled the interval to be daily at 2:00 am. Tip: We recommend that you do schedule replication to run only once a day, preferably at an off-peak time. b. After updating the fields, click Add. 8. Click OK. 9. Move 1. Start Extraction back into production mode. Tip: You can see the scheduled job in the Data Warehouse Center Work in Progress window, with a status of Scheduled. The job can be removed as a scheduled job by putting the mode back into development. Select Schedule, select the scheduled job from the list and click Remove. Click OK and put back into production mode. Configure data source to datamart The WebSphere Commerce Accelerator Business Intelligence reports used to display WebSphere Commerce Analyzer reports are located on the WebSphere Commerce node. The Business Intelligence reports need to retrieve data from the datamart database (wcamart) on the WebSphere Commerce Analyzer node to be displayed in the report. In order to access this data, the following tasks must be completed (one time configuration) on the WebSphere Commerce node: Catalog the tcpip node for DB2 Catalog the datamart database for DB2 Create a WebSphere Application Server data source Note: For additional information on creating a data source for WebSphere Commerce Analyzer, refer to the IBM WebSphere Commerce Analyzer chapter in the Additional Software Guide, IBM WebSphere Commerce V5.5 product guide. 862 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Catalog the tcpip node for DB2 On the WebSphere Commerce node, do the following to catalog the tcpip node where the datamart database resides, which in our example is the WebSphere Commerce Analyzer node: 1. Open a DB2 command window. 2. Catalog the tcpip node as follows from the DB2 command window: db2 catalog tcpip node wca1 remote wca1 server 50000 Where wca1 is the node name of the WebSphere Commerce Analyzer node (DB2 Server), and db2c_db2inst1 is the connection port defined in /etc/services for the DB2 Server. 3. Attach to a remote DB2 Server (WebSphere Commerce Analyzer node) to verify the connection: db2 attach to wca1 user ctrluser using Catalog the datamart database for DB2 Catalog the DB2 datamart database (wcamart) as follows from the DB2 command window on the WebSphere Commerce node: db2 catalog db wcamart at node wca1 Create a WebSphere Application Server data source Create a data source for the WebSphere Commerce Analyzer datamart database (wcamart) for the WebSphere Application Server on the WebSphere Commerce node. 1. Ensure the WebSphere Application Server server1 application server has been started. Note: In our example (default), server1 is the application server where the WebSphere Application Server Administration Console enterprise application is installed. 2. Access the WebSphere Application Server Administration Console by entering the following URL in a Web browser: http://:9090/admin 3. Log on to the WebSphere Application Server Administration Console. 4. From the navigation tree, select and expand Resources and select JDBC Providers. 5. When the JDBC Providers window appears, we did the following: a. Click Browse Servers. Chapter 20. Commerce analytics 863 b. When the Select a Server Scope window appears, select WC_ and click OK. c. When the JDBC Providers window appears, click Apply. 6. From the table listing JDBC Providers, select wc1 - WebSphere Commerce JDBC Provider. Where wc1 is the name of the WebSphere Commerce instance. 7. When the wc1 - WebSphere Commerce JDBC Provider window appears, click Data Sources (Version 4) under Additional Properties. 8. When Sources (Version 4) window appears, click New. 9. When the New window appears, we entered the following and then clicked OK: – Name: WCA DataSource Note: The dataSourceName WCA DataSource is found throughout the .xml files listed found in the \xml\tools\bi. For this reason, we strongly recommend that this name be used. Any changes to the data source name should be made within the WebSphere Commerce Configuration Manager, and the WebSphere Application Server data source should be configured to be the same name. – – – – – JNDI Name: jdbc/WCA DataSource Description: WCA DB2 DataSource Database Name: wcamart Default User ID: martuser Default Password: 10.Click Save from the Task bar. 11.Click Save on the Save window. 12.Logout and close WebSphere Application Server Administration Console. 13.Stop the server1 application server (no longer needed). 14.Restart the WebSphere Commerce instance application server for the WCA DataSource to take effect. 20.2.9 Accessing out-of-box Accelerator reports Now that we have implemented WebSphere Commerce Analyzer runtime environment, we can generate some transactions, and view the out-of-box WebSphere Commerce Accelerator reports for WebSphere Commerce Analyzer. There are two sets of reports available from WebSphere Commerce Accelerator: 864 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide standard WebSphere Commerce reports and WebSphere Commerce Analyzer reports, which is the focus of this section. Note: For more information, refer to the “After configuration” chapter in the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5. To access the out-of-box WebSphere Commerce Accelerator Business Intelligence reports specific to WebSphere Commerce Analyzer, do the following: 1. Enter the following URL in the Microsoft Internet Explorer Web browser: https://:8000/accelerator 2. Log on as the site administrator (for example, wcadmin). 3. Select the desired store (for example, ToolTech) and click OK. 4. From the main menu, select Store -> Business Intelligence Reports. 5. When the Business Intelligence Reports window appears, as seen in Figure 20-31 on page 866, we selected the Product report. Then select Units Sold. Note: Ensure you have taken action for the information listed in the tip found in 20.2.7, “WebSphere Commerce Analyzer business options configuration” on page 852, to address the order status. Failure to take action will result in no data being displayed in the default Business Intelligence reports. Chapter 20. Commerce analytics 865 Figure 20-31 Business Intelligence reports 6. The Order Summary report should look like the Sample Order Summary report in Figure 20-32 on page 867. 866 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 20-32 Sample Order Summary report 20.2.10 Change passwords During the configuration, we accepted the default settings and created martuser and ctrluser with the same password as the user ID, as instructed in the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 product guide. For security reasons, we recommend that you change the default passwords by referring to the Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 for details. Congratulations, the WebSphere Commerce Analyzer integration with WebSphere Commerce is now complete! Chapter 20. Commerce analytics 867 20.3 Create customized reports This section describes how to customize analytical reports using the WebSphere Commerce V5.5 reporting framework. We will create a new report based on Order Summary that groups orders by logon ID. The customized report will list users who have placed the most orders on the site. The report will be created in a way to display only those users that have placed a specific number of orders or spent a specific amount of money. The section highlights the following key tasks necessary to create a customized Business Intelligence report: Overview Before customizing a new report Creating input and output JSP files Defining the report with XML files Add the XML files to the resources.xml file Add the customized report to a page in Accelerator Modifying the .properties files Adding view commands to the database Modify SQL and test the customized report Adding access control to the customized report Note: We have included the ITSO sample files for the report customization example in the c:\6969code\wcareport directory. 20.3.1 Overview The reporting framework allows you to define a report by using XML and create the report input and output views using JSPs. These customized files reside on the WebSphere Commerce node. Both predefined and customized business reports are accessed through the WebSphere Commerce Accelerator on the WebSphere Commerce node. The reports accessible from WebSphere Commerce Accelerator consist of both WebSphere Commerce reports and WebSphere Commerce Analyzer reports. In other words, if a user chooses not to install WebSphere Commerce Analyzer, they will still be capable of accessing and customizing the WebSphere Commerce predefined reports. These reports are generated by extracting data from the WebSphere Commerce instance database. On the other hand, WebSphere Commerce Analyzer predefined reports are generated by extracting data from the datamart database (for example, wcamart) located on the WebSphere Commerce Analyzer node. These reports are therefore the result of mined, organized data that has been prepared specifically 868 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide for reporting. The files you will be working with for both WebSphere Commerce and WebSphere Commerce Analyzer reports (such as XML files, JSP files, etc.) are located on the WebSphere Commerce node. This section provides a working example of how to customize a WebSphere Commerce Analyzer and includes the following topics: The different components created when customizing a report and how they are used in the WebSphere Commerce reporting framework. Modifying an existing report. Using the modified report to create a customized report. The working example provided throughout this chapter outlines the necessary steps in successfully customizing a WebSphere Commerce Analyzer report. Note: Customizing WebSphere Commerce and WebSphere Commerce Analyzer reports both require similar procedures. The main differences are the files and file locations used to create these reports. For example, the WebSphere Commerce report OrderSummary has a different file structure and location from the WebSphere Commerce Analyzer report biOrderSummary. Both reports have a similar purpose, but the contents of their files are completely different, since the two reports are pulling data from different databases. Despite the differences in file content and file location, both WebSphere Commerce and WebSphere Commerce Analyzer reports are generated using the similar file structures and formats. Each new report requires two JSP files, one for the input view and one for the output view. This means one JSP file will display the interface for entering query information, and the other JSP will serve as the actual report output. Additionally, each new report requires three XML files, one of which contains SQL queries for abstracting data from the database. This will be shown in greater detail throughout this section. 20.3.2 Before customizing a new report The first step in customizing a report is to choose the purpose of the new report. This may seem like an obvious step but is actually very important. The process of customizing a report becomes much easier if you fully understand what the report is to do, and furthermore, are able to find an existing report that relates to the new report. In this working example, the custom report will list the users who have placed the most orders on the site. This report will be created in a way to display only those Chapter 20. Commerce analytics 869 users who have placed a specific number of orders or spent a specific amount of money. The report is called Top Customer Activity, or biTopCustomerActivity. After deciding the purpose of the desired report, it is important to locate an existing report that is similar in structure to the report you want to create. This will make the process of customizing reports much easier. By selecting an existing report and using the code as a framework, much of the work is already done for you. The main customization occurs when creating the SQL query that generates the report. Most of the other files simply allow you to replace the existing report name with the newly created report name. In this example, the existing report chosen is called Order Summary or biOrderSummary and summarizes order details by date. Many of the steps in creating a new report will consist of replacing the text OrderSummary with the text TopCustomerActivity. The “bi” in both the biTopCustomerActivity report and the biOrderSummary report stands for business intelligence. In WebSphere Commerce Accelerator, the WebSphere Commerce Analyzer reports (such as Order Summary) can be accessed by doing the following: 1. Make sure the WebSphere Commerce Application Server and HTTP Server are started and select Start -> Programs -> IBM WebSphere Commerce -> WebSphere Commerce Accelerator. 2. Log in to WebSphere Commerce Accelerator and select the store you wish to view. Click OK. The login user name in this example is wcsadmin. 3. A new window will open. From the main menu, select Store -> Business Intelligence Reports. This is shown in Figure 20-33 on page 871. 870 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure 20-33 Access Business Intelligence reports for WebSphere Commerce Analyzer 4. The various WebSphere Commerce Analyzer reports appear. The existing report, Order Summary, is located in this window. The reports are organized by category and each report includes a report description. If selected, some of the WebSphere Commerce Analyzer reports will display other reports stemming from the original report topic. 20.3.3 Creating input and output JSP files A new report requires a JSP input and JSP output view. These WebSphere Commerce Analyzer JSP files are typically named biReportNameReportInputView.jsp and biReportNameReportOutputView.jsp. If these were files used to create a WebSphere Commerce report (as opposed to a WebSphere Commerce Analyzer report), the file names would not include “bi” in the beginning of the name. In this example, you want to copy the JSP input and output files from the existing Order Summary report. Based on the above criteria, the files are appropriately Chapter 20. Commerce analytics 871 named biOrderSummaryReportInputView.jsp and biOrderSummaryReportOutputView.jsp. These existing JSP files are located in the \installedApps\\WC_.ear\CommerceAccelerator.w ar\tools\bi directory, where is the host name of the WebSphere Commerce node and is the instance name. In order to successfully modify these existing JSP files and create new JSP files for the Top Customer Activity report, do the following: 1. Copy the Order Summary JSP files: – biOrderSummaryReportInputView.jsp – biOrderSummaryReportOuputView.jsp To corresponding file: – biTopCustomerActivityReportInputView.jsp – biTopCustomerActivityReportOutputView.jsp 2. For each of the files (biTopCustomerActivityReportInputView.jsp and biTopCustomerActivityReportOutputView.jsp), find and replace all occurrences of orderSummary with topCustomerActivity. The find and replace most be done for with the first character of the strings in uppercase and lowercase (two difference cases). Example 20-5 provides a sample of the biTopCustomerActivityReportInputView.jsp file for reference. Example 20-5 Sample from the biTopCustomerActivityReportInputView.jsp function savePanelData()\ { /////////////////////////////////////////////////////////////////////////////// // Specify the report framework particulars /////////////////////////////////////////////////////////////////////////////// setReportFrameworkOutputView("DialogView"); setReportFrameworkParameter("XMLFile","bi.biTopCustomerActivityReportOutputDial og"); setReportFrameworkReportXML("bi.biTopCustomerActivityReport"); setReportFrameworkReportName("biTopCustomerActivityReport" + document.all.time[document.all.time.selectedIndex].value); /////////////////////////////////////////////////////////////////////////////// // Specify the report specific parameters and save 872 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide /////////////////////////////////////////////////////////////////////////////// setReportFrameworkParameter("Time", document.all.time[document.all.time.selectedIndex].text); saveReportFramework(); top.saveModel(parent.model); return true; } In the portion of code in Example 20-5 on page 872, TopCustomerActivity is bold in places you should have replaced OrderSummary. 3. Modify the biTopCustomerActivityReportInputView.jsp. In our example, we will not address all date options. We will only list all Top Customer orders regardless of date for the example. In practice, you may choose to provide by-month, by-day, etc. 4. Save the two files. Note: For more information on the savePanelData() function, refer to the Accelerator Customization Guide, IBM WebSphere Commerce V5.4 product guide. 20.3.4 Defining the report with XML files Each customized report requires the user to create three XML files. The typical WebSphere Commerce Analyzer XML file names and functions are shown in Table 20-5. Table 20-5 .XML file names and functions XML file name Function biReportNameReportInputDialog.xml Contains configuration and display text for the input JSP biReportNameReportOutputDialog.xml Contains configuration and display text for the output JSP biReportNameReport.xml Contains the SQL used to generate the report Similar to the steps followed in creating input and output JSP files, the XML files used to create the Order Summary report should also be copied and modified. The following three XML files should be copied: biOrderSummaryReport.xml Chapter 20. Commerce analytics 873 biOrderSummaryReportInputDialog.xml biOrderSummaryReportOutputDialog.xml These three file are located in the \xml\tools\bi directory. In order to successfully modify these existing XML files and create new XML files for the Top Customer Activity report, do the following: 1. Copy the Order Summary XML the following files from the \xmll\tools\bi directory: – biOrderSummaryReport.xml – biOrderSummaryReportInputDialog.xml – biOrderSummaryReportOutputDialog.xml To the following corresponding file names: – biTopCustomerActivityReport.xml – biTopCustomerActivityReportInputDialog.xml – biTopCustomerActivityReportOutputDialog.xml 2. For each of the files (biTopCustomerActivityReport.xml, biTopCustomerActivityReportInputDialog.xml, and biTopCustomerActivityReportOutputDialog.xml), find and replace all occurrences of orderSummary with topCustomerActivity. The find and replace most be done for with the first character of the strings in uppercase and lowercase (two difference cases). Note: In biTopCustomerActivityReportInputDialog.xml file, make sure that URL property is set to BITopCustomerActivityReportInputView. The value is case sensitive and will be referenced within the viewreg table. 3. Modify biTopCustomerActivityReportI.xml. For the purposes of the example, we have limited the number of date options to all dates. We made the following modifications to the biTopCustomerActivityReportI.xml: – Modify the SQL to generate the desired report contents We will address this in more detail in 20.3.9, “Modify SQL and test the customized report” on page 880. – Remove all but one of the report XML tags (limited to all dates) – Modify the columns tags to reflect the columns of the results of the XML – Update column headers to reflect properties file entries For details, refer to the c:\6969code\wcareport\biTopCustomerActivityReport.xml file. 874 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 4. Save the three XML files. We will update the biTopCustomerActivityReport.xml file to include SQL in 20.3.9, “Modify SQL and test the customized report” on page 880. For reference, we have provided the XML input dialog in Example 20-6. Example 20-6 Sample XML input dialog Recall the XML output dialog displays text for the output JSP file. In the XML output dialog file shown below, notice there are two buttons: Print and OK. These buttons are used accordingly with the report interface and serve as an example of how the XML output dialog file interacts with the related JSP file, as seen in Example 20-7. Example 20-7 Sample XML output dialog 20.3.5 Add the XML files to the resources.xml file In order for the new report to be a resource to the WebSphere Commerce Accelerator, we need to update the resource.xml file found in the \xml\tools\bi directory. Chapter 20. Commerce analytics 875 It is necessary to add all three of the Top Customer Activity XML files to the resources.xml file. Before doing this, back up the resources.xml file so that you will maintain a copy of the original file. In this working example, the lines of code in Example 20-8 were entered into the resources.xml file below the Order Summary block of code. Example 20-8 Sample code for Order Summary LogonID (#PCDATA)> Password (#PCDATA)> VerifyPassword (#PCDATA)> WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Title (#PCDATA)> LastName (#PCDATA)> FirstName (#PCDATA)> MiddleName (#PCDATA)> Chapter 21. Messaging integration with MQ and e-mail 943 21.6.5 Update .xml to include new DTD Once the DTD file has been created, it must be copied to the \xml\messaging directory. The WebSphere Commerce \instances\\xml\.xml file must be updated to include the DTD file (for example, Create_ITSO_Customer.dtd). Chapter 21. Messaging integration with MQ and e-mail 945 There are two methods possible for updating the WebSphere Commerce instance settings stored in the .xml file: Configuration Manager The Configuration Manager provides a GUI for adding the DTD, performs validation, and is designed to update the settings of the .xml. Direct update to the .xml file with an editor Updating the .xml file directly with an editor should only be done by experienced WebSphere Commerce users, due to the increased possibility of error and subsequent troubleshooting in the event of an error. After making the changes to the .xml file for either method, the WebSphere Commerce instance application server must be restarted for the changes to take effect. Note: Whenever possible, we recommend using the Configuration Manager to modify settings stored in the WebSphere Commerce .xml file. When using the Configuration Manager, validation can be performed to ensure the .xml is updated properly. When updating the .xml file directly, there is a greater chance for error. To update the .xml settings to include the new DTD using the Configuration Manager do the following: 1. From the Configuration Manager, select and expand -> Commerce -> Instance List -> -> Instance Properties -> Messaging. 2. Enter the Create_ITSO_Customer.dtd file name in the Inbound Message DTD files text field. Note that entries are separated with a comma “,”. 3. Click Apply to save the settings. 4. The Configuration Manager can now be closed. 5. The WebSphere Commerce application server will need to be restarted for the changes to take effect. 21.6.6 Create inbound XML message To simulate the XML message being sent from the back-end system, we have hand crafted a sample Create_ITSO_Customer message, as seen in Example 21-4 on page 947. The sample inbound XML message file is called Create_ITSO_Customer.xml. The contents of the Create_ITSO_Customer.xml 946 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide include the message elements that will be mapped to the required UserRegistrationAdd controller command parameters. Example 21-4 contains the ITSO-provided Create_ITSO_Customer.xml file. This file can be found in the ITSO sample code c:\6969code\mq directory. Note: To use the ITSO-provided Create_ITSO_Customer.xml, you will need to change the Store ID value to that of your published store. Example 21-4 ITSO sample Create_ITSO_Customer.xml jredbook1 password0 password0 10001 1 ITSO IBM Mr. Joe Redbook M 100 Redbook Drive RTP NC 27709 Chapter 21. Messaging integration with MQ and e-mail 947 USA 21.6.7 Verify new inbound XML message We are now ready to verify that the new inbound XML message works properly. This section contains the following tasks to verify the inbound XML message for WebSphere MQ: Download the WebSphere MQ IH03 test tool Add the message to WebSphere MQ wc_inbound_ser queue Verify update of USERREG table Log on to the store as the new customer Download the WebSphere MQ IH03 test tool In order to simulate the back-end system sending the XML message to WebSphere MQ, we need to put the sample message (Create_ITSO_Customer.xml) described in Example 21-4 on page 947 into the wc_inbound_ser queue. IBM WebSphere MQ provides a test tool that can be downloaded to support the testing needed. The WebSphere MQ IH03: message display, test, and performance utility can be downloaded from: http://www.ibm.com/software/integration/support/supportpacs/individual/ih03 .html We unpacked the WebSphere MQ IH03 test tool to the c:\mq_ih03 directory. Note: The WebSphere MQ IH03 test tool we downloaded is for Windows. This tool is also available for other platforms. Add the message to WebSphere MQ wc_inbound_ser queue To simulate the inbound message being received by WebSphere MQ, we will read all of the inbound XML message (Create_ITSO_Customer.xml) and write the message to the WebSphere MQ wc_inbound_ser using the WebSphere MQ IH03 test tool. 948 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide To use the WebSphere MQ IH03 test tool to put the message in the wc_inbound_ser queue, complete the following steps: 1. Start the WebSphere MQ IH03 test tool by running rhutil.exe from the directory to which the tool was unpacked (for example, c:\mq_ih03). 2. We entered the following to put the sample inbound_message.xml message into the wc_inbound_ser queue: a. Select the Main tab and enter the following: • • • Queue Manager Name: wc_mq_qmgr Queue Name: wc_inbound_ser File Name: c:\6969code\mq\Create_ITSO_Customer.xml Where the File Name is the path and filename of the sample inbound message supplied with the ITSO sample code. b. Select the Data tab and in the Data Format field, select XML. When you select XML, the message data is displayed and readable within the tool. c. Select the Main tab and click Write Q to put message into the wc_inbound_ser queue. We accepted the default settings for the remaining options. If the test message is consumed from the wc_inbound_ser and, no message appears in the wc_outbound queue or the wc_error queue, your message is successfully received by the WebSphere Commerce. Successful processing of the inbound Create_ITSO_Customer message results in a user registration and data stored in the WebSphere Commerce instance database. For example, the USERREG table and other tables will be populated with customer registration information. Note: In the event of an XML message error, the original message will appear in wc_error and the error inwc_outbound WebSphere MQ queues. Verify update of USERREG table After the inbound message is processed, the customer registration information is stored in the USERREG table of the WebSphere Commerce instance database. To verify that the database has the registered customer information, complete the following steps: 1. Start a DB2 Command window by clicking Start -> Programs -> IBM DB2 -> Command Line Processor. 2. Connect to the store database as follows: connect to Chapter 21. Messaging integration with MQ and e-mail 949 3. Enter the following SQL: select * from userreg where logonid = ‘jredbook1’ You should see a record in the database followed by the message “text 1 record(s) selected”. 4. This verifies that the inbound message has been processed successfully by the WebSphere Commerce and the customer is in the WebSphere Commerce instance database. Log on to the store as the new customer To complete the verification of the inbound messaging Create_ITSO_Customer message, we recommend that you log on to the store with the user created. In our example, we logged on the store with the user ID jredbook1. 21.7 Scenario: e-mail notification This section describes an integration scenario using WebSphere Commerce outbound messaging e-mail notification with the JavaMail (e-mail) connector. We used the Java Apache Mail Enterprise Server (James), although any SMTP-based e-mail product can be used. We will enable the WebSphere Commerce e-mail transport and configure the e-mail notification for the message type Notification message for password reset. Note: For an example of customizing e-mail using a JSP template, refer to Chapter 13, “Customize a store: Price Watch example” on page 393. This scenario is organized into the following tasks: Java Apache Mail Enterprise Server (James) configuration Enable the e-mail transport Configure the e-mail transport Configure the e-mail message type Verify e-mail notification for password reset 21.7.1 Java Apache Mail Enterprise Server (James) configuration The Java Apache Mail Enterprise Server (also known as Apache James) is a 100% pure Java SMTP and POP3 Mail server and NNTP News server. James is created by the Apache Software Foundation and is available free from: http://james.apache.org/ 950 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: The version of James that is tested with this example is V2.1.3. No earlier versions were tested. No guarantee can be made that the configuration steps detailed in this redbook will apply to later versions, although any version should work if configured correctly. Installing James on the Windows platform To install James, complete the following steps: 1. Download James V2.1.3 from the following address to a temporary directory: http://apache.oregonstate.edu/jakarta/james/binaries/james-2.1.3.zip 2. Unzip the james-2.1.3.zip file into the root of one of your drives. It will be assumed that you use the C: drive in this example. Make sure you use the option of your zip utility to maintain the directory structure stored in the zip. 3. Rename the james-2.1.3 directory that was created to James. You may install James into another directory if you wish, but it is assumed in this book that James is installed to C:\James. 4. Since James is a Java application, you must add the location of the Java runtime code to your system path. To do this, complete the following steps: a. Right-click My Computer on your desktop and select Properties. b. Click the Advanced tab. c. Click Environment Variables. d. In the System variables list, find and click the Path variable. e. Click Edit. f. Add the following to the end of the entry in the Variable Value text box: \java\bin; g. Click OK to confirm the change. h. Click OK to exit the Environment Variables window. i. Click OK to exit the System Properties window. j. Restart your system. 5. Click Start -> Run. 6. Enter Cmd and click OK. A command window will open. 7. Use the cd command to navigate to the bin directory of the James installation. For example: cd C:\James\bin Chapter 21. Messaging integration with MQ and e-mail 951 8. To test if James is working properly, run the following command: run.bat If you see output similar to that shown in Figure 21-15, then James is working correctly. Figure 21-15 Output from James when run.bat is executed 9. Stop the James server by pressing Ctrl+C and answer Y if prompted with Terminate batch job (Y/N)?. 10.To install James as a Windows service, enter the following from the c:\james\bin directory: wrapper -i ..\conf\wrapper.conf You will see the following output if this works correctly: wrapper | James Mail Server 2.1 installed. 11.Start the James service by doing the following: a. Click Start -> Programs -> Administrative Tools -> Services. b. Right-click the James Mail Server 2.1 service and select Start. 12.Next, we need to add a user to James for use in our example. Complete the following steps: a. Click Start -> Run.... b. Enter telnet and click OK. 952 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide c. Configure telnet and log on to the James server by entering the following commands. set crlf set local_echo open localhost 4555 root root Where root is the server user name and password. Press Enter. d. Add the new user by entering adduser and pressing Enter, where and are the same as your administrator user in WebSphere Commerce. For simplicity, make sure you do not use a different user name and password for the James server. e. You can check the user was created by entering listusers and pressing Enter. 13.Type quit and press Enter twice to exit. You have now successfully configured James. Testing James You can test the installation by setting up an account using an e-mail client on the server and sending yourself an e-mail. Configure the mail account to use localhost as the POP3 and SMTP server, using the user name and password you created in James. Send the test mail to @localhost, where is the user you created. Configure Outlook Express to test James To configure Outlook Express with an account for testing James, complete the following steps: 1. Launch Outlook Express. 2. Click Tools -> Accounts on the menu bar. The Internet Accounts window will open. 3. Click the Add button and select Mail... from the pop-up menu. The Internet Connection Wizard window will open. 4. To add the Mail account, do the following: a. In the Display Name text box, enter ITSO Test (or a name of your choice) and click Next. Chapter 21. Messaging integration with MQ and e-mail 953 b. In the E-mail address text box, enter @localhost (where is the user that you created earlier in James) and click Next. c. In the Incoming mail and Outgoing mail text boxes, enter localhost and click Next. d. In the Account name and Password text boxes, enter the user name and password of the account that you created in James with the adduser command and click Next. e. Click Finish to close the wizard. You will be returned to the Internet Accounts window. 5. Click Close to return to the main window. Send test e-mail The test account is now created. To make sure it is working correctly, send yourself an e-mail by completing the following steps: 1. Click Create Mail in the tool bar. The New Message window will open. 2. In the To: text box, enter @localhost (where is the user that you created earlier in James). 3. Enter some text in the Subject field and the message body. 4. Click Send. 5. In the main Outlook Express window, click Send and Receive. You should see the e-mail you just sent in the inbox. If you see the e-mail, James and Outlook Express are correctly configured. Note: The use of localhost is just for test purposes. In a production environment, you should enter the actual host name of the server. 21.7.2 Enable the e-mail transport To enable the e-mail transport from the WebSphere Commerce Configuration Manager, do the following: 1. Start the Configuration Manager Server Windows service, IBM WebSphere Commerce Configuration Manager. 2. Start the Configuration Manager by clicking Start -> Programs -> IBM WebSphere Commerce -> Configuration. 3. Log on as webadmin and enter your password. 954 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 4. Select and expand -> Commerce -> Instance List -> -> Transports -> Outbound -> JavaMail -> ConnectionSpec. 5. Click the Advanced tab and enter the following and then click Apply: – – – – – host: protocol: smtp port: 25 sendpartial: false retryDuration: 1 6. The configuration settings will not take effect until the WebSphere Commerce application server has been restarted. 21.7.3 Configure the e-mail transport To configure the e-mail transport from the WebSphere Commerce Administration Console, complete the following steps: 1. Ensure the WebSphere Commerce application server is started. 2. Start the WebSphere Commerce Administration Console. https://:8002/adminconsole 3. Log on to the Administration Console. 4. Select Site and click OK. 5. Select Configuration -> Transports. 6. Click E-Mail in the transports table. 7. In the Host entry in the table, enter the address of the server on which your SMTP server is running. 8. Click OK. 9. Confirm that the status of e-mail transport is Active. If it is not, complete these steps: – Check the box next to E-Mail. – Click Change Status. The status should be set to Active. 21.7.4 Configure the e-mail message type To configure the e-mail message type, complete the following steps: 1. From the WebSphere Commerce Administration Console, click Configuration -> Message Types. Chapter 21. Messaging integration with MQ and e-mail 955 2. From the Message Type Configuration page, check Notification message for password reset (see Figure 21-16) and then click Change. Figure 21-16 Message Type Configuration: Notification message for password reset 3. From the Message Transport Assignment page, ensure the following parameters are set and then click Next: – – – – Message Type: Notification message for password reset Message Severity: 0 to 0 Transport: E-mail Device Format: Standard Device Format Note: Notice the Archive Message after sent check box feature. 4. On the Message Transport Assignment page 2, we entered the following and then clicked Finish: – Host: (In our test environment, we used localhost) 956 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – – – – – Protocol: smtp Port: 25 Send Partial: false Retry duration: Recipient: [email protected] This value is a placeholder. The actual recipient will be the user e-mail address. – Sender: wcadmin@ – Subject: Password reset – Reply To: wcadmin@ 5. Click Logout to exit the Administration Console. 6. Restart the WebSphere Commerce application server. 21.7.5 Verify e-mail notification for password reset To verify that the e-mail messaging configuration for password reset is working properly, complete the following steps: 1. To test the password reset, enter your store URL. 2. Register a user with an e-mail address that is configured for your SMTP mail server. 3. Log off or close the Web browser window. 4. Enter the store URL, and click the Register button. 5. Click the Forgot your password? link. 6. When the Forgot your password page appears, enter your e-mail address that you previously registered and click Send me my password. 7. You should now see a message saying that your password has been sent. 8. From your e-mail client, verify that your new password has been received. 9. Test your new password by logging into your store. Chapter 21. Messaging integration with MQ and e-mail 957 958 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Part 6 Part 6 Appendixes © Copyright IBM Corp. 2003. All rights reserved. 959 960 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide A Appendix A. AIX tips This appendix provides common AIX tasks and commands. See the redbook IBM Certification Study Guide - pSeries AIX System Administration, SG24-6191 for more information. © Copyright IBM Corp. 2003. All rights reserved. 961 Common tasks and commands This section includes some common tasks and commands. Operating system revision level Enter the following command to retrieve the AIX revision level: # oslevel -r Tip: If the text-based smitty utility is not behaving as expected (certain keys do not work as indicated), check that your TERM setting is a supported value, such as dtterm or vt100. Mount the CD-ROM To mount the CD-ROM, do the following: # mount -r -v cdrfs /dev/cd0 /mnt Unmount the CD-ROM To unmount the CD-ROM, do the following: # cd / # umount /mnt Verify if port is in use To verify if a TCP/IP port is in use, do the following: # netstat -an | grep For example, if I want to verify if something is listening on port 9090, I would enter the following: # netstat -an | grep 9090 If there is something listening on this port, you get a LISTEN response. If there is nothing listening on the specified port, the command will not return any message (nothing listening on port). Create a volume group 1. From the command line, launch the smitty utility: smitty mkvg. 2. Enter a name for the new volume group, for example, datavg. 3. Choose a physical partition size appropriate for the physical volumes to be added. 4. From the list of available physical volumes, select those that are to be added to this volume group. 962 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 5. Press Enter to add the volume group. Figure A-1 Add a volume group Create a logical volume 1. From the command line, launch the smitty utility. Enter smitty mklv. 2. Select the new volume group, datavg. 3. Enter a name for the new volume group, for example, db2lv. 4. Use an initial size of 64 logical partitions (for a total of 1 GB, if the volume group uses 16 MB physical partitions). The logical volume can be extended later, if more storage space is required. The other parameters can also be optimized for your particular data or implementation, for example, if you wish to use disk mirroring and other features. 5. Press Enter to add the logical volume. Appendix A. AIX tips 963 Figure A-2 Add a logical volume Create a file system 1. For this example, we use a journaled file system rather than configuring a raw disk or other storage device. From the command line, launch the smitty utility by entering smitty crjfs. 2. Choose Add a Standard Journaled File System and select datavg. 3. Define a local mount point called /db2data. 4. Use a file system size of 1024000 512-byte blocks (for an initial size of 512 MB) and choose to mount automatically at system restart. 5. Press Enter to add the new file system. 964 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure A-3 Add a standard journaled file system Mount a file system Mount the new file system for the first time and confirm that it is available by using the df command: # mount /db2data # df -k Change the size of a file system To change the size of a file system, use the chfs command: # chfs -a size=’’ / Where is the number of 512-byte blocks, and is the local mount point of the file system. For example: # chfs -a size=’600000’ /home AIX performance monitoring tools The topas command is part of the perfagent.tools fileset, found on the AIX 5.1 installation CD 2. It requires the bos.perf.tools fileset found on CD 1. Use vmstat and iostat to monitor system resource usage. These utilities are part of the bos.acct fileset, found on the AIX 5.1 installation CD 2. Appendix A. AIX tips 965 Starting and stopping TCP/IP daemons To stop all TCP/IP services, execute: /etc/tcp.clean For security reasons, it may be desirable to prevent certain services from starting at bootup (for example, snmpd). Simply comment out the corresponding lines in the /etc/rc.tcpip file: #start /usr/sbin/snmpd "$src_running" To start TCP/IP services, execute: # /etc/rc.tcpip Shut down AIX To shut down AIX: # shutdown -F now To shut down AIX and reboot: # shutdown -F -r now List AIX file systems To list AIX file systems: # df To list AIX file system in KB: # df -k Directory list To list an AIX directory # du To list an AIX directory in KB: # du -k 966 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Adding additional IP addresses to an interface When aliasing for Network Dispatcher, the ndcontrol cluster configure command (or GUI) will do this for the cluster address. 1. 2. 3. 4. 5. 6. 7. Type smitty tcpip. Select Further Configuration. Select Set network interfaces. Select Network Interface Selection. Select Configure aliases. Add an IPv4 network alias. Select the network interface in use (for example, en0). Enter the new IP address and network mask. If the wrong gateway is specified, you need to flush the routing table before it can be reset. Installing OpenSSH on AIX 5.1 In order to use Secure Shell (SSH) programs such as Secure FTP (SFTP), SSH needs to be installed on all machines and the SSH daemon started. The IBM AIX Toolbox for Linux Applications includes a port of OpenSSH 2.9.9p2. However, OpenSSH (found at http://www.openssh.org) is under continuous development, and newer versions are available. 1. Download the following packages to a temporary directory (if you have not previously done so, you will need to register with the IBM Web site): – IBM AIX Toolbox Cryptographic Content, found at: http://www6.software.ibm.com/dl/aixtbx/aixtbx-p • • • • openssh-2.9.9p2-6.aix4.3.ppc.rpm openssh-clients-2.9.9p2-6.aix4.3.ppc.rpm openssh-server-2.9.9p2-6.aix4.3.ppc.rpm openssl-0.9.6b-2.aix4.3.ppc.rpm – Pseudo Random Number Generator Daemon, obtained from: ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/prngd/ • prngd-0.9.23-1.aix4.3.ppc.rpm 2. AIX 5L™ includes the Red Hat Package Manager (RPM) utility by default. As the root user, install the packages from the command line, in the following sequence: rpm -ihv openssl-0.9.6b-2.aix4.3.ppc.rpm rpm -ihv prngd-0.9.23-1.aix4.3.ppc.rpm The pseudo random number generator daemon starts up automatically. Appendix A. AIX tips 967 rpm -ihv openssh-2.9.9p2-6.aix4.3.ppc.rpm rpm -ihv openssh-server-2.9.9p2-6.aix4.3.ppc.rpm The SSH daemon starts up automatically. rpm -ihv openssh-clients-2.9.9p2-6.aix4.3.ppc.rpm The SSH programs are now available in /usr/bin. Note: For increased security, you may not wish to install the openssh-server component on all machines. For example, you can install the openssh-clients on a machine in the DMZ to permit it to make SFTP connections to the secure network. However, that machine itself could not accept SFTP connections without the server component. 968 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide B Appendix B. Solaris tips This appendix provides basic procedures, tasks, and commands necessary to install, configure, and manage the Solaris 8 (2.8) Operating Environment in preparation for a WebSphere Commerce V5.5 installation. The appendix is organized into the following sections: Solaris 8 installation Common Solaris tasks and commands Where to find information about Solaris © Copyright IBM Corp. 2003. All rights reserved. 969 Solaris 8 installation WebSphere Application Server V5 and WebSphere Commerce V5.5 requires Solaris 8 (2.8) for the Sun SPARC platform. The steps in a Solaris 8 installation are organized into the following sections: Solaris 8 pre-installation Solaris 8 installation This phase installs the required base operating system files and configures the system with basic network and locale information. Solaris 8 interactive installation and configuration This section provides the installation of selected software options and file system layouts. Installing software on Solaris Solaris 8 post-install configuration This phase provides the necessary steps to configure Solaris for common server usage. Solaris 8 maintenance update installation This section describes the steps to download and install Solaris 8 maintenance update. Solaris 8 recommended patches This section describes the steps to download and install Solaris 8 recommended patches. Solaris 8 pre-installation Before installing Solaris 8 on your system, it is recommended to have the following information from the network administrator: Hostname (for example, www): This is the name that you wish to give your host to identify it uniquely on the local area network. Internet Protocol (IP) address (for example, 9.24.104.1): The IP address is used by the transport layer to locate a specific host on the worldwide Internet. Domain name (for example, itso.ral.ibm.com): The domain name is the organization to which your host belongs. All hosts on the Internet must belong to a domain. Domain Name Service (DNS) Server (for example, ns): The DNS server maps IP addresses to domain names, and domain names to IP addresses. 970 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Subnet Mask (for example, 255.255.254.0): The mask is used to locate hosts that form part of the same subnet on the local area network. You will also need to decide which language you wish to use when installing Solaris. The following languages are supported for performing the installation process: – – – – – – – – – – English French German Italian Japanese Korean Simplified Chinese Spanish Swedish Traditional Chinese Solaris 8 installation To install Solaris 8, do the following: 1. If the system has never had Solaris installed, you can simply insert the CD-ROM into its caddy and/or CD-ROM drive, and the Web Start installer will start. Alternatively, once the system has started booting, you can click Stop, press Enter, and when you get the OK prompt, you can simply type the following: ok boot cdrom You will then see output similar to the following: Boot device: /pci@1f,4000/scsi@3/disk@6,0:f File and args: SunOS Release 5.8 Version Generic 64-bit Copyright 1983-2000 Sun Microsystems, Inc. All rights reserved. Configuring /dev and /devices Using RPC Bootparams for network configuration information. Solaris Web Start 3.0 installer English has been selected as the language in which to perform the install. Starting the Web Start 3.0 Solaris installer Solaris installer is searching the system's hard disks for a location to place the Solaris installer software. Your system appears to be upgradeable. Do you want to do an Initial Install or Upgrade? 1) Initial Install 2) Upgrade Please Enter 1 or 2 > 2. If the following message appeared in the boot messages, then you may elect to perform an upgrade of the existing Solaris installation. However, most Appendix B. Solaris tips 971 administrators would back up their existing software, perform a fresh install, and then restore their data and applications once their system is operational. In this case, we will choose to perform an initial install, which will overwrite the existing operating system. After you enter 1, and press Enter, you will see a message like this: The default root disk is /dev/dsk/c0t0d0. The Solaris installer needs to format /dev/dsk/c0t0d0 to install Solaris. WARNING: ALL INFORMATION ON THE DISK WILL BE ERASED! Do you want to format /dev/dsk/c0t0d0? [y,n,?,q] 3. Formatting the hard drive will overwrite all existing data on the drive. If you had previously installed an operating system on the target drive (c0t0d0),you must ensure that you have backed up all data that you will need in the future. This includes both user directories and application installations. After pressing Y, the following message will appear: Enter a swap slice size between 384MB and 2027MB, default = 512MB [?] Note The swap size cannot be changed during filesystem layout. Press the Enter key to accept the default of 512 MB if your system has 256 MB physical RAM, as the sample system has. However, as a general rule, you should only allocate twice the amount of physical RAM as swap space; otherwise, system performance will be impaired. 4. The swap partition should be placed at the beginning of the drive, as the following message indicates, so that other slices are not dependent on its physical location: The Installer prefers that the swap slice is at the beginning of the disk. This will allow the most flexible filesystem partitioning later in the installation. Can the swap slice start at the beginning of the disk [y,n,?,q] 5. After answering Y to this question, you will be asked to confirm the formatting settings: You have selected the following to be used by the Solaris installer: Disk Slice : /dev/dsk/c0t0d0 Size : 1024 MB Start Cyl. : 0 WARNING: ALL INFORMATION ON THE DISK WILL BE ERASED! Is this OK [y,n,?,q] 6. If you answer Y, then the disk will be formatted and the mini-root file system will be copied to the disk, after which the system will be rebooted and the Web Start wizard installation process can begin: After files are copied, the system will automatically reboot, and installation will continue. 972 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Please Wait... Copying mini-root to local disk....done. Copying platform specific files....done. Preparing to reboot and continue installation. Solaris 8 interactive installation and configuration Complete the following steps for the Solaris interactive installation: 1. When the Solaris Web start Welcome window appears, click Next to proceed with the installation. The following windows will gather information to configure the following aspects of the system: – – – – – – Network Name Service Date and Time Root Password Power Management Proxy Server Information 2. Network configuration a. When the Network Connectivity window appears, choose the Networked option and click Next. b. When the DHCP window appears, choose No to indicate that the interface will be configured manually. Click Next. c. When the Host Name window appears, enter the host name and click Next. d. When the IP Address window appears, enter the IP address (V4 format) and click Next. e. When the Netmask window appears, enter the netmask number (for example, 255.255.254.0) and click Next. f. When the IPv6 window appears, disable the IPv6 by choosing No radio button and click Next. 3. Name Service configuration a. When the Name Service window appears, choose the Name Service you want to use and click Next. We chose DNS for the book. b. When the Domain Name window appears, enter the Name (for example, itso.ral.ibm.com) and click Next. c. Given we are using DNS, the next window is for the DNS Server Address. Enter the Server’s IP address (for example, 9.24.106.15) and click Next. d. When the DNS Search List window appears, enter the list of domains to be searched and click Next. Appendix B. Solaris tips 973 4. Date and Time a. When the Time Zone window appears, select an option to specify a time zone, for example, we chose Geographic region. Click Next. b. When the Geographic Region window appears, select your geographic region from the list. Click Next. c. When the Date and Time window appears, either accept the displayed date and time or specify a new one. Click Next. 5. Root Password configuration a. When the Root Password window appears, type in a password that you want to use for the root. Click Next. 6. Power Management configuration a. When the Power Management window appears, select the options to turn power management off and leave the selected option. Click Next. 7. Proxy Server configuration a. When Proxy Server Configuration window appears, select the option appropriate to you. We selected the option to directly connect to the Internet and not via a proxy. Click Next. 8. When the Confirm Information window is presented, click Confirm. You may choose to click Cancel in order to make any alterations. 9. You may be prompted to change the DNS settings. Click Continue. 10.Solaris is configured with the supplied information and is restarted. Installing software on Solaris After the Solaris is installed and configured, Web Start provides a facility to install software on Solaris. 1. When a Welcome window appears, click Next to continue or Exit to terminate the installation of software on Solaris. Click Next. When prompted, insert the Solaris Software CD 1 of 2 in the CD-ROM drive. 2. When the Select Type of Install window appears, select the Custom Install option. Click Next. 3. When the Software Localization window appears, accept the default entered during the installation of the operating system. In our example, North America is shown as the default. Click Next. 4. When the System Locale wndow appears, accept the default values. In our example, the default is english us.iso 8859-1. 974 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 5. When the Products window appears, accept the selected option of Solaris 8 Documentation and click Next. 6. When the Additional Products window appears, accept the defaults and click Next. 7. When the 64-bit selection window appears, select the option to install software with 64-bit and 32-bit support. Click Next. Note: Sun recommends installing software with both 64-bit and 32-bit support. 8. When the Solaris Cluster Configuration window appears, select Developer Solaris Software Group, and then click Next. Note: Depending on the needs of your runtime environment, you may want to select a different Software Group. For example: Entire Distribution Plus Original Equipment Manufacturer (OEM) Support is 2.4 GB in size Entire Distribution Without OEM Support is 2.3 GB in size Developer System Support is 1.9 GB in size End User System Support is 1.6 GB 9. When the Select Disks window appears, accept the default, and then click Next. 10.When the File Systems and Disk Layout window appears, click Modify. 11.When the Customize Disks window appears, reallocate the disk space. By default, the file systems will be assigned a minimum value required by Solaris and all remaining disk space is allocated to /export/home. Important: Refer to 18.2.3, “File system planning” on page 681 for disk space needs by applications installed on each node of the three-tier runtime. In our test environment, each system had a 17 GB hard disk. For our example, we created the following file systems with the sizes listed in Table 21-10. The file systems in Table 21-10 will accommodate any of the nodes in our three-tier runtime. You will want to carefully plan for the disk space needed for your configuration. Appendix B. Solaris tips 975 Table 21-10 Sample file system sizes for Solaris installation File system Usage Example / Root 1632 MB swap 1-2 times the size of RAM 1024 MB overlap Solaris calculated, entire size of disk space by default (17269) 17269 MB (default) /opt * WebSphere Application Server * WebSphere Commerce * WebSphere Commerce instance * WebSphere Commerce stores * WebSphere Commerce Payments * WebSphere Commerce Payments instance 6144 MB /usr * iPlanet Web Server 2048 MB /export/home User home directories 6412 MB (remainder) Capacity: 17269 MB Allocated:17269 MB Note: Oracle9i alone requires 2.2 GB of disk space. 12.When the File System and Disk Layout window appears again, click Next. 13.When the Profile window appears, review the selections and then click Install Now. The Installing Solaris Software - Progress window appears. This process takes approximately one hour with the options we selected. When prompted, switch the CD in the CD-ROM drive to the Solaris CD you are asked for by the install program. There are several CDs that you will be asked for. 14.If the Specify Media for Solaris 8 Languages window appears, select CD, insert the Solaris 8 Languages CD ,and then click Next. Alternatively, click Skip. Note: We clicked Skip to continue without additional language support. 15.When the After Solaris software is installed message window appears, click Reboot Now. 976 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 16.The first time you log on to the Solaris 8 system, it will ask you if you would like the CDE to be the default desktop. In our example, we selected CDE. The Solaris 8 interactive install is now complete. Solaris 8 post-install configuration This section provides instructions for the basic configuration steps after installation. Default router During the installation, most of the TCP/IP network configuration options are entered, with the exception of one. Without configuring the default router, the system will not be able to communicate beyond the subnet gateway. To configure the default router, complete the following steps: 1. Start a terminal console session. 2. Create a default router file in the /etc directory: a. Change to the /etc directory. # cd /etc b. Create a file called defaultrouter using vi or any other text editor: # vi defaultrouter c. Add the gateway IP address for the subnet (for example 9.24.104.1). d. Save the file. 3. Restart the system or restart TCP/IP. # shutdown -i6 -g0 -y Stopping SNMP The SNMP service is a potential security exposure. To stop SNMP, do the following: 1. Enter the following from a console to see if SNMP is running: # ps -ef | grep snmp 2. To stop SNMP from running from a console, enter the following: # /etc/rc3.d/S76snmpdx stop 3. To permanently stop SNMP for the next reboot, do the following: # mv /etc/rc3.d/S76snmpdx /etc/rc3.d/no_S76snmpdx Appendix B. Solaris tips 977 4. Restart the system. # shutdown -i6 -g0 -y Solaris 8 maintenance update installation If your Solaris 8 Operating Environment (SPARC platform edition) software is not at least at maintenance update 7 (MU7), then you need to complete the following steps to download and install the latest Solaris 8 maintenance update. 1. Start a Solaris Console window and enter the following commands: # cd /opt # mkdir SolarisMU 2. Enter the following URL in a Web browser to download the latest Solaris maintenance update: http://access1.sun.com/Products/solaris/mu Enter a registered user name and password to access the download area. Alternatively, it can be obtained from: http://docs.sun.com/db/coll/472.4 At the time of writing this book, MU7 (Solaris 8 02/02) was available for download at a size of approximately 190 MB, downloadable in either one complete or 10 smaller zipped archives. Note: We performed our tests with maintenance update 7 (MU7). 3. Go to the Solaris 8 Maintenance Update download page. Make sure the directory to download has enough free space to accommodate and unzip the MU files, approximately 686 MB. Download single or multiple zip files to /opt/SolarisMU. Note: Refer to the Maintenance Update Installation Guide provided with the maintenance update for detailed installation instructions. 4. The installation of MU7 requires patches 108987-08 and 112396-01 to be installed on the system. Patches 10987-08 and 112396-01 are contained in the patches 108987-13 and 112396-01, respectively. So we downloaded the patches from: http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fsalert%2F41225&zone_32=MU7 &wholewords=on 978 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 5. We unzipped the patch files and then applied the patches in the following sequence: patchadd /112396-02 patchadd /108987-13 The sequence is important as the patch 108987-13 depends on the existence of patch 112396-02. 6. From the Solaris Console window command prompt, we unzipped the download file and then entered the following: # ./install_mu Note: Patch installation status is saved to the /var/sadm/install_data/Maintenance_Update_log.Solaris_8MU7. file. During the installation, some of the patches may fail to apply, either because an equivalent or newer patch is already present, or because one or more Solaris components were not initially installed. Errors of the following type may be safely ignored: Patches are already applied or One or more patch packages included in are not installed on this system 7. Restart the system for all the maintenance update patches to take effect: # shutdown -i6 -g0 -y 8. Enter the following command to identify the version of your Solaris maintenance update: # cat /etc/release You should see the following message: Solaris 8 Maintenance update 7 applied 9. Enter the following command to identify the patches which the maintenance update has applied to your system: # showrev -p Appendix B. Solaris tips 979 Solaris 8 recommended patches Complete the following steps to download and install the Solaris 8 recommended patches, which are required by WebSphere Commerce V5.5 for Solaris: 1. Start a Solaris Console window and enter the following commands: # cd /opt # mkdir SolarisPatch 2. Enter the following URL in a Web browser to download the Solaris patches: http://www.sun.com/bigadmin/patches/index.html 3. Click Solaris 8 (in the recommended tab) for the recommended patches to download to /opt/SolarisPatch. At the time of writing this redbook, the date for the latest recommended patches available for download was Aug/27/02 and the size was approximately 72 MB. Note: Make sure you have enough disk space available on the target file system for the download file. 4. From the Solaris Console window command prompt, type the following commands to unzip the 8_Recommended.zip patch file: # cd /opt/SolarisPatch # unzip 8_Recommended.zip This creates a directory called 8_Recommended. 5. To install the patches, type the following commands: # cd 8_Recommended # ./install_cluster 6. When prompted with the message “Are you ready to continue with install (y/n)”, type y for Yes, and then press Enter. 980 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: Patch installation status is saved to the /var/sadm/install_data/Solaris_8_Recommended_log file. During the installation, some of the patches may fail to apply, either because an equivalent or newer patch is already present, or because one or more Solaris components were not initially installed. Errors of the following type may be safely ignored: Patches are already applied or One or more patch packages included in are not installed on this system or Installation of failed. Return code 2. Installation of failed. Return code 8. 7. Reboot the machine for all patches to take effect: # shutdown -i6 -g0 -y Disk space used by Solaris After the installation of Solaris 8, maintenance updates, and patches, we checked to see how much free space was available for each file system mount point, as follows: # df -k With the installation options we selected and the file systems sizes we entered, we received the following output: Filesystem kbytes used avail capacity Mounted on /dev/dsk/c0t0d0s0 1621767 1256525 316589 80% / /dev/dsk/c0t0d0s6 2056211 732268 1262257 37% /usr /proc 0 0 0 0% /proc fd 0 0 0 0% /dev/fd mnttab 0 0 0 0% /etc/mnttab swap 1397400 16 1397384 1% /var/run swap 1397704 320 1397384 1% /tmp /dev/dsk/c0t0d0s5 6196234 233699 5900573 4% /opt /dev/dsk/c0t0d0s7 6465570 9 6400906 1% /export/home Appendix B. Solaris tips 981 Common Solaris tasks and commands This section provides examples of some common commands and tasks performed using Solaris 8. Reboot 1. Start the Solaris Console window. 2. Type the following command to shut down and reboot: # shutdown -i6 -g0 -y Tail Tail is used to view a log file that is being written to: # tail -f mkdir (create directory) To create directories, use mkdir as follows: # mkdir test The following command will create the t1 within the test directory without having to change to that directory: # mkdir -p /test/t1 ps - process list The ps utility is used to display the process list of running processes with the ID or PID. Example usage: # ps -ef | awk ‘{print $1 “\t” $2 “\t” $8}’ | more # ps -ef | grep java In Solaris, there is a shorthand version, combining ps and grep: # pgrep java prtdiag - system diagnostic information /usr/platform/sun4u/sbin/prtdiag -v id This command displays the UID and GID of a user. # id 982 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide ulimit This command gets and sets limitations on the system resources available to the current shell and its descendents. In a Korn shell, use the -a option to list all of the current resource limits: .# ulimit -a Tar This command is used to package files into a tar file or extract files from a tar file. Package: # tar -cvf /opt/filename.tar /app Extract: # tar -xvf filename.tar Unzipping a .Z compressed file To unzip a .Z compressed file, enter the following: # zcat .tar.Z | tar -xvf - Unzipping a gzip compressed file To unzip a gzip compressed file, enter the following: # gzcat .tar.gz | tar -xvf - Verify DNS setup To verify that DNS is set up properly, do the following: 1. Go to the directory /etc. 2. Check if there is a file with the name of resolv.conf. 3. If file exists make sure it has the correct entry. For example, we had the following lines in our resolv.conf: domain itso.ral.ibm.com nameserver 9.24.106.15 4. If file does not exists, create a file with the name specified in step 2 with content similar to the sample in step 3. Verify net masks setup To verify that net masks are set up properly, do the following: 1. Go to the directory /etc. 2. Check the content of the file net masks. Appendix B. Solaris tips 983 3. Verify the entry. For example, we had following lines in our net masks: 9.0.0.0 255.255.254.0 4. If a file does not exist, create a file with the name specified in step 2 with content similar to the sample in step 3. FTP server setup This procedure should only be used on test systems, since FTP servers, especially when using root, pose a security risk. To enable the FTP server on Solaris 8 server, do the following: 1. Ensure the FTP service is not commented out in the /etc/inet/inetd.conf file. 2. Ensure that the user you would like to FTP to the server is not in the /etc/ftpusers file. For example, if you want to FTP to this server with user root, comment out the root user in the /etc/ftpusers file with the # character. Telnet to server as root This procedure should only be used on test systems, since telnet servers (especially when using root) pose a security risk. To enable the telnet login with user root on a Solaris 8 server, do the following: 1. Open the /etc/default/login file with a text editor. 2. Comment out CONSOLE=/dev/console to allow the root user to log in from telnet. NFS share/mount This procedure should only be used on development and test systems, since NFS servers can pose a security risk. To enable the NFS server on Solaris 8 server, do the following: 1. You can share the directory by using the following command: > share -F (fstype) -o (options) -d (description) (pathname) For example: > share -F nfs -o ro -d "Big directory on solaris" /bigdirectory In this example, bigdirectory is shared as read only. You can use rw in place of ro in the options to make it read and write. 2. If you want to make this share permanent, you will need to add the share line in /etc/dfs/dfstab. 3. Then, you will need to start the NFS Server Daemon by running the following command: 984 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide /etc/init.d/nfs.server start 4. The NFS server will not start until you add an entry in /etc/dfs/dfstab. 5. You can mount the share on a remote system using the mount command. > mount -F nfs (options) (server):(filesystem) (mount_point) For example: > mount -F nfs -o rw solaris:bigdirectory /mount_from_solaris 6. To make the file system mount automatically, you will need to add the entry in /etc/vfstab file. pkginfo The pkginfo command is used to list information on installed packages: # pkginfo wcbase Lists wcbase if it is on the system. # pkginfo -i Lists packages that have been successfully installed. # pkginfo -p Lists packages which are only partially installed. # pkginfo -l wcbase Lists details of a package. pkgchk The pkgchk command is used to check the integrity of an installed package: # pkgchk wcbase If no errors are listed, then the package has been successfully installed and unchanged/undamaged since the initial install. Note: The wcpostinstall.sh script will have modified the attributes (that is, file permissions) of almost all of the WebSphere Commerce files. To verify file contents only, use the -c switch: # pkgchk -c wcbase # pkgchk -v wcbase Lists the files in the package. # pkgchk -l wcbase Lists details of the files in the package. Solaris Product Registry utility ProdReg is an utility that allows you to view, add or delete software installed on Solaris 8. The utility is located in the folder /usr/bin. You can start the utility window as root by issuing the following command: #/usr/bin/prodreg Appendix B. Solaris tips 985 Where to find information about Solaris The following are sources for more information on Solaris: For general info, patches, documentation, downloads and discussions: http://www.sun.com/bigadmin/ Solaris 8 documentation found at: http://docs.sun.com/db/prod/solaris.8#hic Collection of installation information on Solaris 8 found at: http://docs.sun.com/db/prod/2567#hic Collection of systems administrator information on Solaris 8 found at: http://docs.sun.com/db/prod/2661#hic Solaris patches: http://www.sun.com/bigadmin/patches/index.html Mark G. Sobell, A Practical Guide to Solaris, Addison Wesley, 1999, ISBN 020189548X 986 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide C Appendix C. DB2 tips This appendix provides useful tips for IBM DB2 Universal Database V8.1, Enterprise Server Edition. The following topics are discussed in this appendix: DB2 backup and restore DB2 tasks using smitty on AIX DB2 commands The default database location for DB2 is the instance owner’s home directory. In practice, many users will create a file system to store their databases. Using a file system with access permissions provides the instance owner with control and the ability to set the storage size of the file system. In the working example, we create a logical volume and file system to store the remote databases for the WebSphere Application Server and the WebSphere Commerce Server. © Copyright IBM Corp. 2003. All rights reserved. 987 DB2 backup and restore This section describes DB2 backup and restore. Back up a DB2 database To back up a DB2 database, do the following: 1. Stop the applications that are connected to the DB2 database. 2. Disconnect all applications connected to the database: db2 force applications all db2 terminate 3. Create a database backup directory (for example, c:\ibm\dbbackup). 4. Open a DB2 command window. 5. Back up the database by entering command: db2 backup db to For example: db2 backup db wc1db to c:\ibm\dbbackup Back up DB2 database via Control Center The following describes how to perform the backup using the DB2 Control Center: 1. Select Start -> Programs -> IBM DB2 -> General Administration Tools -> Control Center. 2. Expand the following path of nodes in the left-hand pane: System -> node name -> Instances -> DB2 -> Databases. 3. A list of databases will appear under the Databases node. Highlight the WebSphere Commerce Studio database name. 4. Select Selected -> Backup. 5. The Backup wizard opens. Click Next. 6. Ensure that File System is selected as Media Type. Click Add. 7. The Path Browser is displayed. Select the directory under which you wish to store the database backup and click OK. Click Next. 8. Ensure that the backup options are set as follows (see Figure C-1 on page 989): – Full Backup. – Offline: Users cannot access the database during the backup. 988 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide – Quiesce must be deselected. Figure C-1 Backup options 9. Click Finish. The Backup wizard will close and the Progress window will open. 10.After a few minutes a window with the completion status of the backup will open. The window should look similar to that of Figure C-2. Figure C-2 Successful backup of database Appendix C. DB2 tips 989 Restore a DB2 database As needed, to restore a DB2 database, do the following: 1. Stop the applications that are connected to the DB2 database. 2. If a database exists on the DB2 server that is no longer needed, drop the database as follows from a DB2 command window: db2 drop db 3. Copy the backup of the database to the DB2 server. 4. Prior to performing the DB2 restore, we recommend creating the new database with the desired codeset and territory. For example: db2 create db using codeset UTF-8 territory US Note: If the the codeset and territory are not specified, you cannot be sure that the DB2 create database command will create the database with the desired locale information. Information on the desired codeset and territory can be found in the DB2 command reference. 5. To restore the database, enter the following from a DB2 command window: db2 restore db from For example: db2 restore db wc1db from c:\ibm\dbbackup DB2 tasks using smitty on AIX This section includes various DB2 tasks using the smitty interface. Create a logical volume This procedure provides instructions for creating a logical volume on AIX: 1. Log in to AIX as root and start a terminal session. 2. Start smitty by typing the following: # smitty storage 3. Select Logical Volume Manager and press Enter. 4. Select Logical Volumes and press Enter. 5. Select Add a Logical Volume and press Enter. 990 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 6. Select VOLUME Group name and press F4 for a listing. – Select rootvg and press Enter. 7. When a Logical Volume window appears, enter the following fields: – Logical Volume NAME: (for example, dblv1) – Number of LOGICAL PARTITIONS: 1 – Press Enter and wait until the status changes to Command: OK. 8. Press the F10 key to return to the system prompt. Create an AIX journal file system This procedure provides instructions for creating a journal file system on a previously defined logical volume on AIX. 1. Start smitty by typing the following: # smitty storage 2. Select File Systems. 3. Select Add / Change / Show / Delete File Systems. 4. Select Journal File Systems. 5. Select Add a Journal File System on a Previously Defined Logical Volume. 6. Select Add a Standard Journal File System. 7. When the Add a Standard Journal File System window appears, enter the following: – LOGICAL VOLUME name: press F4 for listing, select dblv1. – MOUNT POINT: Select /home/db2inst1. – Mount AUTOMATICALLY at system restart: Choose yes. Tip: Press the Tab key to toggle yes/no. – Press Enter and wait until the status changes to Command: OK. 8. Press the F10 key to return to the system prompt. Appendix C. DB2 tips 991 Allocate storage for a file system If you have not restarted your system, it is necessary to mount the file system prior to allocate storage to the newly created file system. 1. Mount file system: # mount /dev/dblv1 /home/db2inst1 2. Allocate storage This step allocates file system storage space to the journal file system. By default, AIX allocates storage in 512-byte blocks. In this example, we create a file system that is 600,000 blocks or 300 MB. As the WebSphere Commerce database and the WebSphere Commerce Payments database grow, this file system may need to be increased: # chfs -a size=’600000’ /home/db2inst1 3. Verify file system free space: # df Create users and groups To create users and groups on AIX, do the following: 1. Log in to AIX as root and start a terminal session. 2. Create group db2iadm1 by typing the following: # mkgroup db2iadm1 3. Create user db2inst1 by typing the following: # mkuser pgrp=db2iadm1 db2inst1 4. Set the default password for user db2inst1. When creating a user, the password is set to * (for invalid). It is necessary to set the password. To change the db2inst1 password, type the following: # passwd db2inst1 Changing password for “db2inst1” db2inst1’s New password: Enter the new password again: 5. Change db2inst1 initial logon password. During the initial user logon, the user will be prompted to change a password. To change the initial logon password, type the following: # login db2inst1 db2inst1’s Password: db2inst1’s New password: Enter the new password again: 992 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 6. Change ownership of the /home/db2inst1 file system to user db2inst1 by typing the following: # chown -fR db2inst1:db2iadm1 /home/db2inst1 7. Verify file system ownership (db2inst1:db2iadm1): # ls -la /home/db2inst1 DB2 commands This section includes some common DB2 commands. Create a volume group To create a volume group, enter the following: # mkvg -f -y ’datavg’ -s’16’ hdisk3 Create a logical volume To create a logical volume, enter the following: # mklv -y ’db2lv’ datavg 1 Create a journal file system To create a journal file system on a previously defined logical volume, enter the following: # crfs -v jfs -d ’db2lv’ -m ’/db2data’ -A yes Allocate space to a file system To allocate space to a file system, enter the following: # chfs -a size=’2000000’ /db2data Mount a file system To mount a file system, enter the following: # mount /db2data Appendix C. DB2 tips 993 Create a database To create a database, enter the following: # su - db2inst2 $ db2 create db test List databases To list databases, enter the following: # su - db2inst2 $ db2 list db directory Drop a database To drop (delete) a database, enter the following: # su - db2inst2 $ db2 drop db test Catalog a TCP/IP node To catalog a TCP/IP node, enter the following: Syntax: $ db2 catalog tcpip node remote server Example: $ db2 catalog tcpip node db2aix1 remote db2aix1.itso.ral.ibm.com server db2cdb2inst2 Note: If you choose to specify the actual DB2 service name instead of the port number, the service name must be listed in the local /etc/services file for lookup purposes. Attach to a remote node To attach a client to a remote server, enter the following: Syntax: $ db2 attach to user using Where and are those of the DB2 instance owner. Example: $ db2 attach to db2aix1 user db2inst2 using pass2word 994 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Catalog a remote database To catalog a remote database, enter the following: Syntax: $ db2 catalog db at node Where is the database on the remote DB2 server machine. Example: $ db2 catalog db was40 at node db2aix1 Connect to a remote database To connect to a remote database, enter the following: Syntax: $ db2 connect to user using Example: $ db2 connect to was40 user db2inst2 using pass2word Disconnect from a remote database To disconnect from a remote database, enter the following: $ db2 connect reset Appendix C. DB2 tips 995 996 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide D Appendix D. Oracle tips This appendix includes basic Oracle9i Enterprise Edition tasks and commands as well as useful sources of Oracle9i information. This appendix is organized into the following sections: Oracle9i commands and tasks Testing Oracle connectivity using JDBCTEST Oracle backup and restore Important Oracle files Verifying user creation Cleaning database after deleting an instance Where to find more information © Copyright IBM Corp. 2003. All rights reserved. 997 Oracle9i commands and tasks This section includes common commands and tasks used within an Oracle9i environment. Oracle9i server This section provides instructions for starting and stopping an Oracle9i server. Note: The svrmgrl command is no longer available in Oracle9i. Database server startup and shutdown should be done using sqlplus. Starting the Oracle9i server To start the Oracle9i server, complete the following steps: 1. Log on to the Oracle9i database server as the oracle user: # su - oracle 2. On the Oracle9i server, type the following commands: $ sqlplus Enter user-name: sys as sysdba Enter password: SQL> startup; SQL> exit Stopping the Oracle9i server To stop the Oracle9i server, complete the following steps: 1. Log on to the Oracle9i database server as the oracle user: # su - oracle 2. On the Oracle9i server, type the following commands: $ sqlplus Enter user-name: sys as sysdba Enter password: SQL> shutdown; SQL> exit Note: Only if problems are encountered should you try using shutdown immediate. In emergencies, shutdown abort may be necessary. 998 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Oracle9i listener This section includes information on the Oracle9i listener. Starting the Oracle9i listener To start the Oracle9i listener on the database server, complete the following steps: 1. Log on to the Oracle9i database server as the oracle user: # su - oracle 2. On the Oracle9i server, type the following command: $ lsnrctl start For example: $ lsnrctl start LISTENER Note: All listeners will be started if the listener name is omitted. Stopping the Oracle9i listener To stop the Oracle9i listener on the database server, complete the following steps: 1. Log on to the Oracle9i database server as the oracle user: # su - oracle 2. On the Oracle9i server, type the following command: $ lsnrctl stop For example: $ lsnrctl stop LISTENER Note: All listeners will be stopped if the listener name is omitted. Checking the status of the Oracle9i listener To check the status of the Oracle9i listener on the database server, complete the following steps: 1. Log on to the Oracle9i database server as the oracle user: # su - oracle 2. On the Oracle9i server, type the following command: $ lsnrctl status For example: $ lsnrctl status LISTENER Appendix D. Oracle tips 999 Note: All listeners’ status will be displayed if the listener name is omitted. Checking the Oracle9i service To check the availability of the Oracle9i service on the database server, complete the following steps: 1. Log on to the Oracle9i database server as the oracle user: # su - oracle 2. On the Oracle9i server, type the following command: $ tnsping For example: $ tnsping o920 Listing the status of the Oracle9i connection To check the status of the Oracle9i connection on the database server, complete the following steps: 1. Log on to the Oracle9i database server as the oracle user: # su - oracle 2. Start sqlplus: $ sqlplus system/@ For example: $ sqlplus system/manager@o920 3. On the Oracle9i server, type the following command: SQL> select * from v$session; Oracle utilities This section describes some Oracle utilities. Launching the Oracle Net Manager Net Manager enables services and their applications to reside on different computers and communicate as peer applications. The main function of Net Manager is to establish network sessions between a Oracle9i client and server. The Net Manager is a utility used to create or modify network configuration settings. 1000 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide To start the Oracle Net Manager, complete the following steps: 1. Log on to the Oracle9i database server as the oracle user: # su - oracle 2. On the Oracle9i server, type the following command to start Oracle Net Manager: $ netmgr Launching the Oracle Net Configuration Assistant To launch the Oracle Net Configuration Assistant, complete the following steps: 1. Log on to the Oracle9i database server as the oracle user: # su - oracle 2. On the Oracle9i server, type the following command to start the Oracle Net Configuration Assistant: $ netca Launching the Database Configuration Assistant To launch the Database Configuration Assistant, complete the following steps: 1. Log on to the Oracle9i database server as the oracle user: # su - oracle 2. On the Oracle9i server, type the following command to start the Database Configuration Assistant: $ dbca & Testing Oracle connectivity using JDBCTEST The JDBCTest.java tool is made available to IBM customers and support personnel to assist in debugging setup and install problems with JDBC. The tool is designed to work with either DB2, Oracle, Sybase, Informix®, Cloudscape™ or SQLServer JDBC drivers. The JDBCTest code can be downloaded from: ftp://ftp.software.ibm.com/software/websphere/info/tools/jdbctest The FTP site also provides a quick example of how to use this (jsread2.html). Appendix D. Oracle tips 1001 Oracle backup and restore It is good practice to back up your database periodically or before any major changes. The Oracle utilities exp and imp under the $ORACLE_HOME/bin directory are used for this purpose. To back up a table space, log in as the instance owner oracle in a Solaris console window: # su - oracle $ exp system/@ owner= file= log= Where: is the name of the Oracle network service, for example, o920. is the name of the table space that you want to back up, for example, mqm. is the dump file to which the database backup is made. To restore a table space, get the backup file file_name.dmp and import it into the Oracle database: # su - oracle $ imp system/@o920 fromuser= touser= file= log= The fromuser and touser are usually the same. Important Oracle files Oracle9i uses a number of files to store diagnostic and configuration information. By default, these are found on the file system within the directory specified by the $ORACLE_HOME environment variable. Log files and trace files To assist troubleshooting, a WebSphere Commerce administrator may need to review the Oracle log files or trace files. By default, they are saved at the following locations: For background processes: $ORACLE_BASE/admin//bdump For user related information: $ORACLE_BASE/admin//udump If the database crashes, the information will be saved under $ORACLE_BASE/admin//cdump 1002 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Your Oracle DBA may choose different locations for the log files and trace files. Please check $ORACLE_HOME/dbs/spfile.ora for details. A good starting point to review log files and trace files is the alert log, which can be found at $ORACLE_BASE/admin//bdump/alert_.log. If you are an Oracle DBA, you may want to purge log files and trace files periodically to save space. The size of files under the directories above can grow rapidly. Oracle configuration files The following files are important configuration files of the Oracle9i instance: $ORACLE_HOME/dbs/spfile.ora is a soft link to $ORACLE_BASE/admin//pfile/init.ora, which specifies initialization parameters of an Oracle9i instance. $ORACLE_HOME/network/admin/listener.ora is the configuration file for the Oracle listeners. $ORACLE_HOME/network/admin/sqlnet.ora is the network configuration file. $ORACLE_HOME/network/admin/tnsnames.ora is the configuration file for TNS. Verifying user creation To verify that the users have been corrected properly, log on to sqlplus with each of the user IDs as follows: 1. Log in as user oracle: # su - oracle 2. Start sqlplus using payman: $ sqlplus payman/payman1@o920 SQL> quit 3. Start sqlplus using wcs: $ sqlplus wcs/wcs1@o920 SQL> quit Note: Of course, your password for each user should be different from the user ID for proper security policy. Appendix D. Oracle tips 1003 Changing the user password After database creation and verification, we recommend changing the user password as follows for SID o920: 1. Log in as user oracle. # su - oracle 2. Start SQL*Plus by entering the following: $ sqlplus 3. Connect with the user name and password that you want to change: user-name: /@ For example: Enter user-name: system/manager@o920 4. Change the password: SQL> ALTER USER USERNAME IDENTIFIED BY PASSWORD; For example: SQL> ALTER USER system IDENTIFIED BY ; Cleaning database after deleting an instance After deleting a Commerce instance, you must delete the user and the table spaces. The following SQL statement deletes the user and all the objects owned by it. For example, it deletes tables, table spaces, and the user. SQL> DELETE USER cascade; Where to find more information The following lists where to find more information on Oracle9i: General information can be found on the Oracle Web site at: http://www.oracle.com Oracle9i Enterprise Edition documentation can be found at: http://otn.oracle.com/documentation/content.html 1004 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide E Appendix E. WebSphere Commerce Studio implementation The original release of IBM WebSphere Commerce Studio V5.5, Business Developers Edition and Professional Developers Edition includes IBM WebSphere Studio Application Developer V5.0. This appendix includes instructions for installing WebSphere Commerce Studio V5.5 with fix packs such as WebSphere Studio Application Developer V5.0.1, WebSphere Test Environment V5.0.1, DB2 UDB V8.1 Fix Pack 3, and WebSphere Commerce Studio Toolkit V5.5.0.2 Fix Pack. In our example, we used IBM WebSphere Studio Application Developer V5.0.1 for the following reasons: IBM WebSphere Studio Application Developer V5.0.1 is a prerequisite to IBM WebSphere Commerce Studio Toolkit V5.5.0.2 Fix Pack. We installed IBM WebSphere Application Server V5 Fix Pack 1 (V5.0.1) on the runtime environment to address EJB deployment issues with DB2 UDB V8.1 metadata. As part of the IBM WebSphere Studio Application Developer V5.0.1 installation, we will upgrade to WebSphere Test Environment V5.0.1. Note: For more information on WebSphere Commerce Studio installation, refer to the Installation Guide, IBM WebSphere Commerce Studio V5.5 and the Update Guide for WebSphere Commerce Studio Toolkit V5.5.0.2 product guides. © Copyright IBM Corp. 2003. All rights reserved. 1005 At the time of writing, IBM WebSphere Application Server V5 Fix Pack 2 (V5.0.2) had been released. The corresponding development tooling for IBM WebSphere Application Server V5.0.2 is IBM WebSphere Studio Application Developer V5.1, which includes a WebSphere Test Environment V5.0.2. IBM WebSphere Studio Application Developer V5.1 is sold separately from IBM WebSphere Commerce Studio V5.5. The prerequisites section of the Update Guide for WebSphere Commerce Studio Toolkit V5.5.0.2 product guide mentions support for WebSphere Studio Application Developer V5.1. Refer to the WebSphere Commerce support page for additional information. We have not tested this solution. The support of WebSphere Studio Application Developer V5.1 by WebSphere Commerce Studio provides developers with the following benefits: WebSphere Test Environment V5.0.2 support included in WebSphere Studio Application Developer V5.1, which includes many fixes and new functionality. The ability for hot swap development of commands and EJBs within the WebSphere Test Environment. Note: The IBM WebSphere Commerce V5.5, Express Edition includes IBM WebSphere Application Server V5.0.2, and the IBM WebSphere Commerce Studio, Express Developer Edition includes IBM WebSphere Studio Application Developer V5.1 (WebSphere Test Environment V5.0.2), and WebSphere Commerce workspace and plug-ins. WebSphere Commerce Studio installation This section describes the steps we performed to install WebSphere Commerce Studio V5.5 for the ITSO development environment. The procedures outlined include fix packs for WebSphere Studio Application Developer, DB2, and WebSphere Commerce Studio. The WebSphere Commerce Studio installation is organized as follows: 1006 Windows 2000 installation Install WebSphere Commerce Studio V5.5 Install WebSphere Studio Application Developer V5.0.1 PTF Install WebSphere Test Environment V5.0.1 Install WebSphere Studio Application Developer V5.0.1 Interim Fix 3 Install DB2 UDB V8.1 Fix Pack 3 Install WebSphere Commerce Studio Toolkit V5.5.0.2 Fix Pack WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Windows 2000 installation This section highlights the key issues addressed when installing Windows 2000 Server, such as using Windows 2000 Service Pack level 3 or higher, and user rights assigned to the administrator user needed later for DB2. Windows 2000 Service Pack 4 In our example, we installed Windows 2000 Service Pack 4. Windows 2000 service levels We installed the latest Windows 2000 service level critical updates on top of Service Pack 4. Create admin user and assign user rights To assign user rights to the administrator ID used by the WebSphere Commerce DB2 owner during instance creation, do the following: 1. Log on to Windows as an administrator. 2. Create a user ID and add the user to the administrators group (for example, we created a user called admin). Alternatively, use an existing administrator user such as your development logon ID. Note: This user can be your development user ID that you log on to the Windows system or db2admin. For our example, we created a user called admin that we assigned these user rights and that was also added to the administrator group. Within our procedure, replace your administrator user ID where we have entered admin as a sample user ID. 3. Click Start -> Settings -> Control Panel -> Administrative Tools -> Local Security Policy. 4. From the Local Security Settings window, select and expand Local Policies -> User Rights Assignment. 5. Ensure the administrator user ID (for example, admin) has user right assignments for the following Windows Local Security Policies needed for DB2: – – – – – Act as part of the operating Create a token object Increase quotas Log on as a service Replace a process level token Appendix E. WebSphere Commerce Studio implementation 1007 6. Log on as the administrator user ID created and rights assigned needed for DB2. Verify network configuration Prior to installing WebSphere Commerce and supporting software components, it is important that you verify that your network is configured properly. We recommend that you use a static TCP/IP address and verify that the host name can be resolved with the name server. Install WebSphere Commerce Studio V5.5 This section includes the high-level steps for installing WebSphere Commerce Studio. The WebSphere Commerce Studio installer will install IBM DB2 UDB V8.1 and IBM WebSphere Studio Application Developer V5.0 as part of the installation. To install WebSphere Commerce Studio, do the following: 1. Decide whether to use a remote DB2 database. If yes, it must be installed on a separate windows system before installing WebSphere Commerce Studio. In our example, we installed the DB2 UDB server locally. 2. Insert the WebSphere Commerce Studio CD and run setup. You may be prompted to change CDs during the installation depending on your selections. 3. We accepted the default options unless specified. 4. When prompted for the WebSphere Commerce Studio Instance Information, we entered the following and then clicked Next: – – – – – WebSphere Commerce Studio instance name: wc1dev Merchant Key: WebSphere Commerce Payments instance password: Site Administrator ID: wcadmin Site Administrator password: 5. When prompted for the WebSphere Commerce Studio database information, we entered the following and then clicked Next: – WebSphere Commerce Studio database name: wc1dev – Development database type: Select IBM Universal Database – Check Create WebSphere Commerce Studio database 6. When prompted for additional WebSphere Commerce Studio database information, we entered the following and then clicked Next: – Database administrator ID: admin 1008 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: The admin user is a Windows user with the proper DB2 user assignments: Act as part of the operating Create a token object Increase quotas Log on as a service Replace a process level token – Database administrator password: – Database user ID: admin In our example, the DB2 instance owner and schema owner (user) are the same user (admin). – Database user password: Note: If you had selected the remote database option, you would need to specify the DB2 server host name and port. In addition, you would need to install the DB2 Database Administration Client. 7. When prompted to Choose Destination of software components, we entered the following shortened installation paths and then clicked Next: – – – – WebSphere Commerce Studio: c:\ibm\wcstudio (740 MB) DB2: c:\ibm\sqllib (500 MB) WebSphere Studio Application Developer: c:\ibm\wsad (870 MB) WebSphere Commerce Workspace: c:\ibm\workspace (500 MB) 8. You will be prompted for CDs. The WebSphere Commerce Studio installer will do the following: – – – – – Install WebSphere Studio Application Developer Install DB2 Server and DB2 Administration Client Create the WebSphere Commerce Studio instance Create the WebSphere Commerce Payments instance Import the WebSphere Commerce workspace into WebSphere Studio Application Developer – Install WebSphere Application Server Fixes required by the WebSphere Test Environment 9. After the installation is complete, restart your system. 10.Verify the WebSphere Commerce Studio installation. For details, refer to the Installation Guide, IBM WebSphere Commerce Studio V5.5 product guide. Appendix E. WebSphere Commerce Studio implementation 1009 Install WebSphere Studio Application Developer V5.0.1 PTF Details on installing the IBM WebSphere Studio Application Developer V5.0.1 PTF can be found at: http://www.ibm.com/support/docview.wss?rs=457&context=SSBRLP&q=&uid=swg2400 4660&loc=en_US&cs=utf-8&lang=en Note: The IBM WebSphere Studio Application Developer V5.0.1 PTF does not update the WebSphere Test Environment. We will update the WebSphere Test Environment in the next section. The high-level steps to install IBM WebSphere Studio Application Developer V5.0.1 PTF are as follows: 1. Log on to your system with a user ID that has Administrator authority (you will need write access to the install location). 2. Start IBM WebSphere Studio Application Developer V5.0 by selecting Start -> Programs -> IBM WebSphere Studio -> Application Developer 5.0. 3. Search for the PTF on the IBM update site by selecting Help -> Software Updates -> New Updates from the WebSphere Studio Application Developer workspace as seen in Figure E-1 on page 1011. Note: The Update Manager will find the available updates online from the IBM support site. If you are not able to get this to work for various reasons, you can download the PTF zip file directly and install it locally as described in the PTF installation instructions. 1010 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Figure E-1 WebSphere Studio Application Developer available updates 4. The WebSphere Studio Application Developer V5.0.1 PTF contains two updates: – WebSphere Studio Application Developer Product (Windows/Linux) 5.0.1 Updates to product components. – WebSphere Studio Application Developer (Windows/Linux) 5.0.1 Updates to base components. Ensure both updates are checked as seen in Figure E-1 and click Next. 5. Review the license agreement. If you agree to the conditions, select I accept the terms in the license agreements, and then click Finish. 6. If you are warned that you are about to install an unsigned feature, click Install to continue. This warning will not cause problems during installation. 7. During the install, you will be asked for confirmation during the installation of the second part of the PTF. Click Install to continue. 8. When the installation is complete you will be prompted with the message, “You will need to restart the workbench for the changes to take effect. Appendix E. WebSphere Commerce Studio implementation 1011 Would you like to restart now?” Click Yes to complete the installation and restart. 9. To verify that the WebSphere Studio Application Developer V5.0.1 PTF installation was successful, do the following: a. Switch to the Install/Update perspective by selecting Help -> Software Updates -> Update Manager. b. Select the Installation Configurations view. Select and expand Current Configurations. Under each file: entry you should see the PTF 5.0.1 features listed. Verify that the two WebSphere Studio Application Developer features are at Version 5.0.1 as seen in Figure E-2. Figure E-2 Verify PTF features are installed successfully The IBM WebSphere Studio Application Developer V5.0.1 PTF installation is now complete. Install WebSphere Test Environment V5.0.1 This section describes how to install the WebSphere Test Environment V5.0.1 for IBM WebSphere Studio Application Developer V5.0.1. WebSphere Test Environment V5.0.1 is the corresponding runtime in the development environment for the WebSphere Application Server V5.0.1 (Fix Pack 1) runtime. Details on installing the WebSphere Test Environment V5.0.1 can be found at: http://www.ibm.com/support/docview.wss?rs=457&context=SSBRLP&context=SS2MD7 &q=websphere+test+environment&uid=swg21109863&loc=en_US&cs=utf-8&lang=en+en To install the WebSphere Test Environment V5.0.1 in the IBM WebSphere Studio Application Developer V5.0.1 environment, do the following: 1. Log on to your system with a user ID that has Administrator authority (you will need write access to the install location). 2. Ensure the IBM WebSphere Studio Application Developer is closed. 3. Back up the \runtimes\base_v5 directory. This step is optional, but recommended if you have disk space to do so. 1012 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 4. Download the WebSphere Test Environment V5.0.1 for Windows zip file (was50_fp1_win.zip) to a temporary directory (for example, c:\temp). http://www3.software.ibm.com/ibmdl/pub/software/websphere/studiotools/html/ 501/wsad/install_was.html 5. Unzip the WebSphere Test Environment V5.0.1 zip file (was50_fp1_win.zip) to the root of your WebSphere Studio Application Developer installation directory. In our example, we unzipped to the c:\ibm\wsad directory. 6. Open a Windows command prompt and navigate to the /runtimes/base_v5/ptf directory. Where is the installation directory where you have installed IBM WebSphere Studio Application Developer. 7. To apply the update, type wteInstall. 8. Review the Readme file and license information files for more information on this update. Install WebSphere Studio Application Developer V5.0.1 Interim Fix 3 After the IBM WebSphere Studio Application Developer V5.0.1 PTF has been installed, we recommend that you install the WebSphere Studio Application Developer V5.0.1 Interim Fix 003. The Interim Fix 003 installation instructions can be found at: http://www.ibm.com/support/docview.wss?rs=457&context=SSBRLP&q=&uid=swg2400 5554&loc=en_US&cs=utf-8&lang=en Like the WebSphere Studio Application Developer V5.0.1 PTF, the Interim Fix 3 can be installed using the Update Manager as follows: 1. Log on to your system with a user ID that has Administrator authority (need write access to the install location). 2. Start IBM WebSphere Studio Application Developer V5.0 by selecting Start -> Programs -> IBM WebSphere Studio -> Application Developer 5.0. 3. Search for the PTF on the IBM update site by selecting Help -> Software Updates -> Update Manager. 4. In the Feature Updates view, select and expand Sites to Visit -> IBM WebSphere Studio Application Developer Fixes -> Version 5.0 Fixes -> WebSphere Studio Application Developer Interim Fix 003 5.0.1.3. 5. Details about this interim fix are shown in the Preview view. Click Install to begin the installation. For more information about what is included in the interim fix, click the More Info link. Appendix E. WebSphere Commerce Studio implementation 1013 6. When the Feature Install wizard appears, click Next. 7. Review the license agreement. Select I accept the terms in the license agreements, and click Next. 8. When the Optional Features window appears, click Next. Do not modify the selections. Changing the default choices may result in errors. 9. When the Install Location window appears displaying the install path, click Finish to begin the installation. Errors may occur if you change the default install location. 10.If you are warned that you are about to install an unsigned feature, click Install to continue. This warning will not cause problems during installation. 11.When the installation is complete you will be prompted with the message, “You will need to restart the workbench for the changes to take effect. Would you like to restart now?” Click Yes to complete the installation. 12.To verify that the WebSphere Studio Application Developer V5.0.1 Interim Fix 003 installation was successful, do the following: a. Switch to the Install/Update perspective by selecting Help -> Software Updates -> Update Manager. b. Select the Installation Configurations view. Select and expand Current Configurations. Verify that WebSphere Studio Application Developer 5.0.1 Interim Fix 003 is installed under file:c:/ibm/wsad/wstools/eclipse. The IBM WebSphere Studio Application Developer V5.0.1 Interim Fix 003 installation is now complete. Install DB2 UDB V8.1 Fix Pack 3 We installed IBM DB2 UDB V8.1 Fix Pack 3 for 32-bit Windows. The internal DB2 level is 8.1.3.132 after the installation of Fix Pack 3. In our example, the WebSphere Commerce instance database and WebSphere Commerce Payments database were created during the WebSphere Commerce Studio installation. For this reason, special steps need to be taken to rebind the DB2 utilities to the databases after the fix pack installation. 1014 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: If you plan on using IBM WebSphere Digital Media Enable V5.5 ,we recommend that you use DB2 UDB V8.1 Fix Pack 2. The DB2 Information Integrator for Content (EIP) V8.1.2 (Fix Pack 2 level) required DB2 UDB V8.1 Fix Pack 2. There is no fix pack level of EIP for DB2 UDB V8.1 for Fix Pack 3. There are plans to create a Fix Pack 4 level for both. Details on installing IBM DB2 Universal Database V8.1, Enterprise Server Edition Fix Pack 3 can be found at: ftp://ftp.software.ibm.com/ps/products/db2/fixes/english-us/db2winIA32v8/fi xpak/FP3_WR21324/ The high-level steps to install IBM DB2 UDB V8.1 Fix Pack 3 are as follows: 1. Log on to your system with a user ID that has Administrator authority. 2. Download the IBM DB2 Universal Database V8.1, Enterprise Server Edition Fix Pack 3 (FP3_WR21234_ESE.exe) from the following URL to a temporary directory (for example, c:\temp). ftp://ftp.software.ibm.com/ps/products/db2/fixes/english-us/db2winIA32v8/fi xpak/FP3_WR21324/ 3. Stop all DB2 services in the Windows services. 4. Install the IBM DB2 UDB V8.1 Fix Pack 3: – Run the self extracting fix pack installer (FP3_WR21234_ESE.exe). – We accepted the default installation options. 5. You will need to restart your system before the fixes will take effect. 6. After the system has restarted, open a DB2 command window and enter the following DB2 command: db2level It should return 8.1.3.132 after Fix Pack 3 has been installed. 7. You need to rebind your DB2 utilities with all databases after the fix pack installation. This step is necessary for the fixes to become effective. The binding procedure needs to be performed only once per database. In our example, we will need to rebind the following databases: – WebSphere Commerce instance database (wc1dev) – WebSphere Commerce Payments database (wpm) To list the names of the databases, enter the following: db2 list db directory Appendix E. WebSphere Commerce Studio implementation 1015 To rebind the DB2 UDB databases after applying fixes, enter the following commands from a DB2 command window for each database: db2 db2 db2 db2 db2 terminate CONNECT TO BIND \BND\@db2ubind.lst GRANT PUBLIC BIND \BND\@db2cli.lst GRANT PUBLIC terminate Where represents the name of a database to which the utilities should be bound and represents the directory where you have installed DB2. The db2ubind.lst and db2cli.lst contain lists of required bind files used by DB2 UDB V8.1. Install WebSphere Commerce Studio Toolkit V5.5.0.2 Fix Pack This section describes the procedure for installing the IBM WebSphere Commerce Studio Toolkit V5.5.0.2 Fix Pack. In our example, we are updating IBM WebSphere Commerce Studio V5.5, Business Developer Edition and using IBM IBM DB2 Universal Database V8.1, Enterprise Server Edition (Fix Pack 3). During the fix pack installation, there are several key tasks that are performed that we would like to clarify so you have a better understanding of what to expect during the installation. First, WebSphere Commerce Studio uses the WebSphere Studio Application Developer Update Manager to download the WebSphere Commerce Studio V5.5.0.2 Toolkit Fix Pack to the file system on your local system. Second, both the WebSphere Commerce Studio and WebSphere Commerce workspace directories are serviced using the Update Installation wizard. The order in which these tasks occur is as follows: Prerequisites (WebSphere Studio Application Developer V5.0.1) Pre-install of fix pack (copy version files) Installation of fix pack using the Update Manager Update Manager is used to start the fix pack installation and download the fix pack to the local file system. Install fix pack to the WebSphere Commerce Studio directory The Update Installation wizard is launched by the Update Manager to install the fix pack to the WebSphere Commerce Studio directory. Update instance database (updatedb.bat) Install fix pack to the workspace directory The Update Installation wizard is launched manually to install the fix pack to the WebSphere Commerce workspace directory. 1016 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide After the installation, the user must complete the post-install configuration steps in “WebSphere Commerce Studio configuration” on page 1021. Detailed installation instructions can be found in the Update Guide for WebSphere Commerce Studio Toolkit V5.5.0.2 PDF, which can be downloaded with the fix pack at: http://www.ibm.com/support/docview.wss?rs=494&uid=swg24005628 Prerequisites Ensure you have upgraded IBM WebSphere Studio Application Developer to V5.0.1 as described in “Install WebSphere Studio Application Developer V5.0.1 PTF” on page 1010. Pre-install of fix pack Before you install the IBM WebSphere Commerce Studio Toolkit V5.5.0.2 Fix Pack, do the following: 1. Move the version files: a. Navigate to the \Commerce\properties\version directory. b. Move all the files: From: \Commerce\properties\version To: \properties\version 2. Back up resources.xml. a. Navigate to the \WebSphereTestEnvironment\WebSphereComme rceServerConfiguration.wsc\cells\localhost\nodes\localhost\servers\server 1 directory. b. Back up the resources.xml file. Installation of fix pack using the Update Manager To install the IBM WebSphere Commerce Studio Toolkit V5.5.0.2 Fix Pack, do the following: 1. Start IBM WebSphere Commerce Studio by selecting Start -> Programs -> IBM WebSphere Commerce Studio -> WebSphere Commerce development environment. 2. From the workspace, select Help -> Software Updates -> Update Manager. 3. In the Feature Updates window, right-click Sites to Visit, and select New -> Site Bookmark. Appendix E. WebSphere Commerce Studio implementation 1017 4. When the New Update Site Bookmark window appears, enter the following and then click Finish: – Name: For example, type wcs5502. – URL: In the URL field enter one of the following for the corresponding edition: • Business Developer Edition: ftp://ftp.software.ibm.com/software/websphere/commerce/55/5502/studio /BE/site.xml This is what we entered for the ITSO example. • Professional Developer Edition: ftp://ftp.software.ibm.com/software/websphere/commerce/55/5502/studio /PE/site.xml 5. From the Features Updates window, select and expand -> WebSphere Commerce Studio V5.5 Fixes. Click WebSphere Commerce Studio Fix Pack 5.5.0.2. 6. In the Preview window, click Install to begin the installation. 7. When the Features Install window appears, click Next to confirm the feature you are about to install. 8. Review the license agreement. Select I accept the terms in the license agreements, and click Next. 9. Click Finish to begin the installation. 10.When the Feature Verification window appears, click Install. The installer will begin downloading the update files. When the files have been downloaded, the Update Installation wizard will be started. Continue to the next section. Install fix pack to the WebSphere Commerce Studio directory This section describes how to use the Update Installation wizard to update the WebSphere Commerce Studio directory with the fix pack. 11.When the Update Installation wizard opens, click OK for English. 12.When the Welcome page appears, click Next. 1018 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide 13.When the Target Installation directory window appears, we entered c:\ibm\wcstudio and then clicked Next. In our example, the installer did not detect the WebSphere Commerce Studio installation directory. Enter the installation directory in the text field or click the Browse option and navigate to the directory. 14.Select Install fix packs and then click Next. 15.When the Fix pack location directory window appears, enter the \Installer\studio directory in the Fix pack directory text field. For example, we entered c:\ibm\wsad\Installer\studio and then clicked Next. 16.When the List of fix packs window appears, ensure the studio55BE_fp2 is selected and click Next. 17.When the summary page appears, click Next to begin the fix pack installation. 18.When the fix pack installation is complete, you should see the following message: The following fix pack was successfully installed: studio55BE_fp2 19.Click Finish. 20.After clicking Finish, the installation will exit the Update Installation wizard and return to the Update Manager. The Install/Update window appears with the message, “You will need to restart your workbench for the changes to take effect. Would you like to restart?”. In our example, we clicked Yes to restart the workspace. 21.Close WebSphere Studio Application Developer. Update instance database (updatedb.bat) The updatedb.bat script is used to update existing instance databases. This process should be repeated for each instance database that was created before installing the fix pack. 1. Open a command window and change to the \Commerce\bin directory. 2. Run the following command: updatedb.bat Where: – is the name of the instance database. – is the DB2 user name that owns the database. – is the DB2 user password. Appendix E. WebSphere Commerce Studio implementation 1019 – is the WebSphere Commerce instance name. – is either DB2 or Oracle. – is the host name of the machine where the database resides. For example: updatedb.bat wc1dev admin mypassword wc1dev DB2 wcbuild 3. When the script is done, you should see a message: Successfully updated : . Where is the instance database name. Install fix pack to the workspace directory This section describes how to install the fix pack to the WebSphere Commerce workspace directory using the Update Installation wizard. 1. Ensure that WebSphere Studio Application Developer has been stopped. 2. Navigate to the \Installer directory and double-click updateWizard.bat. 3. When the Update Installation wizard appears, click OK for English. 4. Whenm the Welcome page appears, click Next. 5. When the Target Installation window appears, notice this time that the WebSphere Commerce Studio 5.5 Business is detected, and the WebSphere Commerce Studio installation directory is displayed. In this case, however, we want to install the fix pack to the WebSphere Commerce workspace directory. Check Specify product information and enter the WebSphere Commerce workspace directory. For example, we entered c:\ibm\workspace and then clicked Next. 6. Select Install fix packs and click Next. 7. When the Fixpack location directory window appears, enter the following path in the fix pack directory: \Installer\workspace and then click Next. For example, we entered c:\ibm\wsad\Installer\workspace. Note: Previously we entered the studio directory. In this case, we need to specify the workspace directory. If you enter the studio directory, the Update Installation wizard will get an installation failure. 8. When the List of fix packs window appears, ensure the studio55BE_fp2 is selected and click Next. 9. When the summary page appears, click Next to begin the fix pack installation. 1020 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Note: We found that the product summary did not display the product name. 10.When the fix pack installation is complete, you should see the following message: The following fix pack was successfully installed: studio55BE_fp2 11.Click Finish. The WebSphere Commerce Studio installation is now complete. Continue to the WebSphere Commerce Studio configuration section. WebSphere Commerce Studio configuration This section describes the required and optional configuration tasks for WebSphere Commerce Studio after the installation. Required post-install configuration After the installation of WebSphere Commerce Studio, perform the following required configuration tasks. Note: As documented in the Update Guide for WebSphere Commerce Studio Toolkit V5.5.0.2, when using WebSphere Studio Application Developer V5.0.1, you do not have to repackage the messaging adapter JARs, as was the case for the original release of WebSphere Commerce Studio V5.5 and WebSphere Studio Application Developer V5.0. Update existing instance XML This section describes how to update the instance XML file for changes needed after installing the WebSphere Commerce Studio V5.5.0.2 Toolkit Fix Pack. These changes should be made on each instance that was created before installing the fix pack. Appendix E. WebSphere Commerce Studio implementation 1021 Workaround: At the time of writing, we found that the config_ant.bat supplied with the WebSphere Commerce Studio V5.5.0.2 Toolkit Fix Pack did not work as documented in the Installation Guide for IBM WebSphere Commerce V5.5.0.2 Fix Pack guide. We found that we had to modify the config_ant.bat script to address the following error message displayed after attempting to run config_ant.bat: The system cannot find the path specified. See the modified config_ant.bat in Example E-1. 1. Open a command window and change to the \Commerce\bin directory. 2. We modified the config_ant.bat to properly set variables (for example, JAVA_HOME) as seen in Example E-1. Example: E-1 Workaround update to config_ant.bat @echo off setlocal call setenv.bat set WAS_USER_SCRIPT=config_env.bat if exist %WAS_HOME%\bin\setupCmdLine.bat call %WAS_HOME%\bin\setupCmdLine.bat "%JAVA_HOME%\bin\java" %PM_ARGS% "-Dwas.install.root=%WAS_HOME%" "-Dwas.repository.root=%CONFIG_ROOT%" -Dcom.ibm.CORBA.BootstrapHost=%COMPUTERNAME% -Djava.security.policy="config.policy" com.ibm.ws.bootstrap.WSLauncher org.apache.tools.ant.Main %* endlocal 3. Run the following command: config_ant.bat -buildfile \Commerce\xml\config\updateInstances.xml -DupdateCEP=no -Duninstall=no -DinstName= Where is the WebSphere Commerce Studio installation path (for example, c:\ibm\wcstudio). Where is the WebSphere Commerce Studio instance name (for example, wc1dev). 1022 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide For example: config_ant.bat -buildfile c:\ibm\wcstudio\Commerce\xml\config\updateInstances.xml -DupdateCEP=no -Duninstall=no -DinstName=wc1dev 4. After the config_ant.bat script is run, verify that the \Commerce\Instances\\xml\.xml file has been updated (for example, a new date and the file size should be different in the backup created). If you really want to know what is different, compare the .xml and the backup created. Update WebSphere Commerce Server data source Before you can start the WebSphere Commerce server in the WebSphere Test Environment of WebSphere Studio Application Developer, you must update the WebSphere Commerce server data source with the correct database user and password. To update the WebSphere Commerce server data source, do the following: 1. Start WebSphere Commerce Studio by selecting Start -> Programs -> IBM WebSphere Commerce Studio -> WebSphere Commerce development environment. 2. In the J2EE Hierarchy view of the J2EE perspective, expand Servers and double-click WebSphereCommerceServer. The WebSphereCommerceServer view displays. 3. You will see a message, “Some project definitions in the server configuration are not valid. Do you want the editor to fix the project definitions automatically?” Click Yes. 4. In the WebSphereCommerceServer view, select the Data source tab. 5. On the Data sources page, expand Server Settings. 6. In the JDBC provider list table, we selected DB2 JDBC Driver. After selecting a JDBC provider, the tables below the JDBC Provider list table will be updated. 7. In the data source defined in the JDBC provider table selected above, select the data source for the WebSphere Commerce Studio database. In our example, we selected DB2 jdbc/WebSphere Commerce DB2 DataSource , where is the name of the WebSphere Commerce Studio instance. In our example, we named the instance wc1dev. 8. Click Edit. The Modify Data Source wizard starts. Appendix E. WebSphere Commerce Studio implementation 1023 9. In the Modify Data Source wizard, ensure the following are set properly. We only had to change the default user password. – Name: jdbc/WebSphere Commerce DB2 DataSource – JNDI name: jdbc/WebSphere Commerce DB2 DataSource – Database name: – Default user ID: – Default user password: 10.Click Finish to update the information and close the Modify Data Source wizard. 11.Save the updates to the configuration by selecting File -> Save WebSphereCommerceServer. Note: Updating the WebSphere Commerce Payments server data source is not required. Update the WebSphere Commerce Studio API docs To update the WebSphere Commerce Studio API documentation, do the following: 1. Close WebSphere Commerce Studio. 2. Download the javadoc.zip file from the WebSphere Commerce Support Web site at the following URL to a temporary directory: http://www.ibm.com/support/docview.wss?uid=swg24005628 3. Unpack the contents of the javadoc.zip file into the \eclipse\plugins\com.ibm.commerce.api.doc directory replacing any existing files. 4. Start WebSphere Commerce Studio. 5. Select Help -> Help Contents. 6. From the Help Contents page, select one of the following to ensure that the documentation is working properly: – WebSphere Commerce Production information – WebSphere Commerce Development information – WebSphere Commerce messages Note: If you are prompted by the Update Manager to apply pending changes for the WebSphere Studio Application Developer V5.0.1 PTF/interim fix and WebSphere Commerce Studio V5.5.0.2 Toolkit Fix Pack, check both and click Finish. You will be prompted to restart WebSphere Commerce Studio. 1024 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Optional post-install configuration This section describes optional but recommended configuration tasks for the WebSphere Commerce Studio development environment. Reduce the memory requirements for DB2 The WebSphere Commerce instance database settings are optimized for a production environment, with the anticipation that many users will be accessing the WebSphere Commerce site. There are two reasons that we choose to tune down the database settings within the development environment. First, typically only one user will be accessing the WebSphere Test Environment running the WebSphere Commerce Server. Second, having additional system memory can improve the performance of operations in the WebSphere Commerce Studio. This task is optional but recommended. To reduce the memory requirements of DB2 within the WebSphere Commerce Studio environment, complete the following steps: 1. Start a DB2 command window. 2. Enter the commands listed in Example 21-5 in the DB2 command window. Example 21-5 Reduce the memory requirements for DB2 (optional) db2 connect to user using alter bufferpool IBMDEFAULTBP size 1000 alter bufferpool BUFF8K size 50 alter bufferpool BUFF16K size 50 alter bufferpool BUFF32K size 50 Configure payment methods Before enabling the WebSphere Commerce Payments for use with WebSphere Commerce in the WebSphere Test Environment with WebSphere Studio Application Developer, you may need to configure the payment methods accepted by a store. When you a publish a sample store, a number of sample payment methods are automatically configured and the instructions in this section can be skipped. However, you should complete these steps after publishing a sample store if you find the sample store does not contain payment methods you would like to test. 1. Ensure the WebSphere Commerce server is started. To start the WebSphere Commerce application in the WebSphere Test Environment, right-click WebSphereCommerceServer in the Servers view, and select Start. Appendix E. WebSphere Commerce Studio implementation 1025 2. Ensure the WebSphere Commerce Payments server is started. To start the WebSphere Commerce Payments application in the WebSphere Test Environment, in the Servers view, right-click WebSphereCommercePaymentsServer and select Start. 3. Log in to WebSphere Commerce Payments Console using the site administrator user ID and password. You can access the WebSphere Commerce Payments Console by entering the following in a Web browser: http://:5432/webapp/PaymentManager or https://:5433/webapp/PaymentManager 4. From the left pane, select Merchant Settings. 5. Click Refresh to see what merchant was added after you have published a sample store. 6. In the right pane, click Add a Merchant. 7. Enter a Merchant Name for your sample store. The Merchant Number must be the same as the store ID for your store (for example, 10001). 8. Check the OfflineCard check box and click Create Merchant. The message “A Merchant created successfully” should appear. Note: If a merchant already exists for your storeID, you cannot create another merchant for the same storeID. 9. In the left pane, click Merchant Settings again. In the right-hand pane, beside the name of your new merchant, the green cassette status icon (under the OfflineCard column) indicates that the OfflineCard cassette is enabled and running for that merchant. Click the green icon. 10.You must now create an account for each currency supported by your store, by clicking Accounts. a. Click Add an Account. b. Enter an account name and an account number. The account number must be unique within that store. c. Select the appropriate currency from the drop-down menu. Click Create Account. d. In the Accounts window, click the name of your new account, then click Brands. e. Click Add a Brand. Enter a brand name (for example, VISA) and click Create Brand. 11.Repeat for the above step for all other brands to be used with this account. 1026 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Configure the default Web browser We recommend that you configure the Web browser within WebSphere Studio Application Developer to use the external Microsoft Internet Explorer Web browser. On a typical development system, there are two methods of accessing the Internet Explorer (IE): IE 6 from Windows IE internal to WebSphere Studio Application Developer When starting some WebSphere Commerce administration tools from the Web browser in WebSphere Studio Application Developer 5, a new window is opened that does share the same session as the original window. To work around this issue, do one of the following: 1. Update WebSphere Studio Application Developer 5 to use the external browser (preferred option). By updating WebSphere Studio Application Developer 5 to use the external IE browser, a user can click the Web browser icon from WebSphere Studio Application Developer and it will launch the IE 6 from the system. 2. The alternative is to just use the external Internet Explorer (do not use the IE built-in Web browser of WebSphere Studio Application Developer 5). Set default XML editor to optimize performance While writing this redbook, we discovered that opening large XML files with the XML Editor included with the WebSphere Studio Application Developer V5 did not perform as desired. The XML Editor is the default for .xml and .dtd files. To provide better performance, we set the default editor for .xml to Text Editor (or Source Editor). This change is optional. 1. From the main menu in WebSphere Studio Application Developer, select Windows -> Preferences. 2. Select Workbench -> File Associations. 3. Select the *.xml file. 4. From the File Associated editors list, click Add for the Text Editor. 5. Click Default to make the Text Editor the default editor .xml. Note: The downside to this change is that you no longer have the syntax checking provided by the XML Editor. Appendix E. WebSphere Commerce Studio implementation 1027 WebSphere Commerce Studio verification After the WebSphere Commerce Studio installation and configuration are complete, we recommend that you verify that the WebSphere Commerce Payments and WebSphere Commerce servers start properly. Note: We started the WebSphereCommerceServer last to ensure the console shows the WebSphere Commerce messages. Atlernatively, you can switch between the console output for the servers within the Debug perspective in WebSphere Studio Application Developer V5.0.1. WebSphere Studio Application Developer V5.1 contains a new feature to switch console output directly in the console view in the J2EE and Server perspectives. Start the WebSphere Commerce Payments Server To start the WebSphere Commerce Payment Server, do the following: 1. From the WebSphere Commerce Studio workspace, go to the J2EE perspective. Click the Servers tab. 2. Select WebSphereCommercePaymentsServer, and right-click Start. If successful, you should see the message, “Server server1 open for e-business”. Start the WebSphere Commerce Server To start the WebSphere Commerce Server, do the following: 1. From the WebSphere Commerce Studio workspace, go to the J2EE perspective. Click the Servers tab. 2. Select WebSphereCommerceServer, and right-click Start. If successful, you should see the message, “Server server1 open for e-business”. 1028 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide F Appendix F. Additional material This redbook refers to additional material that can be downloaded from the Internet as described below. Locating the Web material The Web material associated with this redbook is available in softcopy on the Internet from the IBM Redbooks Web server. Point your Web browser to: ftp://www.redbooks.ibm.com/redbooks/SG246969 Alternatively, you can go to the IBM Redbooks Web site at: ibm.com/redbooks Select the Additional materials and open the directory that corresponds with the redbook form number, SG246969. © Copyright IBM Corp. 2003. All rights reserved. 1029 Using the Web material The additional Web material that accompanies this redbook includes the following files: File name 6969code.zip Description WebSphere Commerce V5.5 Handbook zipped code samples System requirements for downloading the Web material The following system configuration is recommended: Hard disk space: Operating System: Processor: Memory: 15 MB minimum Windows, Solaris, AIX 1 GHz or higher 1 GB Refer to Chapter 10, “ITSO sample code” on page 319 for more detailed information. 1030 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Related publications The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook. IBM Redbooks For information on ordering these publications, see “How to get IBM Redbooks” on page 1034. Note that some of the documents referenced here may be available in softcopy only. WebSphere Commerce V5.5 Capacity Planning, SG24-6304 (expected publish date 12/2003) WebSphere Digital Media V5.5 Solutions Guide, SG24-6085 (expected publish date 2/2004) Best Practices and Tooling for Creating IBM WebSphere Commerce Sites, REDP3616 WebSphere Commerce V5.4 Catalog Design and Content Management, SG24-6885 WebSphere Commerce Portal V5.4, Using WebSphere Commerce V5.4 and WebSphere Portal V4.2, SG24-6890 IBM WebSphere Application Server V5.0 Systems Management and Configuration: WebSphere Handbook Series, SG24-6195 WebSphere V5.0 Applications: Ensuring High Performance and Scalability, SG24-6198 IBM WebSphere V5.0 Security WebSphere Handbook Series, SG24-6573 WebSphere Studio Application Developer Version 5 Programming Guide, SG24-6957 Enhance Your Business Applications: Simple Integration of Advanced Data Mining Functions, SG24-6879 DB2 UDB/WebSphere Performance Tuning Guide, SG24-6417 Patterns: Custom Designs for Domino & WebSphere Integration, SG24-6903 IBM Certification Study Guide - pSeries AIX System Administration, SG24-6191 IBM HTTP Server (powered by Apache) for iSeries, SG24-6716 © Copyright IBM Corp. 2003. All rights reserved. 1031 Enterprise Business Portals II with IBM Tivoli Access Manager, SG24-6885 Measuring e-business Web Usage, Performance, and Availability, SG24-6931 IBM WebSphere V5 Edge of Network Patterns, SG24-6896 Other publications These publications are also relevant as further information sources: What’s New in IBM WebSphere Commerce V5.5 Fundamentals Guide, IBM WebSphere Commerce V5.5 Quick Beginnings Guide for Windows 2000, IBM WebSphere Commerce V5.5 Quick Beginnings Guide for AIX, IBM WebSphere Commerce V5.5 Quick Beginnings Guide for Solaris, IBM WebSphere Commerce V5.5 Quick Beginnings Guide for OS/400, IBM WebSphere Commerce V5.5 Quick Beginnings Guide for Linux, IBM WebSphere Commerce V5.5 Installation Guide, IBM WebSphere Commerce V5.5 for UNIX Systems Installation Guide, IBM WebSphere Commerce V5.5 for Windows 2000 Installation Guide, IBM WebSphere Commerce V5.5 for OS/400 Installation Guide, IBM WebSphere Commerce V5.5 for Linux Additional Software Guide, IBM WebSphere Commerce V5.5 (all platforms) Installation Guide, IBM WebSphere Commerce Studio V5.5 Installation and Configuration Guide, IBM WebSphere Commerce Analyzer V5.5 Datamart Reference, IBM WebSphere Commerce Analyzer V5.5 Technical Reference, IBM WebSphere Commerce Analyzer V5.5 Payments Programming Guide and Reference, IBM WebSphere Commerce V5.5 Payments Cassette for Paymentech Supplement, IBM WebSphere Commerce V5.5 Payments Cassette for BankServACH Supplement, IBM WebSphere Commerce V5.5 Payments Cassette for VisaNet Supplement, IBM WebSphere Commerce V5.5 Payments Offline Cassette Supplement, IBM WebSphere Commerce V5.5 1032 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Payments Custom Offline Cassette Supplement, IBM WebSphere Commerce V5.5 Sample Store Guide, IBM WebSphere Commerce V5.5 Store Development Guide, IBM WebSphere Commerce V5.5 Programming Guide and Tutorials, IBM WebSphere Commerce V5.5 Web Services Guide, IBM WebSphere Commerce V5.5 Administration Guide, IBM WebSphere Commerce V5.5 Security Guide, IBM WebSphere Commerce V5.5 Accelerator Customization Guide, IBM WebSphere Commerce V5.4 Quick Beginnings, IBM WebSphere MQ V5.3 for Windows, GC34-6073-01 http://www.ibm.com/software/integration/mqfamily/library/manualsa/manuals/p latspecific.html System Administration Guide, IBM WebSphere MQ V5.3, SC34-6068-01 (common for multiplatforms) http://www.ibm.com/software/integration/mqfamily/library/manualsa/manuals/c rosslatest.html “EJB Tutorial”, downloadable at the following URL: http://www.ejbtut.com Article titled “What are Enterprise JavaBeans components?“, downloadable from the following URL: http://www-106.ibm.com/developerworks/library/what-are-ejbs/part1/inde.html Online resources These Web sites and URLs are also relevant as further information sources: IBM WebSphere Commerce V5.5, Business Edition – Home page http://www.ibm.com/software/genservers/commerce/wcbe/index.html – Technical Library http://www.ibm.com/software/genservers/commerce/wcbe/library/lit-tech-ge neral.html – Support http://www.ibm.com/software/genservers/commerce/wcbe/support/ Related publications 1033 IBM WebSphere Commerce V5.5, Professional Edition – Home page http://www.ibm.com/software/genservers/commerce/wcpe/index.html – Technical Library http://www.ibm.com/software/genservers/commerce/wcpe/library/lit-tech-ge neral.html – Support http://www.ibm.com/software/genservers/commerce/wcpe/support/ IBM WebSphere Commerce Zone (development information) http://www.software.ibm.com/wsdd/zones/commerce/ IBM Services for IBM WebSphere Commerce Software http://www.ibm.com/software/genservers/commerce/services/ How to Buy IBM WebSphere Commerce http://www.ibm.com/software/swprod/swprod.nsf/(BuildHTBPage)?OpenAgent&DocI D=BMAL-5KSR6N How to get IBM Redbooks You can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at this Web site: http://ibm.com/redbooks 1034 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Index Abstract Character Set 242 Access control 37, 72, 127, 461 elements actions 72 relationships 72 resources 72 users 72 Access control groups 73 Access control model 69 Access control policies 69, 73 Account representatives 165 activation.jar 889 Adapter manager 115, 894 Adapters 115 HTTP Browser adapter 115, 895 HTTP PVC adapter 115, 895 Program adapter 116, 895 Scheduler adapter 116, 895 Add defining attributes 530 Add price to product 532 Add product 529 Add remote Database Server 582 Add remote Web Server 588 Add SKU 531 Address formatting 235 Administration business models 61 Configuration Manager 571 configure e-mail message type 955 contracts 380 create WebSphere Commerce instance 571 create WebSphere Commerce Payments instance 573 enable e-mail transport 954 ITSO B2B working example 527 James configuration 951 JCA-JMS configuration for MQ 920 operational categories to manage 152 product management 528 add category 528 add defining attributes 530 add price to product 532 add product 528 add SKU 531 site 133 store 133 store models 61 tools 134 Configuration Manager 134 WebSphere Commerce configuration for MQ 932 WebSphere Commerce programming model 109 WebSphere MQ configuration 916 Administration tools 134 DB2 Control Center 152 Loader Package 147 scheduler 148 WebSphere Application Server Administration Console 150 WebSphere Commerce 134 WebSphere Commerce Accelerator 142 WebSphere Commerce Administration Console 139 WebSphere Commerce Configuration Manager 134 WebSphere Commerce Organization Administration Console 145 WebSphere Commerce Payments Console 149 AIX 961 allocate storage to file system 992 commands 962 create file system 964 create logical volume 963 create volume group 962 df 966 du 966 mount 962 netstat 962 oslevel 962 rc.tcpip 966 shutdown 966 tcp.clean 966 © Copyright IBM Corp. 2003. All rights reserved. 1035 Symbols .classpath 195 A unmount 962 create users 992 installation 680 required filesets 682 Journal File System 991 Logical Volume 990 OpenSSH 967 performance monitoring tools 965 tasks 961 TCP/IP 966 WebSphere Commerce 675 Analytics to action 795–796 Ant 508 Application asset archive deployment 523 Application assets archive build 514 application assets archive (JAR) 514 Application flow of an HTTP request 120 application.xml 192 Architecture messaging 884 WebSphere Commerce Analyzer 798 WebSphere Commerce components 29 WebSphere Commerce runtime 27 WebSphere Commerce subsystems 34 ASCII 244 attach 994 Attributes 92 Auctions 156 Authentication 37 Availability 44 load balancing 45 process isolation 45 process redundancy 44 B B2B direct 63 access control structure 75 organizational structure 70 store archive 83 B2BDirect.sar 84 Back office assets 79 Backup DB2 database 988 Basic access control structure 73 Basic Multilingual Plane 244 BiDi See Bi-Directional 1036 Bi-Directional languages Arabic 259 Farsi 259 Hebrew 259 Urdu 259 Yiddish 259 Big5 243 Brio 794 Build application assets archive (JAR) 514 store archive (SAR) 516 Build and SCM node 324 implementation 328 CVSNT Server 330 WebSphere Commerce Studio 336 software components 325 Build automation 212 Build cycle 187 Build environment 209 Build procedure 507 build script modification 508 Build Verification Test (BVT) 327 build.xml DeployTool 515 Bundle 93 Business accounts 77 Business direct 292 Business logic 79 Business models 62 B2B direct 63 Consumer direct 63 Demand chain 66 Hosting 64 infrastructure 69 supply chain 68 Business Objects 795 Business policies 76, 90 Business policy framework 76 business accounts 77 business policies 76 contracts and service agreements 77 terms and conditions 77 Business relationship roles 165 Business relationships 155 Business requirements 178 Business user roles buyer 168 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide buyer administrator 168 buyer approver 168 seller administrator 168 business-to-consumer (B2C) 63 Buyer 168 Buyer Administrator 168 Buyer Approver 168 C Campaigns 90 Cascading Style Sheets 285 Catalog data methods of customizing 360 Catalog data assets 90–91 Catalog data entities attributes 92 defining 92 descriptive 92 bundle 93 catalog entry 92 catalog group 92 create WebSphere Commerce Payments instance 573 dynamic kit 93 master catalog 92 navigational catalog 92 pre-built kit 93 product 92 SKU 93 static kit 93 Catalog data files catalog.xml 360 locale catalog.xml 360 offering.xml 360 store-catalog.xml 360 store-catalog-shipping.xml 360 store-catalog-tax.xml 360 catalog db 995 Catalog entries 39 Catalog entry 92 Catalog group 92 Catalog management 152 Catalog subsystem 39 catalog.xml 360 Catalogs 90 Category manager 169 CCSID 924 Channel manager 165 Character 242 Character Encoding Form 242 CheckPriceWatchPrices controller command 395 chfs 993 Cisco Local Director 44 Clone 42 Cluster 42, 45, 54 Cluster member 42 Code point 242 Coded Character Set 242 Collaboration 33 Collaborative Workspaces 34, 158 Command design pattern 124 command.xml 512 Commands 117 controller commands 117 data bean command 118 task commands 117 view command 118 Commerce analytics 33, 787 business drivers 788 overview 788 WebSphere Commerce features 789 Concurrent Version System 206, 324, 328 Configuration CVS for NT 331 DB2 connectivity Windows 585 IBM HTTP Server AIX 687 SSL 590 Windows 590 iPlanet Web Server 615 Oracle9i Enterprise Edition prepare database 634 OS/400 765 Solaris 973 Solaris 8 configuration 977 Web server static content 597 WebSphere Commerce instance creation 650 WebSphere Commerce Studio 1021 WebSphere MQ 916 WebSphere Commerce 932 WebSphere Studio Application Developer edit large XML files 1027 Configuration data 88, 90 Configuration Manager 134 create WebSphere Commerce instance 571 Index 1037 instance components 137 Solaris 650 update instance properties 136 configure scheduler 495 Construction 186 Consumer direct 63, 292 store archive 82–83 Consumer direct basic store archive 83 ConsumerDirect.sar 83 contract.xml 381–382 Contracts 77, 90, 380 contract.xml 381 elements attachments 380 participants 380 profile 380 reference 381 terms and conditions 380 methods of creating using XML 381 WebSphere Commerce Accelerator 381 Contracts and service agreements 77 Cookie 38 Core data 88–89 Core development phases 179 Coupons 90 Create a business account 379 Create a contract 545 Create a store 341 optional customization 367 overview 342 package and verify store archive 343 required customization 354 Create and organization 536 Create customized reports 868 Create non-root users 702 Create project in WSAD 345 Create_ITSO_Customer.dtd 937, 942 Create_ITSO_Customer.xml 937, 947 create_wca_apply_tables.sql 814 crfs 993 Crystal 795 CSS See Cascading Style Sheets ctrluser user 810 Cultural considerations 224 address formatting 234 currency 229 1038 date format 225 name formatting 234 number formatting 229 time format 227 CURCONVERT table 808 Currencies 90 Currency 230 store customization 367 Currency format 264 Custom code packaging 201 Custom Load 819 Customer Acceptance Test (CAT) 327 Customer Care 33, 157 Customer service representative (CSR) 166 Customer service supervisor 166 Customers 90 Customize store price watch configure e-mail transport 403 configure scheduler for batch job 493 create batch e-mail command 482 create new commands 438 create new data bean 463 create new database table 406 create new JSPs 470 import e-mail template 491 new data access beans 408 overview 394 pre-conditions 402 solution design 394 testing 498 Customizing a store 96 Customizing application assets 128 asset types 128 back office (business logic) 129 data files 129 store front 129 needed skills 130 CVS import store assets 350 See Concurrent Version System CVS client configuration 336 CVS for NT 330 D Daily build benefits 209 Data bean command 118 Data Bean Manager 119 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide data capture 844 data mining 832 Data mining tools 790 Data structuring tools 790 Database administrator 163 Database Configuration Assistant 1001 Database schema owner 16 datamart 790, 826 Datasource 807 datasource to datamart 862 Date format 225 DB2 catalog tcpip node 994 connectivity configuration 585 installation 692 reduce memory requirements 1025 verification 587 DB2 commands 993 attach 586, 994 catalog db 995 catalog TCP/IP node 994 chfs 993 connect reset 995 connect to database 995 create db 994 crfs 993 drop db 994 list db 994 mklv 993 mkvg 993 mount 993 DB2 Control Center 152 DB2 database backup 988 DB2 Intelligent Miner for Data 791 DB2 restore database 990 DB2 Server db2start 698 DB2 tips 987 DB2 UDB V8.1 Fixpack 3 installation Windows 562 DB2 Warehouse External Trigger Server 844 DBA See Database administrator DBCS See Double Byte Character Set dbshut 637 dbstart 637 default organization 70, 89 Defect tracking 208 defining attributes 530 Deliverable 175 Demand chain 66 store archives 85 Demilitarized Zone 42 deploy.createdb.sql 511 deploy.populatedb.commerce.xml 511 deploy.populatedb.log 524 Deployment application asset archive (JAR) 523 store archive 520 Deployment overview 213 backup plan 215 development environment 213 practice deployment 215 production environment 215 production vs development debug 215 staging environment 214 test environment 214 DeployTool 507, 510, 514 build.xml 515 database sql scripts 510 deploy.createdb.sql 511 deploy.populatedb.commerce.xml 511 description 321 logs 524 deploy.createdb.log 524 deploy.ejb.log 524 deploy.populatedb.log 524 Descriptive attributes 92 Design patterns 122 Design phase 181 Development 326 Development environment 187, 323 WebSphere Commerce Studio 187 Development integration test 327 Development Integration Test node 326 implementation 338 software components 328 Development methodology 173 core development phases 179 definitions 174 customer 175 customer IT team 175 deliverable 175 phase 174 project database 176 project team 175 Index 1039 strategy 177 task 176 work-products 175 lifecycle 178 phases 178 deployment / launch 181 design 179, 181 development launch 179 implementation 179, 181 pre-sales 179–180 site maintenance / enhancements 179, 181 site testing 179, 181 related concepts 184 using the methodology 182 Development node 325 implementation 337 CVS client configuration 338 WebSphere Commerce Studio 338 software components 325 Direct sales 63 Direct view command 118 Disable the iPlanet servlet engine 620 Discounts 90 Display design pattern 125 DMZ See Demilitarized Zone Document of Understanding 175 DOU See Document of Understanding Double Byte Character Set 243 languages Japanese 243 Korean 243 Simplified Chinese 243 Traditional Chinese 243 Double-byte 243 DTD Generator 94, 148 Dynamic kit 93 E EAR 188 EAR project 192 application.xml 192 ibm-application-ext.xml 192 Edge Components 43, 45–46, 48, 56 EIS See Enterprise Information System EJB 1040 See Enterprise JavaBeans EJB container 43, 188 EJB project 195 ejb-jar.xml 197 EJS WLM 43 Elaboration 186 e-mail activity 90 e-mail message type 955 e-mail notification 950 e-mail notification password reset 957 e-mail transport 954 Encoding 241 abstract character set 242 character 242 character encoding form 242 coded character set 242 store pages 247 tools pages 247 Encoding Scheme 242 Encoding System 242 Enterprise Information System 887 Enterprise JavaBeans 188 Entity beans 118 EUR 229 Extractor 95, 148 F Failover 56–57 Failover support 45 Fast Load 819 Firewall 42 ForeignKeys.dtd 101, 355 Forward view command 118 Fulfillment centers 90 Function Verification Test (FVT) 327 G G11N See Globalization Ghost 338 Globalization 471 catalog content 251 definition 220 internationalization 220 localization 220 multilingual support 220 introduction 220 WebSphere Commerce 221 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide business logic 223 cultural norms 222 data 222 maintenance 223 why it is important 220 Globalization guidelines 219 catalog content 251 cultural considerations 224 messaging system 279 store design 252 tips 283 tools framework 274 WebSphere Commerce 221 WebSphere Commerce application model 237 Globalization support 39 Globalization tips handling apostrophes 283 input validation 286 locale dependent CSS 285 NL cmd parameters via hidden forms 287 NL enabled alert/confirm boxes 285 special characters 283 glyph 242 Groupings 39 H HACMP 45 Horizontal scaling 42–46, 57 Hosting 64 store archives 85 Hosting.sar 85 HTTP Browser adapter 895 HTTP PVC adapter 895 HTTP request servlet 114, 894 HTTP requests 894 HTTPServletRequest object 119 Hub 67 I I18N See Internationalization IBM Directory Server 34 IBM eServer iSeries 4 pSeries 4 zSeries 4 IBM HTTP Server 6 configuration certificate 592 create certificate 720 create key database 719 enable SSL in httpd.conf 719 key database 719 start 721 configure httpd.conf for SSL 688 create administrator 687 create key store database 689 create self-signed certificate 690 create system user and group 687 installation Windows 588 verification 691 IBM HTTP Server and WebSphere plug-in 686 IBM Method 185 ibm-application-ext.xml 192 ibm-ejb-jar-bnd.xmi 197 ibm-ejb-jar-ext.xmi 197 ibm-wc-load.xml 104 ibm-web-bnd.xml 194 ibm-web-ext.xml 195 id command 982–983 ID Resolver 94, 148 IEC See International Electrotechnical Commission IMAP 888–889 Implementation phase 181 Inbound messaging 889 add new message 896 add new message for MQ 936 components 889 sys_template.xml 898 system walkthrough for MQ 896 user_template.xml 898 Inception 186 ins_fact_visits.sql 814 Installation add Database Server node Windows 582 add Web Server node Windows 587 AIX AIX installation 680 IBM HTTP Server and WebSphere plug-in 686 scenarios and planning 676 Web Server node 685 WebSphere Commerce 723 Index 1041 CVS for NT 331 DB2 AIX 691 Windows 582 DB2 Server node AIX 691 DB2 UDB V8.1 Fixpack 3 Windows 584 IBM HTTP Server Windows 588 Oracle9i Client Solaris 640 Oracle9i Enterprise Edition Solaris 623 WebSphere Commerce DB 634 OS/400 configuration 765 Configuration Manager client 768 pre-installation 758 PTF installation 763 start Configuration Manager 769 WebSphere Commerce instance creation 771 scenarios and planning why multi-tier 554 Windows 554 single-tier Windows 559 Solaris 970 scenarios and planning 600 Solaris installation 606 Sun ONE Web Server Solaris 611 WebSphere Commerce Payments node AIX 698 WebSphere Commerce Studio 1008 WebSphere MQ 911 WebSphere plug-in Windows 588 WebSphere Studio Application Developer PTF 1010 WebSphere Studio Application Developer V5.0.1 Interim Fix 3 1013 WebSphere Test Environment 1012 instance components WebSphere Commerce 137 instance_name.xml 119, 894, 937, 945 International Electrotechnical Commission 244 International Organization for Standards 244 1042 Internationalization 220 Internet Service Provider (ISP) 64 Inventory 90 Inventory subsystem 40 IP sprayer 43–45, 56–57 iPlanet servlet engine disable 620 iPlanet Web Server 599 configuration certificate trust db 618 server certificate 618 installation WebSphere plugin 621 See Sun ONE Web Server start 615 ISO See International Organization for Standards ISO Latin 1 244 ISO/IEC 10646 244 IT architect 15 IT specialist database administrator 163 site administrator 160 store administrator 162 system administrator 158 IT specialist roles and tools 158 ITSO B2B working example 291 build 505 build and deployment overview 506 build procedure 507 application assets (JAR) 514 build verification test 516 check-out source from CVS 508 modify build script and unpack descriptor 508 source configuration management 517 business scenario 292 customer types 292 product brands 292 product media types 294 products 293 customize catalog data 360 development ITSO catalog 360 pruned ITSO catalog 363 customize catalog images 365 customize store 393 configure e-mail transport 403 configure scheduler for batch job 493 create batch e-mail command 482 create new commands 438 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide create new data access beans 408 create new data bean 463 create new database table 406 create new JSPs 470 import e-mail template 491 overview 394 pre-conditions 402 solution design 394 testing price watch 498 deployment 505 deployment procedure application asset archive (JAR) 522 publish store archive 520 manage the ITSO store 527 contracts 380 requirements analysis 295 initial context 297 REQ01 contracts 296 REQ02 Price Watch 296 REQ03 Product management 296 REQ04 Commerce analytics 296 REQ05 Register customers via MQ 296 REQ06 e-mail notifications for password reset 296 requirements 296 system context 298 use case model 301 solution design 310 component model 312 ITSO site navigation 315 site catalog hierarchy 317 systems architecture 310 ITSO sample code 319 description 320 download 320 prepare sample code and scripts 321 ITSO scenario system context 298 ITSO.sar 516 J J2EE application server 188 J2EE Connector Architecture 887 JAF 889 James See Java Apache Mail Enterprise Server Java 2 Enterprise Edition (J2EE) 112 Java Activation Framework (JAF) 889 Java Apache Mail Enterprise Server 950 Java Message Service 885 Java programmer 16 Java project 197 JavaBeans Activation Framework 889 JavaMail 888–889 JavaServer Pages 188 JCA See J2EE Connector Architecture JCA-JMS 921 JD Edwards 887 JIS 242 JMS See Java Message Service JMS queues JMSErrorQueue 925 JMSInboundQueue 925 JMSOutboundQueue 925 JMSParallelInboundQueue 925 JMSSerialInboundQueue 925 JMSQueueConnectionFactory 923 JNDI Name 924 JSP templates 119 Jurisdictions 90 JVM 42, 46, 55 L L10N See Localization Language table 238 Languages 90 LDAP 34, 36, 38 Line-of-business (LOB) user 17 Line-of-business user roles business relationship roles 165 account representatives 165 channel manager 165 sales manager 165 customer service 166 customer service representative 166 customer service supervisor 166 marketing manager 166 operational roles 166 buyer 168 buyer administrator 168 buyer approver 168 logistics manager 167 operations manager 167 Index 1043 pick packer 167 procurement buyer 168 procurement buyer administrator 168 receiver 167 returns administrator 167 seller 167 seller administrator 168 organizational management roles 168 product management 169 buyer 169 category manager 169 product manager 169 product merchandising 169 Line-of-business user roles and tools 165 Linux IBM eServer iSeries 4 IBM eServer pSeries 4 IBM eServer zSeries and S/390 4 Red Hat 4 SuSE 4 Load Balancer 43 Load Balancer node 48 Load balancing 45, 55 Loader 95, 148 Loader Package 94, 147 components DTD Generator 148 Extractor 148 ID Resolver 148 Loader 148 Text Transformation Tool 147 DTD Generator 94 Extractor 95 ID Resolver 94 Loader 95 Text Transformation Tool 94 XML Transformation Tool 94 XSL Editor 94 Loader Packager components XML Transformation Tool 147 XSL Editor 147 LOB See line-of-business user Locale add a new locale 368 Locales 82 WebSphere Commerce 368 Localization 220 1044 Logistics manager 167 Lotus QuickPlace 34 Lotus Sametime 33 M Macro design 181 mail.jar 889 Maintainability 46 Manage the ITSO store 527 Managed data 88, 90 ManagePriceWatchList controller command 395 Managing orders 156 Managing returns 156 Map messages to command parameters 898 map.mapxmi 197 Marketing 155 Marketing manager 166 Marketing subsystem 40 martuser user 810 Master catalog 92 Match topics to roles and skills 17 Matching skills to customization needs 130 Max Connections 925 Member groups 35 Member security services 36 Member subsystem 35 security services 36 single sign-on 38 user registration 35 MemberRegistrationAttributes.xml 378 Members 35, 90 Merchandising 155 Merchandising associations 39 Merchandising subsystem 40 Merchant 65 Messaging architecture 884 inbound messaging 884 leveraging WebSphere Application Server 885 outbound messaging 884 Messaging integration 33 Messaging integration with e-mail 883 Messaging integration with MQ 883 Messaging subsystem 40, 883 enable trace message components 927 Inbound example Create_ITSO_Customer.dtd 937 Create_ITSO_Customer.xml 937 instance_name.xml 937 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide user_template.xml 937 UserRegistrationAdd command 937 outbound messaging 900 predefined messages 906 XML parser plugin 893 Messaging system globalization 279 Micro design 181 Microsoft Internet Information Server 6 MIME 889 mkdir command 982 mklv 993 mkvg 993 modelorg.xml 376 modelorg_en_US.xml 376 modelorgrole.xml 376 Model-View-Controller design pattern 122 mount 993 MQ 36 MQ JMS Provider queue connection factory 923 MQ JMS Provider queue destinations 925 MQ listener 114 MQ transport 933 MQ_INSTALL_Root env variable 927 mqbrkrs 702 mqm 702 mqm group 921 Multilingual support 220 N Name formatting 234 Native2Ascii tool 256 Navigational catalog 92 Net8 1000 Network zones 48 NNTP News server 950 Number formatting 230 Number usage 264 O offering.xml 360 Online registration 35 OpenSSH 967 Operational data 88, 90 Operations manager 167 Oracle9i check status of listener 999 commands and tasks 998 create database 634 Database Configuration Assistant 1001 global database name 634 listener 634, 999 Net8 Configuration Assistant 1000 start listener 999 start server 998 stop listener 999 stop server 998 tips 997 where to find information 1004 Oracle9i Client installation Solaris 640 Oracle9i EE Server installation Solaris 623 Oracle9i Enterprise Edition 599 database tuning 636 Order subsystem 40 organization 69, 89, 536 Organizational entity 35 Organizational structure 69, 89 Organizational unit 35, 69 OS/400 create WebSphere Commerce Payments instance 775 enable SSL for IBM HTTP Server 777 PTF installation 763 publish a store 780 scenario and planning 756 start application servers 777 updating SQL packages 766 WebSphere Commerce 755 Outbound messaging 900 add new outbound message 905 components administration and management services 901 composition services 902 runtime services 902 system walkthrough for MQ 903 P Package store archive 348 add Ant build scripts 347 extract store archive to SARFile folder 348 Index 1045 package store archive 348 publish store archive 350 Patterns for e-business 48 Payment 90 Performance 42 Persistence database 46 memory-to-memory 46 Persistent object model 126 Personalization 33 Phase 174 Pick packer 167 Platform support 4 AIX 4 Linux 4 OS/400 4 Solaris 4 Windows 2000 4 plugin-cfg.xml 30, 894 pop_browser.sq 814 POP3 888–889, 950 Pre-built kit 93 Precompile JSPs 578, 743 Pre-sales phase 180 Presentation layer 188, 191 stores 191 WebSphere Commerce Accelerator 191 WebSphere Commerce Administration Console 191 WebSphere Commerce Organization Administration 191 Price watch configure e-mail transport add new message to database 403 configure e-mail transport and message type 405 James SMTP server 403 configure scheduler 495 make command schedulable 494 create batch e-mail command command interface 483 implementation class 483 import data bean for e-mail command 489 register command 490 create commands 438 access control policies 461 add task commands to workspace 449 command interface 438 enable component tracing 463 1046 implementation class 439 PriceWatchListDisplayCmd 450 register command 449 task commands 454 create data access beans access bean for entity bean 428 add new FinderHelpers 434 EJB/RDB mapping 425 entity beans 409 generate deploy code 429 create data bean data bean types 463 further considerations 466 create JSPs 470 globalization 471 modify item display JSP 481 register view of JSP 480 site header 482 create new database table 406 import e-mail template add JSP to workspace 491 JSP content 491 register view for e-mail template 493 overview 394 pre-conditions 402 solution design access control 402 controller commands 398 data access 397 data storage 396 e-mail template JSP 402 passing data to the JSP 400 price watch list JSP 401 solution limitations 396 solution overview 395 task commands 399 use cases 395 testing 498 Prices 90 PriceWatchAdd task command 395 PriceWatchBean data bean 395 PriceWatchDelete task command 395 PriceWatchDeleteAll task command 395 PriceWatchEmail.jsp 395 PriceWatchEmailBean data bean 395 PriceWatchList task command 395 PriceWatchList.jsp 395 PriceWatchListDisplay controller command 395 Processing layer 188, 190 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide sub systems catalog 190 enablement 190 marketing 190 member 190 merchandising 190 order management 190 payment 190 trading 190 Procurement buyer 168 Procurement buyer administrator 168 product 92, 529 Product management 528 add a category 528 add a product add price to product 532 add product 529 add SKU 531 define attributes 530 verify product display page 532 Product manager 169 Product packaging WebSphere Commerce 4 WebSphere Commerce Studio 6 product price 532 Program adapter 116, 895 Programming model 109 overview 110 business components 111 business objects 111 business processes 111 controls and view 111 database 110 store models 112 Project database 176 Project manager 15 Project team 175 Promote steps 848 Protocol listeners 114 HTTP request servlet 114 MQ listener 114 Protocol provider 888 ps command 982 Publish a store 97 OS/400 780 technical details 100 data considerations 105 execute publish job 104 instantiation during publishing 104 publish parameters 101 register a store 101 schedule job 104 troubleshooting 106 unpack store archive 102 user perspective 97 Publish store archive compile JSPs 522 create test transaction 522 prepare environment for store publish 520 publish store archive 521 verify payment 522 publishNLS.properties 101 Q Queue Manager 924 R Rational Unified Process 185 Construction 186 Elaboration 186 Inception 186 Transition 186 Receiver 167 Red Hat Enterprise Linux AS V2.1 4 Redbooks Web site Contact us xxvii Redirect view command 118 Reporting and business intelligence 156 Reporting framework 790 Request for quote (RFQ) 155 Required skills 15 Resource bundles 255 Resource skill level 178 Restore DB2 database 990 Returns administrator 167 Roles 15 database administrator (DBA) 16 database schema owner 16 IT architect 15 Java programmer 16 line-of-business user 17 project manager 15 tester 17 Web developers 17 WebSphere Commerce site administrator 16 WebSphere Commerce store administrator 16 root organization 70, 89 Index 1047 Runtime architecture 27 Runtime environment 27 Runtime topology selection criteria 41 availability 44 failover support 45 maintainability 46 performance 42 scalability 43 security 41 session management 46 throughput 42 Runtime topology selection summary 47 RUP See Rational Unified Process S Sales managers 165 SAP 887 Scalability 43 Scheduler adapter 116, 895 SCM See Source Control Management Security 41 Seller 167 Seller Administrator 168 Sellers 90 Server groups 42 Server project 198 Service agreements 77 Service provider 889 Servlet engine 114, 894 session affinity 57 Session control 38 Session management 46 Session Manager 38 Session types 38 shipfulfill.xml 384 Shipping 90 shipping.xml 384 showrev 610 shutdown 966 Shutdown on Solaris 982 Single sign-on 38 Site administration WebSphere Commerce 133 Site administrator 160 Site maintenance and enhancements 181 Site testing phase 181 1048 SKU 92–93, 531 SMTP 888–889, 950 Solaris commands showrev 610 common tasks and commands 982 configuration 977 installation 606, 970 maintenance update 607 recommended patches 608 WebSphere Commerce 599 where to find information 986 Solaris 8 configuration 977 information 986 maintenance update 978 recommended patches 980 tasks and commands 982 tips 969 Solution outline 181 Source Control Management 205 SOW See Statement of Work Statement of Work 175 Static kit 93 Store 89 add store front files to CVS 388 add/delete language for store archive 271 assets 78 catalog data catalog.xml 360 create 341 customize 393 customizing 96 data 79 configuration data 90 core data 89 instance data 88 managed data 90 operational data 90 data architecture 88 globalization design 252 globalization support 82 localization of assets 263 currency 264 language 263 shipping 265 taxes 267 new display format 268 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide optional customization business policies 381 contracts 381 currency 367 shipping 384 shipping prices 384 taxes 384 terms and conditions 381 publish to WebSphere Test Environment 336 publish to workspace 384 required customization 354 catalog data 360 hardcoded references 357 store address 359 store directory 354 store front-end assets 366 store identifier 354 resource bundles 256 store-refs.xml expose publish parameters 356 Store administration WebSphere Commerce 133 Store administrator 162 Store architecture 78–79 Store archive 82 add languages 271 build 516 contents 82 descriptors 82 front end assets 82 store data 82 deployment 520 package 343 publish 520 verify 343 Store archives B2B direct 83 Consumer direct 83 Consumer direct basic 83 demand chain 85 hosting 85 Supply chain 86 Store catalog hierarchy 317 Store configurations 80 Store customization advanced 131 basic 130 intermediate 131 Store data architecture 88 configuration data 88 core data 88 managed data 88 operational data 88 WebSphere Commerce instance data 88 Store data architecture figure 88 Store data assets 87 Store front assets 78, 129 Store identifier 355 Store navigation 315 Store organizational hierarchy 317 Store packaging 82 store-catalog.xml 360 store-catalog-shipping.xml 360, 384 store-catalog-tax.xml 360, 384 storeorg.xml 376 store-refs.xml 101, 356 stores_r table 850 Strategy 177 Subsystems 34 Sun ONE Enterprise Web Server 599 Sun ONE Web Server 6 Sun One Web Server configuration enable SSL 615 Sun Solaris 599 Sun SPARC 970 Supply chain 68 store archives 86 Supported database servers 6 IBM DB2 UDB 6 Oracle9i 6 Supported software by edition 5 Supported units of measure 90 Supported Web servers 6 IBM HTTP Server 6 Microsoft Internet Information Server 6 Sun ONE Web Server 6 SuSE Linux Enterprise Server V8 4 SVRMGR 638 sys_template.xml 898 System administrator 158 System context 298 System Verification Test (SVT) 327 SystemErr.log 510 Systems architecture 27 Index 1049 T Tail 982 Task 176 Task command 117 tax.xml 384 Taxes 90 taxfulfill.xml 384 Team development 202 add files to CVS 353 add store front files to CVS 388 build environment overview 209 create CVS module 351 defect tracking 208 deployment overview 213 environment overview 202 ideal work flow 204 implement development environment 323 import store assets into CVS 350 optimistic team model 203 resource 206 scenario 324 Build and SCM node 324 Development Integration Test node 326 Development node 325 setup additional development nodes 388 source control management 205 Terms and conditions 77 Test Build Verification Test 327 customer acceptance test 327 development integration test 327 Function Verification Test 327 System Verification Test 327 unit test 327 Tester 17 Text Transformation Tool 94, 147 Throughput 42 Time format 227 Tivoli Web Site Analyzer 791 Tools and store data 93 Loader Package 94 summary of tools 95 WebSphere Commerce Accelerator 95 WebSphere Commerce Administration Console 95 WebSphere Commerce Organization Administration Console 95 WebSphere Commerce Studio 94 Tools framework 1050 globalization 274 Tracing enable for messaging 927 Trading subsystem 39 Transition 186 Troubleshooting tips DB2 database backup 988 restore DB2 database 990 U UCS See Universal Character Set UCS-2 245 Unicode 223, 244 Unicode Transformation Format 245 Unit test 327 Universal Character Set 245 unpack descriptor modification 509 unpack.xml 103, 508–510 Update Installation Wizard 1020 updateWizard.bat 1020 URL registry 90 URL rewriting 38 US-ASCII 242 USD 229 Use case model 301 actors defined 301 ITSO B2B working example UC-A01 create a contract 306 UC-A02 add a category 307 UC-A03 add a product 307 UC-A04 generate commerce analytics reports 308 UC-A05 register customer via MQ 308 UC-A06 password reset e-mail notification 310 UC-PW01 display price watch list 303 UC-PW02 add item to price watch list 304 UC-PW03 delete item from price watch list 305 UC-PW04 delete all items from price watch list 305 UC-PW05 check price watch and e-mail customers 306 User registration methods 35 LDAP 36 Loader package 36 MQ 36 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide online 35 user_template.xml 898, 937–938 USERREG table 949 UserRegistrationAdd command 937 Users 35 usrtraffic_r 814 UTF See Unicode Transformation Format UTF-16 244–245 UTF-8 243–245 V Value chains 65 Verification IBM HTTP Server 593, 691 remote Web server configuration 598 WebSphere Commerce AIX runtime 747 WebSphere Commerce Studio 1028 Vertical scaling 42–44, 56–57 View command 118 View registry 90 VMWare 338 W wasgroup 702 wasuser 702 WCA group 810 WCAADMIN group 810 Web controller 116, 895 Web designer 17 Web developer 17 Web project 193 Java Source 193 Web Content 193 Web Content/WEB-INF 194 Web server plugin 57 WLM 43 web.xml 194 WebSphere Application Server 41 Administration Console 150 application server processes 42 base edition 41 configuration JCA-JMS for MQ 920 horizontal scaling 42 Network Deployment Edition 41, 44 verification 568 vertical scaling 42 WebSphere Application Server V5 Fixpack 1 installation Windows 563 WebSphere Application Server V5.0.1 Fixes installation Windows 566 WebSphere Business Portals 34 WebSphere Commerce Accelerator 142 Administration Console 139 administration tools 28 AIX 675 installation 723 Business Edition 13 features 13 business interaction engine 28 Business models 62 business models B2B direct 63 Consumer direct 63 Demand chain 66 Hosting 64 Supply direct 68 commands 117 common server runtime 28 configuration e-mail message type 955 e-mail transport 954 Configuration Manager 134 create instance 733 OS/400 771 create non-root users 702 development methodology 173 e-mail notification 950 globalization 219, 221 inbound messaging system 889 information 20 instance components 137 instance creation Solaris 650 Windows 571 instance data 88 instance properties 136–137 Loader Package 94, 147 messaging architecture 884 messaging subsystem 883 MQ transport 933 organizational structure 69 Index 1051 OS/400 755 outbound messaging 900 post-instance creation Solaris 659 precompile JSPs 578 AIX 743 prepare Oracle database 634 Professional Edition 8 features 8 programming model 109 runtime topologies load balancing 56 map to implementation details 56–57 single-tier 50 three-tier 52 two-tier remote Database server 50 two-tier remote Web server 51 vertical application server cluster 54 scheduler 148 Server 79 site administration 133 site administrator 16, 160 software components 28 Database Server 31 enablement software 33 Web Server 30 WebSphere Application Server 31 WebSphere Commerce Payments Server 32 WebSphere Commerce Server 32 Solaris 599 start servers Windows 575 store assets 78 create 341 data architecture 88 supported locales 368 store administration 133 store administrator 16, 162 store architecture 78 subsystems 28, 34 Catalog subsystem 39 Inventory subsystem 40 marketing subsystem 40 Member subsystem 35 Merchandising subsystem 40 Messaging subsystem 40 Order subsystem 40 1052 Trading subsystem 39 tools 134 compile JSPs 578, 743 unicode usage 246 value chains 65 verification runtime and store 577 Windows 553 WebSphere Commerce .xml 119 WebSphere Commerce Accelerator 142 functionality sales 144 store 143 WebSphere Commerce Administration Console 139 functionality 140 access management 142 configuration 140 logistics 145 marketing 144 payments 140 products 144 rules service 142 security 140 store archives 141 WebSphere Commerce Analyzer 787 access out-of-box reports 864 analytics to action 795 architecture 798 business options configuration 852 components 799 configure datasource to datamart 862 create customized report 868 custom load 819 data capture 844 data mining configuration 832 datamart 826 Datasource 807 enable WebSphere Commerce instance 806 fast load 814, 819 features data mining tools 790 data structuring tools 790 datamart 790 reporting framework 790 features by release 790 implementation WebSphere Commerce Analyzer node 809 WebSphere Commerce node 804 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide integration 801 scenario 802 more information 800 post-configuration steps 859 prepare promote steps 837 promote steps 848 replication options 819 reports overview business intelligence reports 793 framework 792 integration kits 794 operational reports 792 run replication and extraction 860 schedule replication and extraction 861 software components 792 start data capture 859 start trigger server 859 WebSphere Commerce application model business components 237 business objects 237 business processes 237 controls and views 237 data model input 247 data model output 250 database 237 encoding 241 models 237 unicode 244 WebSphere Commerce instance 79 WebSphere Commerce instance data 88 WebSphere Commerce Java programmer 16 WebSphere Commerce Organization Administration Console 145 functionality access management 146 approvals 146 WebSphere Commerce Payments AIX 698 create instance 716 OS/400 775 instance creation Windows 573 WebSphere Commerce Payments Console 149 WebSphere Commerce Server application development presentation layer 188 processing layer 188 components subsystems 34 WebSphere Commerce Server framework adapter manager 115 adapters 115 commands 117 Data Bean Manager 119 data beans 119 entity beans 118 HTTP request servlet 114 instance_name.xml 119 JSP templates 119 MQ listener 114 protocol listeners 114 request device types 115 servlet engine 114 Web Controller 116 WebSphere Commerce Server instance 79 WebSphere Commerce Sever framework 112 WebSphere Commerce site administrator 16 WebSphere Commerce Store Administrator 16 WebSphere Commerce Studio 187 Business Developer Edition 6 configuration 1021 default Web browser 1027 payment methods 1025 reduce DB2 memory requirement 1025 update API docs 1024 update data source 1023 custom code packaging 201 development environment 187 Express Developer Edition 6 implementation 1005 DB2 UDB V8.2 Fixpack 3 1014 install Toolkit V5.5.0.2 Fixpack 1016 install WebSphere Commerce Studio 1006 WSAD V5.0.1 PTF 1010 WTE V5.0.1 1012 installation 336 overview 188 plugins 198 API reference 200 Configuration Manager 198 online help 199 Professional Developers Edition 6 verification 1028 workspace 188–189 EJB project 189 elements 191 Java projects 189 WAR project 189 Index 1053 workspace backup 344 WebSphere Commerce V5.5 installation Windows 561 WebSphere Commerce V5.5.0.2 Fixpack installation Windows 569 WebSphere Internal Messaging 46 WebSphere MQ 896 bindings mode 913 client-server mode 913 configuration 916 IH03 test tool 948 installation 911 scenario 912 WebSphere Commerce configuration 932 WebSphere plug-in 30 WebSphere plugin installation 588 WebSphere Studio Application Developer 188, 1005 create project 345 WebSphere Test Environment 188, 1005 publish store 336 WebSphere Update Installer V5.0.x 564 Windows installation add remote Database Server node 582 add remote Web Server node 587 IBM HTTP Server 588 single-tier 559 WebSphere Commerce prerequisites 560 WebSphere Commerce 553 WLM EJS 43 See also workload management Web server 43 Web server plug-in 43 Work products 175 Workload management 55, 57 See also WLM 43 XML Transformation Tool 94, 147 XPRICEWATCH database table 395 XPriceWatch entity bean 395 XSL 147 XSL Editor 94, 147 XSLT 147 X X11.adt.motif AIX required fileset WebSphere Application Server 682 XML 147 XML parser plugin 893 1054 WebSphere Commerce V5.5 Handbook Customization and Deployment Guide WebSphere Commerce V5.5 Handbook Customization and Deployment Guide (2.0” spine) 2.0” 2.498” 1052 1314 pages Back cover ® WebSphere Commerce V5.5 Handbook Customization and Deployment Guide Runtime architecture, programming model, business and store models overview Team development scenario to create, customize, build, deploy and manage a store Implement advanced multi-tiered runtime configurations Integrate MQ, e-mail, and Commerce Analyzer This IBM Redbook provides IT architects, IT specialists, and developers with the critical knowledge to design, develop, implement, deploy, and manage a WebSphere Commerce V5.5 runtime environment and store. This book includes the following: Introduction to the WebSphere Commerce runtime architecture, programming model, business and store models. Development guidelines for e-commerce development methodology, development environment, build cycle and globalization. ITSO B2B working example, including a business requirements analysis and solution design, and how to implement a team development environment, create and customize a store, and build, deploy and manage a store. Deployment scenarios for implementing advanced multi-tiered runtime scenarios on Windows, Solaris, AIX and OS/400. Integration and customization with MQ, e-mail and WebSphere Commerce Analyzer. The appendixes include procedures and tips on AIX, Solaris, DB2, Oracle and WebSphere Commerce Studio implementation. SG24-6969-00 ISBN 0738499439 INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment. For more information: ibm.com/redbooks Report "WebSphere Commerce V5.5 Handbook, Customization and Deployment Guide 9780738499437" × --- Select Reason --- Pornographic Defamatory Illegal/Unlawful Spam Other Terms Of Service Violation File a copyright complaint Close Submit Unsere Partner sammeln Daten und verwenden Cookies zur Personalisierung und Messung von Anzeigen. Erfahren Sie, wie wir und unser Anzeigenpartner Google Daten sammeln und verwenden. Cookies zulassen