Microsoft Reference Architecture for Commerce Version 2.0 (Pro-Other)

Reference Architecture for Commerce Version 2.0 Developer’s Guide

ISBN: 0-7356-1826-7 The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication. This Documentation is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AS TO THE INFORMATION IN THIS DOCUMENT. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. The example companies, organizations, products, people and events depicted herein are fictitious. No association with any real company, organization, product, person or event is intended or should be inferred. © 2001 Microsoft Corporation. All rights reserved. Microsoft, FrontPage, MSDN, Outlook, PowerPoint, SideWinder, The Age of Kings, Visual Basic, Visual C++, Visual InterDev, Visual Studio, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Contents Part 1

Getting Started

1

Chapter 1

Introduction to the Reference Architecture What Is the Reference Architecture? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What’s New in this Version? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is the Developer’s Guide? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Who Should Read this Guide? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Roadmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support for the Reference Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3 3 4 5 5 6 8 8

Chapter 2

Installing the Software

9

Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Installing the Prerequisite Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Install Microsoft Windows 2000 Server and MSMQ . . . . . . . . . . . . . . . . . . . . . . . . 10 Install Commerce Server 2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Install Microsoft XML Parser 3.0 SP 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Install the Developer Tools (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 After You Install the Prerequisite Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Installing the Reference Architecture Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Download the Reference Architecture Application . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Create and Configure the Business Desk Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Create and Configure the Web Site Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Create a New Web Site to Host the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Create a New Web Site to Host the Commerce Server 2000 Business Desk . . . . . . 14 Start the Application Installer Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Install and Configure the XSL ISAPI Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Unpack the Commerce Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Import the Predictor Modeling Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Configure the Business Desk Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Configure the Pipeline Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Configure the Queued E-mail Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Create the Business Desk Console for the Application . . . . . . . . . . . . . . . . . . . . . . 20

iv

Contents

Configuring the Commerce Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Import, Modify, or Delete Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configure Tax Rates and Shipping Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . Test the Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distributed Deployment Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing the Application in a Distributed Environment . . . . . . . . . . . . . . . . . . . . . . . Production Environment Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

20 20 22 22 22 22 23

Part 2

System Architecture

25

Chapter 3

Business Requirements and Design Model Requirements That Affect Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ease of Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Anonymous Shopping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Strong Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support for Multiple Device Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manageability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reference Architecture Application Business Requirements . . . . . . . . . . . . . . . . . . . . Functional Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Production Environment Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Documenting the Business Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The MSF Application Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Why Use the MSF Application Model? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MSF Application Design Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

27 27 28 28 30 30 31 31 32 32 32 38 38 39 39 40 40 41

Chapter 6

Physical Design Phase The Research Effort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Identifying Physical Solution Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Identifying Existing Candidate Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Analysis and Rationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Existing Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Meeting the Business Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Identifying the Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

61 61 62 68 71 71 78 82 82 82 82

v

Contents

Part 3

Solution Implementation

83

Chapter 7

Implementation Overview

85

Implementation Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Recommended Background Knowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Technology Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML in the ConsolidatedRetail.com Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ASP Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Commerce Server Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stored Procedures in the Data Tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client-Side Scripting for Input Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

85 85 86 86 87 88 88 88 89

Chapter 8

Solution Roadmap

91

PASP Files and the XSL ISAPI Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 A Simple Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Web Site Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Initialization Pages and Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Catalog Browsing Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 User Authentication and Profile Management Pages . . . . . . . . . . . . . . . . . . . . . . . . 97 Order Management Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Commerce Server Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Utility and Configuration Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Catalog Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 User Management Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Shopping Basket Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 The Predictor Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Pipelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Pipeline Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Custom Business Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Chapter 9

ConsolidatedRetail.com Functionality Presentation Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML Output from the PASP Files in ConsolidatedRetail.com . . . . . . . . . . . . . . . . . XML Helper Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XSL Style Sheets in the ConsolidatedRetail.com Site . . . . . . . . . . . . . . . . . . . . . . Rendering Index.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Caching Commonly Used Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

105 105 106 107 108 110 115

vi

Contents

User Authentication and Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registering a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Authenticating a User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Passport Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving and Updating Profile Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Product Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Catalog Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Browsing the Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Searching the Catalogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a New Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Shopping Basket Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Products to the Shopping Basket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing the Shopping Cart or Save for Later Basket . . . . . . . . . . . . . . . . . . . . . . . Order Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Shipping Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying a Shipping Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Multiple Shipping Addresses and Methods . . . . . . . . . . . . . . . . . . . . . Specifying Payment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Confirming the Order Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Completing the Order Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

120 121 123 126 128 133 133 135 148 151 151 152 154 166 166 169 171 173 176 181 184

Chapter 10

Debugging and Testing Debugging the Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Debugging XML Output from PASP Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Debugging a Custom Site Built on the Reference Architecture . . . . . . . . . . . . . . . . . . Developing a Test Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Possible Test Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Possible Test Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Functional Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing Methodology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Response Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Throughput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance Testing Tools and Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance Testing Methodology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

185 185 186 192 193 193 194 196 196 199 199 200 200 201 208

Contents

vii

Part 4

Appendices

209

Appendix A

XML Output from ConsolidatedRetail.com Acct.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AddressBook.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AddtoList.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AddtoListResp.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basket.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Category.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ChangePasswd.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CreditCards.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DeleteAddressBook.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EditAddressBook.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EditCreditCard.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ForgotPasswd.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ListBase.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ListSearch.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Login.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MultiShipping.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OrderHistory.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OrderHistoryDetail.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OrderSummary.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Payment.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Product.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registration.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SearchResults.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Shipping.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ShippingMethod.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . StepSearch.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ThankYou.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UserProfile.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

211 212 213 214 214 215 216 218 219 220 222 227 232 233 234 235 236 238 239 240 242 244 246 248 249 253 254 255 261 263

Appendix B

Data Field Validation Data Fields That Require Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Validation Is Performed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ListSearch.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . StepSearch.pasp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Search Text Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

265 265 267 271 272 272

viii

Contents

Appendix C

Sample Detailed Test Plan Assumptions and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Test Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Registration and Authentication Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Banner Advertisement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

273 273 275 275 279 281

Appendix D

Sample Detailed Test Cases

283

Index

291

Part 1 Getting Started Part 1 of the Developer’s Guide for the Microsoft® Reference Architecture for Commerce, version 2.0, describes the Reference Architecture components and objectives, the appropriate audience for this guide, and the document conventions used. Most importantly, it provides a roadmap to the remainder of the guide, segmented by audience role, as well as procedures for installing the Reference Architecture application and other required software. Part 1, “Getting Started,” consists of the following: ● Chapter 1, “Introduction to the Reference Architecture” ● Chapter 2, “Installing the Software” You should review this section prior to reading other chapters in the Developer’s Guide.

1 Introduction to the Reference Architecture Welcome to the Developer’s Guide for the Microsoft® Reference Architecture for Commerce, version 2.0. The Microsoft Reference Architecture for Commerce consists of engineered code components that allow developers to build retail Web sites using the Microsoft® Windows® 2000 Server operating system and Microsoft® .NET Enterprise Servers, such as Commerce Server 2000 and SQL Server™ 2000. This guide is designed to aid your understanding of the design and implementation decisions made by the developers of the Microsoft Reference Architecture application, and to help you create great e-commerce solutions using Microsoft tools and technologies.

What Is the Reference Architecture? The Microsoft Reference Architecture for Commerce consists of code and documentation designed to accelerate the development of e-commerce solutions for small to medium businesses. It includes: ● An e-commerce application, ConsolidatedRetail.com, that contains reusable and customizable components and is designed to address many of the general business requirements that are common to e-commerce solutions. ● Complete documentation, including a thorough explanation of the application components and the decisions behind the code design and development process, instructions for using, modifying, and testing the code, and procedures for setting up the development environment and installing the application. The Reference Architecture e-commerce site is designed to allow a retailer to extend its customer base using the Internet, while providing an effective, compelling online purchasing experience for customers. It is also designed to automate as many of the

4

Reference Architecture for Commerce

business processes involved in selling products as possible. While there are many sector-specific considerations in the retail industry, the design of the e-commerce site is reasonably generic so that it can be adapted for any e-commerce solution, regardless of the industry or products involved. The Reference Architecture code components include Active Server Pages (ASP pages, configuration files, Extensible Stylesheet Language (XSL) style sheets, and COM+ components that developers can examine to learn how to implement an effective e-commerce solution. In addition, the application provides clearly documented code and reference materials that assist developers who want to reuse or extend the software components provided. Many of the software artifacts can be reused with little or no adaptation. Note: For instructions about how to install the Reference Architecture application, please read Chapter 2, “Installing the Software.”

What’s New in this Version? Version 2.0 of the Reference Architecture adds the following functionality: ● Support for Microsoft Passport authentication, as well as procedures for adding other authentication methods. ● Support for the Commerce Server 2000 Basket Templates, which allows users to create, manage, and use current Order and Save for Later shopping baskets, and public and private shopping lists. ● Advanced Search, which provides complex search capability. ● Wizard browsing, which allows customers to go from one product detail page to the next when browsing products. ● Personalization, which allows dynamic site content generation based on a user profile. ● Payment Manager, which allows users to select and save a payment option. ● Order cancellation, which allows customers to cancel orders. ● Support for the Commerce Server 2000 Predictor, which facilitates discount and directed advertising using e-mail. ● Directed e-mail support, which allows online merchants to generate e-mail messages based on specific business rules, and provides offline processing of bulk e-mail using COM+ queued components. ● Event capture, which extends data warehousing to capture defined events. ● Enhanced documentation, including explanations of the new functionality, an explanation of the caching mechanisms, and examples of detailed test plans and detailed test cases.

Chapter 1: Introduction to the Reference Architecture

5

What Is the Developer’s Guide? The Developer’s Guide is intended to provide the necessary explanatory information to help you understand how the Reference Architecture for Commerce is designed and implemented, and to give technical and architectural justifications for the design decisions made in the building of the application. You should use this document as your roadmap to the Reference Architecture components, and refer to it when examining the source code and installing and configuring the site. Note, however, that this documentation is not intended to be a complete programming reference, nor is it intended to replace documentation provided with prerequisite software, such as Windows 2000 Server, Commerce Server 2000, or SQL Server 2000, or the documentation that accompanies developer tools. Developers using the code and documentation provided in this Reference Architecture should adhere to standard coding and testing practices, and should test any site thoroughly before attempting to deploy it in a production environment.

Who Should Read this Guide? As the title indicates, the Developer’s Guide is targeted primarily at application designers and developers. However, other readers involved in scoping, designing, and implementing e-commerce applications will find that it contains relevant and useful information. There are many roles in software development, and each person involved in the project requires different types and levels of information (you can learn more about the roles involved in a software development project by reviewing the Microsoft Solutions Framework Team Model). Readers in the following roles will find this document particularly useful. (Examine the descriptions in the following table to determine your role, and then refer to the “Document Roadmap” section later in this chapter to locate information that is relevant to your particular responsibilities.) Table 1-1. Project Roles Role

Description

Developer

Developers are responsible for the implementation of the components, Web pages, database objects, and other software artifacts that comprise the e-commerce application. Some are specialized developers who take responsibility for a particular aspect of the solution, while others have a more general role in the production of code. (continued)

6

Reference Architecture for Commerce

Role

Description

Application Architect

The Application Architect’s role is to design the software solution and oversee the development effort. To do this effectively, an architect must have a clear understanding of the business requirements, as well as technical knowledge of the development tools and techniques required to build the solution. Additionally, Application Architects must understand the development process from conceptual design to physical implementation.

Infrastructure Specialist

Effective e-commerce solutions, more so than most other application types, require a strong relationship between the design of the software application and the architecture of the infrastructure on which it will run. Infrastructure Specialists are responsible for designing the network topology for an e-commerce site — including firewalls, server clusters, staging servers, and administrative and monitoring functionality.

System Administrator

Any software implementation must be administered to some degree. System Administrators (including network, Web site, and database administrators) are responsible for the day-to-day running of the site. This includes ensuring that appropriate security measures are taken to prevent unauthorized access to sensitive data, implementing a reliable backup procedure, monitoring the site’s performance and availability, and other administrative tasks.

Business Decision Maker

Business Decision Makers fulfill an overall product management role in an e-commerce project. They are primarily responsible for determining the project scope as well as the technological and personnel investments required to build a solution that meets the business needs.

Document Roadmap The Developer’s Guide consists of four main sections, each containing topics related to the development of the site. You are encouraged to read the topics that relate most closely to your role in e-commerce development. The sections, together with their relevance to specific roles and responsibilities, are described next.

Part 1: Getting Started This section provides basic introductory information, a roadmap to the remainder of the guide, and installation and configuration instructions for the Reference Architecture application and other required software. All users should review this information prior to reading other sections of the Developer’s Guide.

Chapter 1: Introduction to the Reference Architecture

7

Part 2: System Architecture Part 2 contains a high-level description of the application, as well as a summary of the design process used to develop the site. It contains a chapter about the design approach and application model and specific chapters on each phase of the design process. ● Business Decision Makers should use this section when evaluating the hardware, software, and expertise requirements for an e-commerce project. ● Application Architects will find this section useful in understanding the conceptual use cases, logical model, and physical implementation of the ConsolidatedRetail.com site. ● Developers can gain an understanding of the skill requirements and the technologies used in the development of the site. ● Infrastructure Specialists will find the physical design of the ConsolidatedRetail.com application useful in determining the required network and security design for the solution.

Part 3: Solution Implementation Part 3 includes a series of topics that describe the implementation details of specific aspects of the application, as well as the testing, deployment, and operational management methodologies the application uses. It contains an implementation overview, a roadmap to the solution, a description of the functional components, and a chapter on debugging and testing e-commerce applications. ● Application Architects can use this section to examine the implementation of the various components in the application. The topic about testing provides additional information about the methodology used to test the application for usability and performance. ● Developers can use this section to gain an understanding of the code in the ConsolidatedRetail.com application, and how it can be reused and extended. ● Infrastructure Specialists will find the topics about testing and deploying the application useful in understanding how the application can be implemented on specific network architecture. ● System Administrators can use the topic about operational management to understand the management issues and tasks involved in operating and maintaining the application.

Part 4: Appendices Part 4 provides additional reference materials that you may find helpful when reviewing the Reference Architecture application code or when building or testing a solution based on the Reference Architecture. These materials include sample XML

8

Reference Architecture for Commerce

output, data field validation notes, a sample test plan, and sample test cases. The materials included in Part 4 are intended primarily for developers and testers. In addition, the Developer’s Guide contains an appendix that shows the XML output generated from the XSL pages, an appendix that explains data validation performed by the reference code, and appendices that provide sample detailed test plans and test cases.

Document Conventions This guide uses the following style conventions and terminology. Table 1-2. Document Conventions Element

Meaning

Bold font

Characters that you type exactly as shown, including commands and switches. User interface elements are also bold.

Italic font

Variables for which you supply a specific value. For example, Filename.ext could refer to any valid file name for the case in question. New terminology also appears in italic on first use.

Monospace font

Code samples.

%SystemRoot%

The folder in which Windows 2000 is installed.

Tip

Alerts you to supplementary information that is not essential to the completion of the task at hand.

Note

Alerts you to supplementary information.

Important

Alerts you to supplementary information that is essential to the completion of a task.

Caution

Alerts you to possible data loss, breaches of security, or other more serious problems.

Warning

Alerts you that failure to take or avoid a specific action might result in physical harm to you or to the hardware.

Support for the Reference Architecture Community (newsgroup) support is available for the Reference Architecture for Commerce on the following newsgroups: ● NNTP at news://msnews.microsoft.com/microsoft.public.reference_arch.commerce ● Web-based Newsgroup Client at http://msdn.microsoft.com/newsgroups /default.asp?newsgroup=microsoft.public.reference_arch.commerce

2 Installing the Software This chapter describes the necessary steps to install the Reference Architecture application on a single computer for testing and examination. This guide also describes realistic deployment practices for use on production sites based on the Reference Architecture.

Before You Begin Before you install the Reference Architecture application, be sure that you have the necessary hardware configuration and all required software.

Hardware Requirements For testing and development purposes, the Reference Architecture application should be installed on a single computer dedicated to the task, rather than on a personal workstation with other software. The application can be safely installed and run with other applications, but due to the possibility of software conflicts or incompatibilities, you should use a single stand-alone computer to ensure proper operation. The Reference Architecture application requires the following minimum system configuration: ● 400 MHz or faster Pentium-compatible CPU ● 256 megabytes (MB) RAM ● 3-gigabyte (GB) hard disk ● Network adapter Note: For development and code review purposes, the Reference Architecture application runs on a single computer without a network adapter.

10

Reference Architecture for Commerce

Software Requirements Before you install the Reference Architecture application, be sure that the required software is installed. The next section provides installation instructions. The Reference Architecture application requires the following software: ● Windows 2000 Server (or Advanced Server), including Microsoft Message Queuing (MSMQ), and Windows 2000 Server, Service Pack 2. ● Microsoft Commerce Server 2000 and Commerce Server 2000, Service Pack 1. Commerce Server 2000 requires Microsoft SQL Server™ 2000 (Standard or Enterprise Edition). ● Microsoft XML Parser (MSXML) 3.0, Service Pack 1, available for download from the MSDN® Web site at http://msdn.microsoft.com/downloads/ ● Microsoft XSL ISAPI filter, included in the Reference Architecture download. The Reference Architecture application code includes a custom version of the XSL ISAPI filter (Xslisapi2.dll). This version is not available for download on Microsoft.com; however, the documentation for the publicly available version (Xslisapi2.dll, version 2.1) is appropriate for the custom version. This documentation is available for download from the MSDN Web site. On the MSDN Downloads page, type XSL ISAPI 2.1 in the Search box. ● Microsoft Reference Architecture for Commerce application (available for download from the MSDN Code Center). On the MSDN Code page (at http:// msdn.microsoft.com/code/), type Reference Architecture for Commerce in the Search box. ● Microsoft Visual Studio® 6.0 (this is required only for developers who want to examine the source code of the application) and current Service Pack level (available for download from the MSDN Web site at http://msdn.microsoft.com /vstudio/). ● Microsoft Passport Software Development Kit (SDK), version 1.4. The Passport SDK is available for download from the MSDN Web site at http:// msdn.microsoft.com/downloads

Installing the Prerequisite Software Install the required software for the Reference Architecture application as described in the following procedures.

Install Microsoft Windows 2000 Server and MSMQ Refer to the Windows 2000 documentation for details about how to install Windows 2000 and Windows 2000 Service Pack 2. You can find information about Windows 2000 Server at http://www.microsoft.com/windows2000/

Chapter 2: Installing the Software

11

Note that you must install the Microsoft Message Queuing (MSMQ) components before you install the Reference Architecture application. (You can install MSMQ on a computer that is already running Windows 2000.) After you install Windows 2000, log on using the Administrator account.

Install Commerce Server 2000 Refer to the Commerce Server 2000 documentation for details about how to install Commerce Server 2000 and Commerce Server 2000 Service Pack 1. You can find more information about Commerce Server 2000 at http:// www.microsoft.com/commerceserver/

Install Microsoft XML Parser 3.0 SP 1 If you have not already done so, download Microsoft XML Parser 3.0 Service Pack 1 from the Web site at http://msdn.microsoft.com/downloads/ After the download completes, double-click the MSXML3SP1.exe file to unpack and install the parser.

Install the Developer Tools (Optional) After you install the XML Parser, install Visual Studio 6.0 and the Passport SDK, version 1.4. Visual Studio 6.0 is necessary if you want to examine or modify the Reference Architecture application source code, and the Passport SDK is required if you want to incorporate Passport authentication.

Install Visual Studio 6.0 Refer to the Visual Studio 6.0 documentation for complete instructions about installing Visual Studio. Be sure that the following components are installed: ● Microsoft Visual C++® development system version 6.0 ● Microsoft Visual InterDev® Web development system version 6.0 ● ActiveX® controls ● Data access ● Enterprise tools ● Tools In addition, you may want to install the MSDN Library to provide online Help for Visual Studio. After installation completes, you should apply all required Service Packs.

12

Reference Architecture for Commerce

Install the Passport SDK 1.4 Refer to the Passport SDK 1.4 documentation for complete instructions about installing the Passport SDK.

After You Install the Prerequisite Software After you install the required software, restart the computer.

Installing the Reference Architecture Application After you successfully install the prerequisite software, you can install the Reference Architecture application and configure the Web site. The following steps describe how to download, install, and configure the application.

Download the Reference Architecture Application The latest version of the Reference Architecture for Commerce application is available on the Microsoft Developer Network (MSDN) Web site.


To download the application 1. Locate the application at http://msdn.microsoft.com/code/ 2. Click Download, and then click Yes to accept the license agreement. Follow the

instructions to download the software.

Create and Configure the Business Desk Folder Before you can install the Reference Architecture application, you need to create and configure a folder for the Commerce Server 2000 Business Desk interface.


To create and configure the folder 1. In Microsoft Windows Explorer, navigate to the Inetpub folder on the system

partition. 2. Create a folder in Inetpub named B2CRefBizDesk. This folder will store the files for the site’s Business Desk interface.

Create and Configure the Web Site Folder Before you can install the Reference Architecture application, you need to create and configure a folder to hold the Reference Architecture Web site files. This allows the XSL ISAPI filter to write temporary files to disk.


To create and configure the Web site folder 1. In the Inetpub folder on the system partition, create a folder named B2CRef. This

folder will store the Reference Architecture Web site files.

Chapter 2: Installing the Software

13

2. Right-click the B2CRef folder, and then click Properties. 3. Click the Security tab, and then click the Add button. 4. In the Look In drop-down list, click your local computer name if it is not already

5.

6. 7. 8.

selected. This displays the accounts on your local computer (rather than accounts in any domain in which the computer is a member). Scroll the list of accounts until you find the account IWAM_computer-name, where computer-name is the name of your computer. This is the account under which the Microsoft Internet Information Services (IIS) Web server runs. Select that account, click the Add button, and then click the OK button. In the B2CRef Properties window, make sure Launch IIS Process Account is selected in the list of names. In the Permissions box, under Allow, select the Modify and Write check boxes. Click OK to close the window.

Create a New Web Site to Host the Application After you create the folders to hold the Web files, you need to create a new Web site to host the Reference Architecture application.


To create the Web site 1. On the taskbar, click the Start button, point to Programs, point to Microsoft 2. 3.

4. 5. 6. 7.

8.

9. 10.

Commerce Server 2000, and then click Commerce Server Manager. In the left pane of the Commerce Server Manager window, expand the Internet Information Services node by clicking the plus sign (+) next to it. A node that represents your computer (with the same name as your computer) should be visible. Click the plus sign (+) next to it to display the Web sites hosted on your computer. Under Internet Information Services, right-click the icon that represents your computer, point to New, and then click Web Site. In the first dialog box, click Next. In the Description box, type B2CRef. The IIS Administration listings refer to the Web site by this name. Click Next. In the IP Address and Port Settings dialog box, leave the IP address as All Unassigned, set the TCP port to 81 (or to any other available IP port address, and then click Next. In the Web Site Home Directory dialog box, either enter the path to the Inetpub\B2CRef folder in the Path box or click Browse to navigate to that folder and select it, and then click Next. In the Web Site Access Permissions dialog box, leave the default settings (Read and Run scripts), and then click Next. Click Finish to create the site.

14

Reference Architecture for Commerce

Create a New Web Site to Host the Commerce Server 2000 Business Desk The Commerce Server 2000 Business Desk console should be placed on a separate Web site to prevent conflicts with the XSL ISAPI filter used on the main Reference Architecture site.


To create the Web site 1. If you have not already done so, expand the Commerce Server Manager Internet

2. 3. 4.

5.

6. 7.

Information Services node, right-click the icon that represents your computer, point to New, and then click Web Site. In the first dialog box, click Next. In the Description box, type B2CRefBizDesk. The IIS Administration listings will refer to the Business Desk console Web site by this name. Click Next. In the IP Address and Port Settings dialog box, leave the IP address as All Unassigned, set the TCP port to 82 (or to any other available IP port address, and then click Next. In the Web Site Home Directory dialog box, either enter the path to the Inetpub\B2CRefBizDesk folder in the Path box or click Browse to navigate to that folder and select it, and then click Next. In the Web Site Access Permissions dialog box, leave the default settings (Read and Run scripts), and then click Next. Click Finish to create the site.

Start the Application Installer Program You are now ready to install the Reference Architecture application that you downloaded previously (refer to the section, “Download the Reference Architecture Application,” earlier in this chapter).


To install the application 1. Double-click the Reference Architecture for Commerce installer program icon to

begin the installation process. 2. On the Welcome screen, click Next. 3. Read the License Agreement. If you agree to the terms of the license agreement, click I accept the terms in the license agreement, and then click Next. Otherwise, you will not be able to install the application. 4. In the Custom Setup dialog box, the default action is to install the entire Web application and all source code. If you want to change particular elements from the installation, select the check boxes next to the elements, click This feature will not be available, and then click Next.

Chapter 2: Installing the Software

15

5. In the Services Account dialog box, in the Username, Password, and Domain

boxes, enter the information under which the COM+ components will run. Click Next. 6. Click Install. The installation process will install the files and components. 7. Click Finish on the last screen.

Install and Configure the XSL ISAPI Filter After you create the Web site for the Reference Architecture application, you need to set up the correct XSL ISAPI filter.


To set up the filter 1. If you have not already done so, expand the Commerce Server Manager Internet

2. 3. 4. 5.

6. 7.

Information Services node, and then expand the node that represents your computer to display the Web sites hosted on your computer. Right-click B2CRef, and then click Properties. Click the ISAPI Filters tab, and then click Add. In the Filter Properties dialog box, type XSLISAPI2 in the Filter Name box, and then click Browse. Navigate to the B2CRef installation folder (default is “C:\Program Files\Reference Architecture for Commerce\Binaries”), click xslisapi2.dll, and then click Open. In the Filter Properties dialog box, click OK to add XSLISAPI2 to the list of ISAPI filters for the site. Click OK to save your changes and close the Properties dialog box.

Configure the XSL ISAPI Filter to Work Correctly with Business Desk If you configure Commerce Server 2000 Business Desk to use the same site that the XSL ISAPI filter uses, an error is generated and Business Desk does not function correctly. This is because the XSL ISAPI filter captures all files delivered by the site to the client, and attempts to process them. So, for example, when Business Desk requests an XML file, the XSL ISAPI filter captures the file first and tries to process it, rather than passing it on to Business Desk. To eliminate this problem, you must do either of the following: ● Configure Business Desk to use a site that does not have XSL ISAPI installed. If you follow the recommended procedure in this chapter, this is the default configuration. ● Remove XML from the list of file types that XSL ISAPI will process. Note that this option requires that you modify and then recompile the source code for the XSLISAPI.dll.

16

Reference Architecture for Commerce


To remove XML from the list of file types that XSL ISAPI will process 1. Start Microsoft Visual Studio, and then open the XSL ISAPI file, Global.h. 2. Find the following section, which lists the file extensions that the filter will

process: Const LPCSTR g_szFileTypesA[] = { "XML", "PASP" };

3. Delete XML from the list, and recompile the project. 4. Replace the previous version of the XSL ISAPI filter with the one you compiled.

Unpack the Commerce Site After you install and configure the XSL ISAPI filter, unpack the commerce site.


To unpack the site 1. Start the Commerce Site Packager: on the taskbar, click the Start button, point to

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

9. 10.

Programs, point to Reference Architecture for Commerce, and then click PUP Package. In the Unpack dialog box, click Custom unpack, and then click Next. In the Unpack Method dialog box, leave Create a new site selected, and then click Next. In the Site Name dialog box, the Site name box should be preset to B2CRef. Do not change the setting. Click Next. In the Select Resources dialog box, leave all resources on the right side (Resources to unpack), and then click Next. In the Global Resource Pointers dialog box, keep the default settings and click Next. In the Database Connection Strings dialog box, keep the default settings and click Next. In the dialog box that requests a SQL user name and password, type sa in the SQL user name box and whatever password you assigned for the SQL Server sa account in the SQL password box. Click Test Connection, and if successful, click OK on the confirmation message box and the Test Connection dialog box. In the Select Applications dialog box, keep the default settings and click Next.

Chapter 2: Installing the Software

17

11. In the Select IIS Web Sites and Virtual Directories dialog box: a. In the left pane, click the first line of the listing (/) to highlight it. b. Under IIS Web site, click B2CRef on the drop-down list. c. The IIS virtual directory should contain a single forward slash (/). This

places the application at the root of the B2CRef Web site. d. In the left pane, click BizDesk to highlight the second line of the listing. e. Under IIS Web site, click B2CRefBizDesk on the drop-down list. f. Under IIS virtual directory, keep the value BizDesk, and then click Next. 12. A warning message may appear indicating that you will overwrite existing 13. 14. 15.

16.

17.

18.

19. 20.

virtual directories if you continue. If this message appears, click Yes. A second message may appear indicating that you will overwrite specific directories if you continue. Click Yes again. In the Data Warehouse dialog box, keep the default settings, and click OK. In the Profiling System dialog box, change the Profile Schema Definition (.xml) file to point to :\Program Files\Reference Architecture for Commerce\SupportFiles\ProfileSQLwCC.xml (where is the drive on which the application is installed). Change the Site Terms Definition (.xml) file to point to: :\Program Files\Reference Architecture for Commerce\SupportFiles\SiteTermswCC.xml (where is the drive on which the application is installed). Click Next. Change the Schema Definition Script to point to :\Program Files\Reference Architecture for Commerce\SupportFiles\ProfileSQLwCC.sql (where is the drive on which the application is installed). Click Profiling System Connection String, and then click Modify. Click Microsoft OLE DB Provider for SQL Server, and then click Next. Choose your server name, user name, and database (B2CRef_commerce). Click OK to close the dialog box. Click OK again. When the application is unpacked, an Unpacking is complete dialog box displays. Click Finish to exit. Note: Do NOT click the View Selected Application button because some post-installation configuration of the Web site still needs to be done.

18

Reference Architecture for Commerce

Import the Predictor Modeling Data This release of the Reference Architecture for Commerce provides support for the Commerce Server 2000 Predictor, which facilitates discount and directed advertising using e-mail. The Predictor resource allows you to build complex analysis models that you can use to determine the type of content, advertisements, and additional products that might interest your users.


To import the Predictor modeling data 1. In SQL Enterprise Manager, navigate to the B2Cref_dw database. Expand the

2. 3. 4. 5.

6. 7. 8. 9. 10.

Microsoft SQL Servers node, the SQL Server Group node, the node for your server, and then expand the Databases node. Right-click the database name, B2CRef_dw, and then click All Tasks. Click Import Data, and then click Next. Change the data source to Text File. Select :\Program Files\Reference Architecture for Commerce\SupportFiles\PredictorModels.csv (where is the drive on which the application is installed), and then click Next. Click Next again. An error message displays. Click Yes. Click Comma, and then click Next. Click Next until you reach the Finish screen. Click Finish. Click Done.

Configure the Business Desk Web Site You need to configure the local path for the Business Desk Web site.


To configure the Web site 1. If you have not already done so, expand the Commerce Server Manager Internet

2. 3. 4. 5.

Information Services node, and then expand the node that represents your computer to display the Web sites hosted on your computer. Right-click B2CRefBizDesk, and then click Properties. Click the Home Directory tab, and then click Browse. Under Inetpub\B2CRefBizDesk, click BizDesk, and then click OK. In the B2CRefBizDesk Properties dialog box, click OK.

Chapter 2: Installing the Software

19

Configure the Pipeline Components You need to configure the local path for the pipeline components.


To configure the pipeline components 1. On the taskbar, click the Start button, point to Programs, point to Microsoft 2. 3. 4. 5. 6.

Commerce Server 2000, and then click Pipeline Editor. On the File menu, click Open. Locate the pipelines folder in the B2CRef folder (the folder where you installed the B2CRef site). For example, the path could be C:\Inetpub\B2CRef\Pipelines\. Click final.pcf, and then click Open. Right-click the QueueEmail Class pipeline stage, and then click Properties. In the Component Properties dialog box on the PipelineQueue Properties tab, replace yourcomputername in the Queued Component Path Name text box with your computer name. Note: If your computer is a member server of a domain, the installation program will create a public queue instead of a private queue. If this is the case, omit the PRIVATE$\ part of the path. If you plan to host your Message Queues on a separate computer, you need to change the path accordingly.

7. Click OK, and then click the floppy disk toolbar icon in the Pipeline Editor to

save the changes and exit the Pipeline Editor application. 8. Stop and restart the B2CRef site. To do this right-click the B2CRef site in the Commerce Server Manager console, click Stop on the pop-up menu, right-click it again, and then click Start on the pop-up menu.

Configure the Queued E-mail Component You need to configure the Queued E-mail component to be able to send confirmation e-mail messages.


To configure the queued e-mail component 1. On the taskbar, click the Start button, point to Programs, point to Administra-

tive Tools, and then click Component Services. 2. In the left pane of the Component Services window, expand the Component

Services node by clicking the plus sign (+) next to it. Click the plus sign (+) next to the Computers node. 3. A node that represents your computer (with the name My Computer) should be visible. Click the plus sign (+) next to it to display the COM+ Applications node. Click the plus sign (+) next to it.

20

Reference Architecture for Commerce

4. A node that represents the queued e-mail component (with the name

B2CRef_Queued_Email) should be visible. Click the plus sign (+) sign next to it. 5. A node with the name Components should be visible. Click the plus sign (+) next to it. 6. A node with the name QueuedEmailer.CMailer should be visible. Right-click this node, and then click Properties. 7. In the Properties dialog box, click the Activation tab. The entry in the text box named Constructor String needs to be changed in the following way: Between the XML tags and , enter the name of your SMTP e-mail server (ask your network administrator if you don’t know the name). You also need to enter the SMTP user name and password between the respective XML tags. Note: The other tags are already filled out, but you might need to check with your network administrator if you need to change them according to your actual SMTP settings (for example, SMTP Port, SMTP Timeout, Use SSL, and the SMTP Authority Mode).

8. Click OK to return to Component Services window. 9. Right-click the B2CRef_Queued_Email node, and then click Shut Down. Right-

click it again, and then click Start. 10. Close the Component Services window.

Create the Business Desk Console for the Application After you install and unpack the B2CRef application and configure the pipeline components, you need to create the Business Desk console for the application. To create the console, please refer to the complete procedures in the Commerce Server 2000 documentation.

Configuring the Commerce Site This section describes procedures for configuring the commerce Web site by adding a catalog, configuring tax and shipping information, and testing the site.

Import, Modify, or Delete Catalogs Use the Catalog Editor module to work with categories and catalogs. You can create, modify, and delete categories and catalogs. In addition, you can use the Catalog Editor module to import a catalog from either an Extensible Markup Language (XML) file or a comma-separated value (.csv) file. The following procedure imports the two sample XML catalog files included with the application and makes them available for the site to use.

Chapter 2: Installing the Software


21

To import the Booksfull.xml catalog file 1. In Commerce Server 2000 Business Desk, on the Catalog menu, click Catalog 2. 3.

4. 5.

Editor. On the Catalog Editor screen, click the Import Catalog toolbar, and then click Import XML on the drop-down list. In the Import XML Catalog dialog box, type :\Program Files\Reference Architecture for Commerce\SourceCode\Catalogs\Booksfull.xml (where is the drive on which the catalog is located) in the File name box. Verify that the Delete any existing catalog data check box is not selected. Click OK. In the Business Desk: Import XML Catalog dialog box, click OK. The Books catalog will be imported and available on the Reference Architecture retail site. Note: The catalog does not yet appear in the Name box in the Catalog Editor.




To import the Hardwarefull.xml catalog file 1. In Commerce Server 2000 Business Desk, on the Catalog menu, click Catalog 2. 3.

4. 5.

Editor. In the Catalog Editor dialog box, click the Import Catalog toolbar, and then click Import XML on the drop-down list. In the Import XML Catalog dialog box, type :\Program Files\Reference Architecture for Commerce\SourceCode\Catalogs \Hardwarefull.xml (where is the drive on which the catalog is located) in the File name box. Verify that the Delete any existing catalog data box is not selected. Click OK. In the Business Desk: Import XML Catalog dialog box, click OK. The Hardware catalog will be imported and available on the Reference Architecture retail site. Note: The catalog does not yet appear in the Name box in the Catalog Editor.

Use the Catalog Editor module to refresh and publish a catalog on your Web site. You need to refresh and publish a catalog whenever you make any changes to ensure that those changes are reflected on your Web site.


To refresh and publish a catalog 1. In Commerce Server 2000 Business Desk, on the Catalog menu, click Catalog

Editor. 2. In the Catalog Editor dialog box, click the Update Catalog toolbar. The catalog

will be updated and published on the Web site.

22

Reference Architecture for Commerce

Configure Tax Rates and Shipping Information To configure tax rates and shipping information, please refer to Commerce Server 2000 documentation about “Tax rates for orders” and to the Commerce Server 2000 tutorial documentation about “Adding a Shipping Method and a Tax Rate.” To configure shipping methods, please refer to Commerce Server 2000 documentation about “Shipping Codes.” Note: The sample catalog schema does not contain a weight field; therefore, the application does not support shipping methods based on weight.

Test the Site After you import the catalog and configure the tax and shipping information, you are ready to test the B2CRef site. To test the site, go to http://localhost:81.

Distributed Deployment Considerations Although you can install the Reference Architecture application on a single computer for development and evaluation purposes, a more realistic deployment environment would involve distributing the application over several servers. In a production environment, you should give additional consideration to security, scalability, and availability in the form of firewalls and server clusters.

Testing the Application in a Distributed Environment You can deploy the Reference Architecture application in a distributed environment for testing purposes. The infrastructure architecture shown in Figure 2.1 could be used to distribute the application over three computers:

Client

Web Server

Database Server

Internet Explorer 5.5

Commerce Server 2000 MSXML3 XSLISAPI121 B2C Reference Site B2CRef BizDesk Site

SQL Server 2000 Analysis Services

Figure 2.1 Simple Distributed Infrastructure Architecture

Chapter 2: Installing the Software

23

To install this distributed environment, use the installation instructions described earlier with the following exceptions: ● Install Windows 2000 Server on the database server and the Web server (the client computer can use Windows 2000 Server, Windows 2000 Professional, Windows 98, or Windows Millennium Edition). The application supports Internet Explorer 4.x and later. ● Verify network connectivity (over TCP/IP) before you attempt to install the application. ● Install SQL Server and Analysis Services on the database server. ● Specify the name of the Database server and valid logon credentials when you install Commerce Server 2000 on the Web server and when you unpack the Reference Architecture application. ● You can install Business Desk on the client computer by going to http://:/BizDesk (where is the name of the Web Server computer and is the IP address specified for Business Desk). ● You can access the B2CRef site from the client computer by going to http:// : (where is the name of the Web Server computer and is the IP address specified for B2CRef.

Production Environment Considerations The purpose of the Reference Architecture application is to demonstrate features that would be required in a real e-commerce solution and to provide reusable components for developers. When a business chooses to deploy a solution similar to the Reference Architecture application in a production environment, a great deal of thought and planning goes into designing the infrastructure on which the application will run. Figure 2.2 shows the minimum infrastructure architecture for such a production site:

Internet Client

Web Farm

Database Cluster

Windows 2000 Advanced SQL Server 2000 on windows Server & Commerce Server 2000 Data Center, clustered 2000 using Network using Microsoft Clustering Load Balancing Services Primary Secondary Firewall Firewall

Figure 2.2 Minimum Production Infrastructure Architecture

Part 2 System Architecture Part 2 of the Developer’s Guide for the Microsoft Reference Architecture for Commerce provides an overview of the business requirements and phased design process used by the architects of the sample application. In addition, each chapter summarizes the actual deliverable produced at that phase of the design process. Note that the process used follows the Microsoft Solutions Framework (MSF) guidelines, which were gleaned from standard industry best practices. More information about MSF is available from the Microsoft Web site. On the Microsoft Home page, type MSF in the Search box.) Part 2, “System Architecture,” consists of the following: ● Chapter 3, “Business Requirements and Design Model” ● Chapter 4, “Conceptual Design Phase” ● Chapter 5, “Logical Design Phase” ● Chapter 6, “Physical Design Phase”

3 Business Requirements and Design Model Ask your average Web user to define an e-commerce site, and he or she will probably tell you that it is an online store where customers can use a credit card to buy products. Although this description is accurate, it does not sufficiently describe the variety of e-commerce sites being developed for the Internet today. In the fastmoving world of Internet business, an effective e-commerce Web site is much more than a Web-based shop.

Requirements That Affect Design Users are demanding more from e-commerce sites, and if one site doesn’t meet their expectations, they’ll go somewhere else. So, what are users demanding from e-commerce? Which business requirements must the application designer consider first? The following list suggests some of the major issues affecting application design: ● Ease of use ● Performance requirements ● Anonymous shopping ● User profiling ● Strong security ● Support for multiple device types ● Manageability At first glance it appears that some of these challenges are within the scope of the Application Architect, while others are more the responsibility of the

28

Reference Architecture for Commerce

Business Decision Maker or Infrastructure Specialist. However, if you examine these challenges in detail, you can understand how the design of the application has an impact on each challenge.

Ease of Use It’s reasonable that a site should be easy to use and navigate. After all, businesses don’t want to make it difficult for customers to buy products, and customers are much more likely to spend money at a site if they can find their way to the checkout page. One way to make the site easier to use is to ensure that you use familiar analogies for common tasks. This means storing a customer’s selections in a shopping basket until the customer decides to complete the purchase (or check out). Using metaphors like this make it easier for non-computer experts to understand how the site works, and make a purchase. Making the site easily navigable can be a much more difficult task than you might first think. The Web works in a fairly non-linear fashion, and users often click links in an unexpected order. You should be sure that your site presents a consistent interface to the user regardless of which page he or she is currently viewing, and that important pages (such as the home page, the shopping basket, and the user’s account information) are always available by clicking a single link. On the ConsolidatedRetail.com site, the banner across the top always includes links to the shopping basket, customer account, and home pages, and the panel on the left side always includes the search and catalogs links. Another way to ensure that users can find their way around your site is to make sure your lists of products, or catalogs, are organized in a logical manner. Customers will find it much easier to locate the product they are interested in if your catalogs are divided into categories, and possibly sub-categories. You should also provide users with the ability to search for a product if they are unsure of where it is listed. If your site is easy to use and navigate, customers will enjoy using it. Conversely, if it is difficult to use, they will probably give up and move on to another site.

Performance Requirements There are many factors in the design of a Web site that can affect its performance. Of course, performance means different things to different people, and what is considered an acceptable level of performance can vary from user to user.

Chapter 3: Business Requirements and Design Model

29

Acceptable Response Time What most people mean by a site that performs well is a site that provides acceptable response times. Response time is the amount of time a user waits after requesting an action before seeing a result. Ideally, we’d all like each action on the site to be performed instantaneously; however, in practice we need to accept that limited bandwidth, database concurrency, and business processing tasks usually cause a slight delay. When designing an e-commerce site, try to reduce the factors that adversely affect response time, although you will never completely eliminate them. The key to e-commerce optimization is to optimize the time in which it takes to perform things such as checking out, so that you don’t lose orders because customers abandon their shopping baskets while standing in the virtual line.

Scalability Another important aspect of performance is scalability. This is the ability of the site capacity to increase when resources are added. To the user community, this means that the site continues to provide acceptable response times when many users access the site concurrently. Many developers are disappointed to learn that a test site that performs brilliantly on a development computer fails to cope with the required number of users. So, how can the scalability of a site be maximized? Two typical approaches are scaling up and scaling out. The first approach, scaling up, is achieved by adding more processing power to the servers in the form of more and/or faster CPUs, more RAM, faster disks, and so on. This approach can be very effective, particularly on the data tier where very large databases require respectively large processing power. However, this approach becomes less cost-effective the closer to the top-end a server reaches, as hardware costs rise exponentially with their power. Scaling out, on the other hand, involves sharing the processing load across multiple servers in a cluster, or a collection of servers, known as a Web farm. Web farms are a much more cost-effective use of hardware, and provide a more flexible and extensible solution. As the load on a site increases, servers can be easily added to the Web farm. Figure 3.1 on the next page illustrates the basic architecture of a Web farm.

30

Reference Architecture for Commerce

Client

Client

Client

Internet

IIS

IIS

IIS

SQL Figure 3.1 A Web Farm

Anonymous Shopping In general, users do not want to be forced to log on to a site before they can see what the site has available to purchase. Your site should allow anonymous users to browse through your products and even place products in a shopping basket, without requiring authentication.

User Profiling When a customer revisits a site, that customer doesn’t want to have to reenter information that was supplied during a previous visit. After a customer provides your site with shipping and contact information, he or she expects that this data will be remembered. To accomplish this, many sites maintain user profile information for each user who registers with the site. In most cases, the user is required to register by providing a minimal amount of profile information, such as a user name and password. The

Chapter 3: Business Requirements and Design Model

31

user is then assigned a unique identifier that can be used as the primary key for that user’s profile data. After a user registers at a site, the user’s profile information can be saved in a database and recalled for use later. Users can usually add to the mandatory information, allowing them to specify such details as an e-mail address, telephone number, shipping address, or any other piece of personal information you allow them to add. Retaining user profile information is useful for the following reasons: ● It prevents users from being required to reenter data on subsequent visits. ● It can be used to analyze user activity at the site. ● It can be used as the basis of personalization, allowing you to target banner ads or discounts at a specific class of user. ● It can be used for business analysis purposes; for example, to track buying trends based on specific profile values.

Strong Security Sensitive information transmitted across an unsecured network, such as the Internet, can be intercepted. For this reason, any site that makes use of sensitive financial or personal information must protect that data’s integrity by using authentication, encryption, and secure networking protocols. Secure Sockets Layer (SSL) is a protocol that provides communications privacy, authentication, and message integrity for a TCP/IP connection. By using this protocol, clients and servers can communicate in a way that prevents eavesdropping, tampering, or message forgery. In addition, a shopping site must ensure that stored customer information — such as personal data, preferences, order history, and payment information — are protected on the server. Access to customer information should be protected by user IDs and passwords.

Support for Multiple Device Types Web browsing devices are becoming increasingly available and varied — for example, there are Internet-enabled cell phones, handheld devices, voice-enabled browsers, and television- and game console-based browsers. In addition, these devices have different capabilities and may or may not support a given markup language or browser version. A commercial Internet site can provide support for multiple device types by providing an interpretative layer that determines the device type, and then formats the content for display on that specific device. Mechanisms that facilitate this functionality include the Extensible Markup Language (XML), Extensible Stylesheet Language (XSL), and related filtering technologies, such as the XSL ISAPI filter.

32

Reference Architecture for Commerce

Manageability Although application designers are not responsible for business decisions such as pricing and advertising campaigns, the design of an e-commerce solution can have a tremendous impact on the way a business responds to trends in the marketplace and competitor activity. Business managers can work only within the constraints of the management features of an e-commerce site. To be successful, an e-commerce solution must be easy to use and yet have an all-pervasive management infrastructure. You have two basic choices when you design the management interface for an e-commerce site. You can create your own custom interface or you can use an ”out of the box” solution such as the Microsoft Commerce Server 2000 Business Desk. Building your own management interface means that you can design the manageability of your site to be exactly the way you want it. However, it adds a significant development effort to an already large software project, and it is often looked upon as a project nearly as large as or larger than the application itself. The Commerce Server Business Desk can be used to manage most aspects of an e-commerce site by default, and additional functionality can be added by creating custom modules if required. The remainder of this chapter describes the actual business requirements identified during the planning phase of this project, and the application model and design process used in the design of the ConsolidatedRetail.com application.

Reference Architecture Application Business Requirements Before the application design process can begin, it is important to gain an understanding of what the application must do. Analyzing business requirements is one of the most important steps in developing an application. The aim of business requirement identification is to create a solution that meets both retailer and consumer needs. The requirements are then transformed into a business requirements document, which will serve as the guide to develop the overall project vision. This section outlines the actual requirements identified for the Reference Architecture application, ConsolidatedRetail.com. Note that the business requirements used here are purposefully limited to the capabilities of an easily installable reference example.

Functional Requirements ConsolidatedRetail.com was designed to meet the following functional requirements. ● Ease of navigation – The site should be easy to navigate. Links should be clear, easy to understand, and functional. Users should be able to move easily between pages and screens.

Chapter 3: Business Requirements and Design Model ●

●

33

Ease of use – The application should be easy to use. It should be easy to locate and buy products and reach the checkout page. The site should be easy to understand for non-computer experts. The site should use easy-to-understand metaphors, such as storing products in a shopping basket or cart until the shopper is ready to check out or shopping from a shopping list. Customers should be able to move products in and out of the list or basket simply and easily. Each page on the site should display a consistent interface. Important and commonly used pages should be available through a single click. Site access – Users must be able to access the site by: ● Entering the URL into a browser. ● Linking from another site or from e-mail.

●

User registration/profiling – From any page on the site, a user must be able to register so that he or she will not have to reenter the same information for each order. A user should not be required to register to browse; however, registration is required for checkout. Also, registration is required to sign up for e-mail newsletters, notification of specials, public and private shopping lists, and so on. Registration consists of: ● Profile information – User name, billing address, primary shipping address, phone numbers, e-mail address should be associated with each unique, authenticated user. ● Authentication information – User identification (user ID) and password should be persisted in the application. ● Billing information – Users should have an option to enter credit card information and have it saved. The application should be able to save multiple credit card numbers. ● Preferences – Users should be able to specify whether or not they want e-mail notification of shipment status (default Yes), and whether or not they want notification of sales and specials (default No). ● Address book – Users should be able to store multiple shipping addresses.

●

User registration management – After a user logs on and is authenticated, the user should be able to modify, add, or delete registration information. All fields except for User ID should be editable. In addition, the user should be able to review order status and order history. Logon/authentication – After a user registers, if that user returns to the site, he or she should be able to log on from any page on the site. Browsing – Users should be able to browse the catalogs. From the home page, users should be presented with a list of catalogs. After a user selects a catalog, he or she should be presented with sub-categories or actual products. Users should be able to browse a series of product detail pages in succession by clicking a single button, such as a Next button or an arrow icon.

●

●

34

Reference Architecture for Commerce ●

●

●

●

●

●

Anonymous browsing – Users should be able to browse catalogs anonymously; that is, users should be able to view products without being logged on. Multiple catalogs – The application must support multiple catalogs. The aggregation of products from multiple catalogs should be transparent to users. Products and categories – The application should permit products to be associated with one or more catalogs. Product page – The application should have a product page that includes a larger picture and/or a more detailed description of each product. Each product can be added to the shopping basket from this page. From this page the user should be able to: ● Add products to a shopping basket. ● Browse to the next product. ● Browse to the previous product. ● Return to the previous page. Product search – Users should have access to free text searches, where users enter text characters and the search function returns a list of products. Users should be able to search from the home page and all category and subcategory pages. Users should be able to type multiple words in the Search field. If a user specifies multiple words, a Boolean query using “and” as the operator should be constructed from the words. If a user is on the home page, Search should default to Search All Categories. Searches performed on category and sub-category pages should default to Search Within Category Name. Users can override these default settings by selecting a particular area of the site or specific category to search. If a site uses multiple catalogs, Search should work across all catalogs. An exception to this rule occurs if the site exposes the multiple catalogs (and had a hierarchical product listing). Each catalog would be the first level in the category/ product hierarchy. In that case, the default would be to search only the currently active catalog. Users can override the default and choose to search another catalog or the entire site. This is similar to the behavior specified for multiple catalogs described earlier. Searches should be performed against key words and titles by default. Product search results – The search results page should show a list of products and their categories (or catalogs, as appropriate). They should be grouped by category or catalog. Each search result should provide a hypertext link to the corresponding product page.

Chapter 3: Business Requirements and Design Model ●

●

●

35

Adding products to the basket –Users should be able to access the following types of baskets: ● Shopping Cart basket – This is the primary type of shopping basket; it holds the products that a user selects to purchase during this visit. Both authenticated and anonymous users should be able to use this type of basket; however, an anonymous user must be authenticated to complete the checkout process. ● Save for Later basket – This is a collection of products that a user may consider for purchase in the future. Only authenticated users should be able to create and save this type of basket. ● Shopping list – This is a reusable (or saved) list of products that can be public or private. Each user can have multiple shopping lists, each with a name and properties indicating public or private availability. For example, a user can have private lists entitled “My Ravioli,” or “Weekly groceries,” or “New travel wardrobe.” A user can have public lists entitled “Human Art 101 – Mrs. Drawer’s class” or “Wedding Gift Registry.” A user should be able to change a shopping list from private to public and from public to private. Only authenticated users should be able to create, edit, and save this type of basket. From any product page, a user should be able to add one or more products to the basket he or she is currently using. The baskets should not be tied to a particular catalog; that is, a user should be able to progress from one catalog to the next, adding products from one or more catalogs. When a user adds a product to a basket, the basket item count increases automatically. The user should be able to see the number of products in the basket from any catalog or product page. If the basket used is the Shopping Cart, the user also sees pricing information as the products are added. The Shopping Cart provides per product, total product, and total order pricing information. Using the Save for Later basket – An authenticated user may want to purchase products stored in a Save for Later basket. To do this, the user opens the Save for Later basket and chooses one or more products to move into the Shopping Cart. If the products are no longer available, the user receives an appropriate message. The Save for Later basket does not save or store pricing information; therefore, when products are moved, the site must process a price query and display the price for each product (as it would for any product placed in the Shopping Cart). Managing the Shopping Cart and Save for Later basket –Users should be able to perform multiple operations that manage the contents of both the Shopping Cart and Save for Later basket. These operations include: ● Moving a product from the Save for Later basket to the Shopping Cart basket ● Moving a product from the Shopping Cart basket to the Save for Later basket ● Changing quantities (Shopping Cart basket only) ● Deleting products from the Save for Later basket or the Shopping Cart basket

36

Reference Architecture for Commerce ●

●

●

●

Using a public shopping list – A site visitor who wants to order from a public shopping list locates the list by searching the site using some form of query. The site displays the names of all lists that match the query, and the user selects a list to view. The user selects products from the public shopping list, the products are added to the user’s shopping basket, and information on pricing is displayed. If a selected product is no longer available, the user receives an appropriate message. Creating and using a private shopping list – An authenticated site user can create a list of products that he or she orders repeatedly. The user can create a new shopping list and add products to it or can add products to a list he or she created during a previous visit. To create a new shopping list, the user must supply a name for the list and must specify whether or not the list will be publicly available. At any time, a user can change a list that he or she created from public to private and from private to public. To purchase products from a shopping list, the authenticated user locates and opens the list, and then selects one or more products to purchase. The selected products are added to the user’s Shopping Cart basket, and price and quantity information is displayed. If a selected product is no longer available, the user receives an appropriate message. Banner advertisement – Users can choose to view a banner advertisement, which displays detailed information about the Shopping Cart and the Save for Later baskets. Checking out – Users should be able to check out from any screen. When checking out, each user is shown all ordered products (the Shopping Cart basket). At this point, the user can edit the Shopping Cart basket contents. If the user confirms the contents of the basket, the shipping screen should appear. Each product is associated with the user’s primary shipping address. The user can override this address with one from the address book or with a new address. If the user adds a new address, he or she chooses to save the new address in an address book. After the user attaches an address to each product (or accepts the default address), the user can go to the Shipping screen and choose the delivery method for each address. (The site owner determines the default method.) After selecting each delivery method, the user progresses to the Payment screen. After selecting a payment method, the user advances to the Order Summary screen. This screen should be divided by shipping addresses. Under each address, the product description(s), product cost, and total cost (if appropriate) are listed. The total product cost is sub-totaled, the shipping cost listed as a line item and subtotaled, and then the tax is listed and the total for that address.

Chapter 3: Business Requirements and Design Model

37

After all addresses are totaled, a grand total is listed at the end of the page. The user has the opportunity to: ● Accept the order. ● Modify the order. ● Cancel the order. ● Continue shopping. If the user chooses to modify the order, the Manage Basket page appears. If the user chooses to cancel, the Shopping Cart basket clears. If the user chooses to continue shopping, the Home page appears. If the user chooses to accept, the Payment page appears. If the user has saved credit card information on the Registration page, this information appears on the Payment page. The user can choose that credit card or override the saved information and provide new credit card information. If the user adds new credit card information, he or she should have the option of adding the new information to the saved Registration information. After the user selects or enters credit card information, he or she can: ● Cancel the order. ● Modify the order. ● Continue shopping. ● Submit the order.

●

●

●

●

If the user submits the order, a confirmation page with the order number appears. Shipping choices – The following shipping choices must be supported: ● Ground delivery ● Second-day delivery ● Overnight delivery ● International delivery Order status notification – Users can choose to receive e-mail notification of order status. Shipping calculation – Shipping costs are calculated based on the shipper type (such as UPS) or other rules determined by the site owner. Tax calculation – Tax must be calculated based on rules set by the site owner. These rules should include: ● Location of sale ● Shipping address ● Type of merchandise The tax information is displayed on the Order Summary screen during checkout.

38

Reference Architecture for Commerce ●

●

●

Order summary – This screen displays the address, product description(s), product cost(s), shipping charges, taxes, and total cost (if appropriate), for each order. Address book – Registered users are placed in the address book. This book can hold unlimited shipping address information, although the site owner can set limits. Order cancellation – Users must be able to cancel orders at any time before they are submitted. When a user cancels an order, the Shopping Cart basket empties. Saved products are not affected.

System Requirements The site must meet the following system-wide requirements: ● Globalization – The application should have the ability to be customized for different cultural contexts. That is, the interface colors, navigation layout, page structure, and language should be modifiable. ● Performance – Users should experience consistent performance each time they visit the site. The site should perform as well as other enterprise e-commerce applications in use. ● Scalability – The site should scale both up and out. Response time should be quicker if faster disks and CPUs are added or if more RAM is added. Response time should also improve if more servers are added to the Web farm. Servers in the Web farm should be able to handle requests appropriately. ● Availability – The site should be functioning and should have no single point of failure. It should trap errors, and errors should not prevent users from accessing authorized areas of the site. The site should accept users at all times. ● Manageability – There should be a management interface that allows for the modification and management of company reports, catalogs, orders, shipping costs, tax rates, and user accounts. ● Security – The site should protect confidential information such as credit card numbers. The site should display the privacy policy and any pertinent copyright information. User IDs and passwords should protect sensitive information from access by unauthorized personnel. ● Accessibility – The site must function properly on multiple client devices. The site should work on down-level browsers as well as newer browsers.

Production Environment Requirements The site must be thoroughly tested before it is launched as a production system. The following types of testing should be performed: ● Usability testing – The site should be evaluated by a number of users to verify that it is easily understood and navigated.

Chapter 3: Business Requirements and Design Model ●

●

●

●

39

Functional testing – The site should be tested to ensure that all features function as designed and as expected. Performance testing – The site should meet appropriate performance benchmarks (as determined by the project team), even during peak load periods. Staging – The site should be rolled out and then fully tested on a test deployment system that approximates the production system. Test scripts should reflect the projected maximum number of users and transactions. Test report – The full test report should be completed and reviewed prior to site rollout.

Documenting the Business Requirements After the basic requirements are identified, they should be captured, communicated, and approved in a Vision/Scope document that identifies the application business value, requirements and limitations, and the personnel required to plan, design, and complete the project. Thereafter, the design process can begin. The next section describes the application design model and design process used in the creation of ConsolidatedRetail.com.

The MSF Application Model The ConsolidatedRetail.com application is designed to follow the three-tier model as defined by the Microsoft Solutions Framework (MSF). This model groups the services provided by an application into three abstract layers so that the resulting application can be both flexible and scalable. Any one layer can be altered without adversely affecting the other two, thus allowing the application to change and grow as user demand and technology changes dictate. The three tiers are: ● Presentation services – The presentation services of an application are used to render data for display to the user and accept user input. ● Business services – Sometimes referred to as application services, the business services of an application enforce the business rules. In a typical e-commerce application this might include ensuring that a user is authenticated before allowing that user to place an order, retrieving appropriate content based on a user’s profile, and verifying that all of the steps involved in processing an order are performed in the correct sequence. ● Data services – The data services in an application include the logic necessary to store, retrieve, and modify data, as well as the data integrity rules that the application must enforce. In an e-commerce application this might include processing of catalog, user, and order data.

40

Reference Architecture for Commerce

Note: You can find more information about MSF at http://www.microsoft.com/msf/

Why Use the MSF Application Model? In addition to the flexibility and scalability benefits discussed earlier, the MSF threetiered application model has distinct advantages in terms of developing, deploying, and managing the application over time. The primary advantages to using the MSF three-tiered approach to application architecture are that it provides: ● Abstraction – Because the services are abstracted from one another, each tier of the application can be developed, maintained, and enhanced independently of the others. Thus, three different development teams can work on the same application project. ● Distribution – Because logical tiers are independent, they can be deployed in a distributed fashion across multiple servers. ● Reuse – Different client devices can use the services provided by each tier. For example, the business services for an e-commerce site could be used by one set of presentation services to provide a Hypertext Markup Language (HTML) interface for a Web site and also by another set of presentation services for a mobile phone that has Wireless Application Protocol (WAP) enabled. Some of the business services can also be configured as Web services by various line-of-business (LOB) applications or by complementary applications supplied by trading partners. In addition to following the three-tiered design model, the designers and developers of ConsolidatedRetail.com followed the MSF design process. The next section describes this process.

MSF Application Design Process The first step in building an effective application of any kind is to create an effective design. There are many approaches to software design, each with its own strengths and weaknesses. When deciding on the design process you want to use, you should be sure that the process provides distinct phases that progress toward an actual software implementation, and that the process is flexible enough to incorporate requirement changes during these phases. The MSF application design model not only defines the services-based architecture for a distributed application, but it also defines an iterative design process where software is designed in a sequence of conceptual, logical, and physical phases. ● Conceptual phase – The conceptual phase views the challenge from the perspective of the user and/or the business. The primary goal of the conceptual phase is to define the challenge and the solution concepts.

Chapter 3: Business Requirements and Design Model

●

●

41

The functional specification document is the end result of the conceptual phase. Logical phase – The logical phase views the design objectives and challenges from the perspective of the project team. The primary goal of the logical phase is to map the conceptual design into logical components. The team uses the user scenarios (or use cases) identified in the conceptual phase to build a logical model of the components in an object-oriented software solution. Object-oriented solutions encapsulate business functionality in software representations of real-world objects, which are defined by classes in an objectoriented design. Physical phase – The physical phase views the design objectives and challenges from the perspective of the developer. The primary goal of the physical phase is to apply the logical design to physical requirements and constraints. Because the physical phase approaches the design problem from the perspective of the developer and the task is to define the physical implementation, the technical specification document is the product of the physical design phase.

Conclusion This chapter provided a general overview of e-commerce requirements, as well as the specific requirements outlined for the ConsolidatedRetail.com application. It also provided an overview of the MSF application model and design process. The next chapters discuss in greater detail the conceptual, logical, and physical design phases and the deliverables produced at each phase along the way.

4 Conceptual Design Phase During the conceptual design phase, the design team identifies and documents the complete project vision, based on the previously identified business and user requirements. The team prepares usage scenarios (derived from use cases) based on these requirements and then creates a functional specification document that explains in detail how the application will work from the viewpoint of both the user and the business or supplier of the e-commerce application. This functional specification document is the end deliverable of the conceptual phase. The design team creates usage scenarios by elaborating upon use cases. A use case is simply a textual description of an interaction between an external actor (which can be a user or an existing system) and the application (or components) being designed. Actors can also be services, components, and so forth, as well as users. The two main pieces of information to determine when creating use cases are the actor’s action and the expected result. Use cases are typically sketched out during a whiteboard (or brainstorming) session in which they are quickly outlined and given descriptive names. They are then worked out in more detail and ordered somewhat linearly. The remainder of this chapter describes each of the usage scenarios developed for the ConsolidatedRetail.com application and provides use case diagrams of the action(s) that each scenario portrays.

Reference Architecture Usage Scenarios During the conceptual design phase, the designers of the Reference Architecture application identified the usage scenarios described in the following sections.

44

Reference Architecture for Commerce

Usage Scenario 1: A Customer Logs On to the Site To log on, a customer navigates to the logon page, and then enters his or her user name and password. The user name and password are authenticated by the system. If the user enters a valid user name and password, a page appears containing links that allow the user to update user profile information and view his or her order history, as described in Usage Scenario 8. If the customer leaves the user name field blank, the user is informed that the user name field must be filled in. If the customer leaves the password field blank, the user is informed that the password field must be filled in. If the customer enters an invalid user name, the logon page is redisplayed with an error message indicating that the user name is invalid. If the customer enters a valid user name but an invalid password, the logon page is redisplayed with an error message indicating that the password is invalid. If the customer indicates that he or she forgot the password, the customer is presented with the option of entering a user name and receiving the password in an e-mail message. After the customer logs on, he or she may be greeted with a personalized message or a list of products he or she may be interested in, based on prior purchases. Figure 4.1 is a use case diagram that illustrates the logon function: ConsolidatedRetail.com

Login

Customer

Figure 4.1 Logon Function

Usage Scenario 2: A Customer Searches for Products An anonymous or authenticated customer can search for products by entering the title, text, a description of a product, or text combined with search parameters (such as greater than [>], less than [

IIS identifies clients by examining the Hypertext Transfer Protocol (HTTP) request header sent with the page request. IIS can identify many common browsers by using the entries in the Browscap.ini file in the WINNT\System32\Inetsrv folder. The XSL ISAPI application provides additional entries for devices such as WAP phones in a file called Browscap-add.ini, which should be copied and appended to the Browscap.ini file.

A Simple Example The following is a simple example of how the XSL ISAPI filter can be used to render the XML output produced by a PASP file. Note: This example is designed to help you understand the functionality provided by the XSL ISAPI filter. It does not describe any of the actual pages in the ConsolidatedRetail.com site.

94

Reference Architecture for Commerce

Assume a user with Internet Explorer 5 requests a page called Myproducts.pasp. The script in the file is interpreted and the following XML is returned through the following response object:

Now, the XSL ISAPI filter parses this XML and reads the xml-stylesheet processing instruction, which contains the following three attributes: ● type – This is the type of style sheet to be applied (in this case XSL). ● server-config – This is the XML configuration file defining the style sheets to be used with specific clients. ● href – This is the default style sheet to be downloaded and applied by the client if no corresponding style sheet is listed in the server-config file. The XSL ISAPI filter then reads the specified server-config file (Productconfig.xml), which contains the following entry:

Because IIS identifies the client browser as Internet Explorer 5 from the request header, the XSL ISAPI application now applies the Products-ie5.xsl style sheet to the XML retrieved from Myproducts.pasp. Assume that the Products-ie5.xsl style sheet contains the following XSL code: Product Catalog

Chapter 8: Solution Roadmap

95

This style sheet would be applied to XML data from Myproducts.pasp, thus producing the following HTML, which would be sent to the browser: Product Catalog

Widget

Wrench

Obviously, in a real e-commerce solution such as the one represented by ConsolidatedRetail.com, the XML produced by the PASP files and the XSL style sheets used to render it is more complex than this simple example. The principle, however, is the same.

Web Site Files The main ASP and PASP pages and accompanying XSL files used in the user interface of the ConsolidatedRetail.com retail site are described here. As previously mentioned, many of the ASP scripts used by the application are implemented as PASP scripts that present XML output to the XSL ISAPI filter. A few regular ASP scripts are also used for non-displaying scripts that accept posts from other pages. Each PASP page has an associated -config.xml file used by the XSL ISAPI filter to identify the appropriate style sheet to be used for specific client types. In this implementation, only a -IE5.xsl file is provided to render the page in HTML that is compatible with Microsoft Internet Explorer 5.5. Additional XSL files could be created to facilitate output for other browsers or devices.

Initialization Pages and Include Files The ConsolidatedRetail.com site uses the following initialization scripts and include files: ● Global.asa – Global.asa is a Web application initialization script that defines actions to be taken at key events in a Web application’s lifetime. ● include\Site_Const.asp – This file defines numerous constants and is included by all pages on the site. ● include\Common.asp – This file defines functions that are used to render data in XML tags. It is used by all PASP pages on the site to generate the XML to be passed to the XSL ISAPI filter.

96

Reference Architecture for Commerce ●

●

●

●

●

●

●

●

include\Profile.asp – This file includes all of the functions for authenticating users, logging them on or off, and retrieving or updating their personal profiles. include\Basket.asp – This file provides the functions required for users to create and maintain a shopping basket; that is, accumulate an order while browsing the catalog. include\UI_layout-IE5.xsl – This XSL style sheet provides the presentation logic for rendering the standard layout for pages in the site. It is included by all pagespecific XSL files to ensure a consistent look and feel to the site. include\Order.asp – This file retrieves and displays the status of a particular order. include\Discounts.asp – This file checks each item in the shopping basket for discounts, and then generates appropriate XML. include\ContentSelection.asp – This file verifies and displays advertising content (used for targeting advertising or discounts at a specific user). include\Catalog.asp – This is a common file that developers can use for code specific to catalog operations. include\Cache.asp – This script is used to cache and retrieve HTML fragments, objects, and components.

Catalog Browsing Pages The ConsolidatedRetail.com retail site uses the following catalog-related pages: ● Default.asp – This page redirects users to the home page of the site (Index.pasp). Because Default.asp is a traditional start page name for ASP applications, it is placed here to redirect any requests that might come in for Default.asp to the application’s real start page. ● Index.pasp – Index.pasp is the default start page for the application. This is what comes up when you type the site name with no additional path information; several other pages also redirect to this page when tasks are completed or errors are encountered. ● Category.pasp – This page generates XML for the page that provides users with a view of the products and subcategories in a particular category of a given catalog. ● Product.pasp – This page generates XML content for the page that shows details about a single product and all its variants from a catalog. This page provides a button that allows the user to display the detail page for the previous or next product in a category or subcategory. ● ListSearch.pasp – This page allows users to locate a public shopping list. ● StepSearch.pasp – This page allows users to specify search criteria and search the catalogs.

Chapter 8: Solution Roadmap ●

●

97

SearchResults.pasp – This page receives the input when a user enters search criteria into the product search box, performs the search for products matching the keywords, and returns a list of matching products to the user. Bdrefresh.asp This script clears the Business Desk cache.

User Authentication and Profile Management Pages The ConsolidatedRetail.com retail site uses the following user authentication and profile management scripts: ● Registration.pasp – This page allows users to register with the site. ● Login.pasp. This page allows registered users to log on to the site. ● ForgotPasswd.pasp – This page allows users to request that their password be sent to them by e-mail. ● Acct.pasp – This page displays account details of the user who is currently logged on. ● UserProfile.pasp – This page allows a user to edit his or her profile. ● AddressBook.pasp – This page allows users to view and update the shipping and billing addresses saved in their address books. ● CreditCards.pasp – This page allows a user to save credit card numbers and expiration dates in his or her profile. (The user can save as many credit card numbers as he or she wants to save; there is no limit.) ● EditCreditCard.pasp – This page allows a user to edit the credit card information saved in his or her profile. ● RefreshApp.asp – This script clears the Profiles cache.

Order Management Pages The ConsolidatedRetail.com retail site uses the following order management pages: ● OrderHistory.pasp – This page retrieves and displays the order history of the current user, allowing the user to view all purchases the user has made from the site. (Note that the order history page displays only the most recent 20 orders.) ● OrderHistorydetail.pasp – This page displays the details of a specific order from the user’s order history. ● Basket.pasp – This page displays the contents of the current user’s shopping basket, or more specifically, the products contained in the OrderGroup object associated with the user’s current session. ● OrderSummary.pasp – This page provides a summary of the current order. Although the displayed results of this page are considerably different, the scripting behind this page and the XML content generated by the script are similar to Basket.pasp.

98

Reference Architecture for Commerce ●

● ●

●

●

●

●

ListBase.pasp – This page provides a common code base for the Save for Later, Shopping List, and Public List pages. AddtoList.pasp – This page allows the user to add items to a shopping list. AddtoListResp.pasp – This page allows the user to view the contents of a revised shopping list after an item is added. Shipping.pasp – This page is invoked when the user clicks the Checkout link on the shopping basket page or clicks the Checkout link at the top of any page. It allows the user to specify an address for delivery of the order. ShippingMethod.pasp – This page allows the user to select a shipping method for the order. MultiShipping.pasp – This page allows a user to ship items in a single order to different addresses. Thankyou.pasp – This page completes the processing of an order in the Commerce Server portion of this application by running it through a series of Commerce pipeline processes.

Commerce Server Objects Another important aspect of the solution is the use of Commerce Server 2000 programmable objects for business processing. These objects can be used from any COM-aware client (such as an ASP script) to retrieve data from the site database or to perform a task such as authenticating a user. The use of these objects is examined in depth in Chapter 9, but the following list introduces the key Commerce Server objects used in the ConsolidatedRetail.com application.

Utility and Configuration Objects An e-commerce site is a highly complex application that requires many kinds of information and functionality. To help simplify the development of an e-commerce solution, Commerce Server 2000 provides a number of objects that can be used to manage site configuration information and provide general functionality that can be used throughout the site. Many of the objects used in Commerce Server solutions are in fact Dictionary objects or SimpleList objects. These are general-purpose objects that can be used to maintain a collection of name/value pairs. For example, in the ConsolidatedRetail.com application, a Dictionary object is used to store the collection of pipelines used by the site. For more detailed information about Dictionary and SimpleList objects, refer to the Commerce Server 2000 documentation. The ConsolidatedRetail.com application uses the following utility and configuration objects throughout the site.

Chapter 8: Solution Roadmap ●

●

●

●

● ●

●

●

99

AppConfig – This is the Commerce Server Application Configuration object. It provides methods that can be used to retrieve configuration settings for the site. It contains an Options Dictionary object that is used to store various configuration options for the site. In the ConsolidatedRetail.com site, the options dictionary is used to store data source connection strings and other configuration information. AppDefaultConfig – Commerce Server 2000 supports the ability for the site administrator to alter site behavior through programmatic changes to properties stored in the Commerce Server 2000 administration database. The Reference Architecture application provides limited support for AppDefaultConfig options as follows: ● i_AddItemRedirectOptions – This specifies how the site functions after a user adds an item to a shopping basket (a value of 1 continues displaying the current product page; 0 redirects to the basket page). ● i_FormLoginTimeOut – This specifies the number of minutes before a logon ticket times out. ● i_SitePrivacy – This specifies how much tracking is performed for anonymous users (a value of 1 profiles anonymous users; 2 profiles and tracks anonymous user visits). DataFunctions – This is a data-formatting object that holds information about the site locale, currency and other data-related issues. It also provides methods for handling data type specific tasks such as removing white space from strings or converting data from one type to another. GenID – This is a utility object used to generate Globally Unique Identifiers (GUIDs). These can be useful for providing a unique ID to identify a specific item. AppFramework – This is a utility object used to simplify HTML form processing. MessageManager – This object is used to store multilingual error messages for use by pipeline components. CacheManager – This object is used to manage data caching for the site. Caching data such as catalogs, shipping methods, user profiles and so on can greatly improve performance. DictionaryXMLTransforms – This object is used to transform the contents of a Dictionary object to XML (and vice-versa) using a specified XDR schema.

For more information about the AppConfig, DataFunctions, GenID, AppFramework, MessageManager, CacheManager, and DictionaryXMLTransforms objects, refer to the Commerce Server 2000 documentation.

100 Reference Architecture for Commerce

Catalog Objects One of the most obvious tasks that must be addressed by pages in an e-commerce site is to retrieve product information from the catalogs associated with the site. Commerce Server 2000 provides support for multiple catalogs in a single site. You can structure catalogs hierarchically with nested categories and define products at any level of the catalog, including the root. In addition, any category or product can be related to any other category or product anywhere in the hierarchy. For example, a product called Windows 2000 Server in the Software category could have a relationship defined with a product called The Windows 2000 Server Administrators Guide in the Books category. This makes it easy to create links to related products or categories and provide opportunities for cross selling. Figure 8.2 shows the catalog structure that Commerce Server 2000 supports:

Catalog

Product Product

Category

Product Category

Product

Category

Product

Figure 8.2 Commerce Server 2000 Catalog Structure

You can create catalogs from scratch or import them from an XML or CSV file by using the Commerce Server Business Desk. For detailed information about managing catalogs with the Business Desk, refer to the Commerce Server 2000 documentation.

Chapter 8: Solution Roadmap 101

Another feature of the catalog support in Commerce Server is that you can create Catalog Sets. A Catalog Set is a collection of one or more catalogs that is assigned to a particular class of user based on a property in their profile. For example, you could create a catalog set containing catalogs with discounted prices for users who have joined your customer loyalty scheme. For users who have no catalog set assigned, Commerce Server sites include a default catalog set for anonymous users and a default catalog set for authenticated users. Programmatic access to the catalog data is provided through the following Commerce Server automation objects: ● CatalogManager – This object represents the entire catalog management system. ● CatalogSets – This object provides access to the catalog sets defined in the site. ● ProductCatalog – This object represents a specific catalog. ● Category – This object represents a category within a catalog. ● Product – This object represents a product. These objects provide methods for navigating through the entire catalog hierarchy of a site. Many of the methods and properties that these objects provide return ADO Recordsets, which contain catalog, category, or product data. Before any catalog data can be accessed, a connection to the data source for the site must be initialized. Generally this is achieved by calling the Initialize method of the CatalogManager object passing either an ADO connection string to the site database or the site name as a parameter. For more detailed information about the CatalogManager, CatalogSets, ProductCatalog, Category, and Product objects, refer to the Commerce Server 2000 documentation.

User Management Objects Commerce Server provides several objects that can be used to manage user information and status as customers interact with the site. These objects include: ● AuthManager – This object is used to handle security related functionality, allowing users to be authenticated and logged on and providing a means of identifying the specific user making a request. ● ProfileService – This object is used to connect to the data source where profile information relating to the registered users in the site is stored. ● ProfileObject – This object encapsulates the profile data for a specific user, and can be used to set or retrieve values such as Name, Telephone Number, E-mail Address, or any other user attribute that needs to be tracked. For more detailed information about the AuthManager, ProfileService, and ProfileObject objects, refer to the Commerce Server 2000 documentation.

102 Reference Architecture for Commerce

Shopping Basket Objects After a user locates a product he or she wants to purchase, it is common practice in a Web site to allow the user to add the product to a cart or basket. In reality, the conceptual basket is a metaphor for a software object representing the collection of items the user has selected during the visit. Every register user is issued a virtual shopping basket during a visit (there is a one-to-one mapping of users to baskets). The Reference Architecture application uses the following objects provided by Commerce Server 2000 to provide the abstract shopping basket functionality: ● OrderGroup – This object represents the shopping basket. ● OrderForm – This object represents the collection of items in the shopping basket. The OrderForm object is implemented as a Dictionary object, containing information about the order as a whole, and a SimpleList object containing item Dictionary objects representing the individual items in the basket. An Addresses SimpleList object is used to store a collection of address Dictionary objects, representing the shipping and billing addresses associated with the order. For more detailed information about the OrderGroup, and OrderForm objects, refer to the Commerce Server 2000 documentation.

The Predictor Resource Commerce Server 2000 provides the ability to send content, such as advertisements and discount notifications, to specific users. To do this, Commerce Server 2000 uses the Microsoft Windows 2000 Predictor resource, which is installed optionally with Commerce Server 2000. The Predictor resource allows you to build complex analysis models that you can use to determine the type of content, advertisements, and additional products that might interest your users. After the Predictor builds the analysis model, you can add the Predictor Client Object to your ASP pages, which gives your site the ability to display recommended products and targeted content. The Predictor resource uses a great deal of memory when building the analysis models. You can prevent this from impacting your Web servers by building the analysis model once and then copying it to each of your Web servers. Each Web server can host multiple analysis models to enable different predictive capabilities. After you build an analysis model, you can view its components by using the Prediction Model Viewer in Commerce Server Manager and the Segment Viewer module in the Commerce Server Business Desk. For more detailed information about the Predictor and guidelines for its use, refer to the Commerce Server 2000 documentation.

Chapter 8: Solution Roadmap 103

Pipelines Commerce Server 2000 solutions usually use pipelines for business processing. A pipeline consists of a sequence of COM components that operate on a business object, such as an OrderForm. The components in the pipeline, and the order in which they are called, is specified in a pipeline configuration file (*.pcf). You can think of a pipeline as being a kind of production line in which each component performs a specific task before passing the business object to the next component. ConsolidatedRetail.com uses seven pipelines: Advertising.pcf, Discounts.pcf, Final.pcf, Lists.pcf, Pagbasket.pcf, Recordevent.pcf, and Total.pcf. Six of these have references that are stored in the application level MSCSPipelines dictionary variable as Advertising, Discounts, PAGFinal, Lists, PAGBasket, and PAGTotal respectively. The remaining pipeline, Recordevent.pcf, is held as a Commerce.OrderPipeline object in Application(“CampaignsCSFEventPipe).

Pipeline Components The components in a pipeline are COM components that implement the IPipelineComponent interface. This interface provides an Execute method, to which a Dictionary object can be passed. A business process is implemented by passing a business object such as an OrderForm to the execute method of each component in the pipeline in turn. Commerce Server provides a number of pipeline components that can be used in e-commerce sites. These objects are used to apply discounts to an order, charge tax, arrange shipping, and so on. In addition, you can create your own custom pipeline components to perform specific tasks. The ConsolidatedRetail.com site includes the following two custom pipeline components: ● PersistUtility – This is a custom pipeline component that is used for copying non-persisted attributes of the OrderGroup object to persisted attributes. Typically, attributes from the OrderGroup object that begin with an underscore are temporary values and are destroyed at the end of pipeline processing. Because this application exports an order form outside of the Commerce Server realm, some OrderGroup values that are usually discarded need to be retained to provide context in external processing. PersistUtility copies a few underscored attributes to names without underscores, so the values persist after pipeline processing is complete. ● QueueEMail Class – This is a custom pipeline component that takes data from the order form, converts it to XML, and uses the QueuedEMailer.CMailer component (described in the section, “Custom Business Components”) to send an e-mail message to the customer.

104 Reference Architecture for Commerce

Custom Business Components Additional custom functionality can be added to a solution by creating custom business components. The ConsolidatedRetail.com site includes one custom business component: QueuedEMailer.CMailer. QueuedEMailer.CMailer is a custom COM component used to send e-mail to a customer. This is used for order confirmations and forgotten passwords. The component is implemented as a COM+ queued component, allowing its methods to be called asynchronously through a message queue. This improves response time by allowing a user’s session to proceed without having to wait until the email processing is complete.

Conclusion This chapter provided a very brief, high-level overview of the major code categories in the Reference Architecture application, with reference to actual code snippets. At this point, you should have a conceptual understanding of how the code is structured. The next chapter walks you through each tier of ConsolidatedRetail.com application, and provides pseudo-code and actual code examples to illustrate the processing flow.

9 ConsolidatedRetail.com Functionality Now that you have an overview of the various parts of the solution, you are ready to examine the specific functionality provided by the site. This chapter discusses the following aspects of the solution and pays particular attention to the challenges inherent in writing code for each functional area: ● Presentation services ● User authentication and profiling ● Catalogs ● Shopping basket management ● Order processing As you review each section of this chapter, you will see how specific functionality has been implemented and how you can reuse part or all of the ConsolidatedRetail.com application in your own business-to-consumer solutions.

Presentation Services The presentation services in the ConsolidatedRetail.com site are provided by the XSL ISAPI filter. The main development challenge is to generate appropriate XML in each of the PASP scripts and to create suitable XSL style sheets to present that XML as HTML (or some other presentation format).

106 Reference Architecture for Commerce

XML Output from the PASP Files in ConsolidatedRetail.com Each PASP file in the ConsolidatedRetail.com site produces an XML document in a consistent format. It does this by including an Include reference to the Common.asp file in every page on the site and calling its PageStart procedure. The PageStart procedure in the Common.asp file contains the following code: Sub PageStart(strPageNameWithExtension) 'comments and code omitted for clarity ' strip off the pasp file extension Dim strPageName strPageName = Trim(Left(strPageNameWithExtension, _ InstrRev(strPageNameWithExtension, _ ".") - 1)) if mc_blnUsePassport = True then Call InitPassport(GetServerURL() & "/" & mc_strPassportReturnPage Else '??????? End if 'XML header Response.Write _ "" & vbcrlf 'root for the page element. 'the tag is closed in the "PageEnd" Subroutine. Response.Write "" & vbcrlf 'This information is used by the link to passport for 'returning back to the site after passport authentication. Call XMLTag("HTTPHost", Server.URLEncode(GetHTTPHost())) if not LocalIsLoggedIn() then Call GetPassportLogo(GetServerURL() & "/" & mc_strPassportReturnPage) end if End Sub

This procedure creates the XML header for the document that will be produced by the PASP file. At the end of each PASP script, the PageEnd procedure is called to close the tag and complete the XML document. The following is the relevant code in the PageEnd procedure: Sub PageEnd() 'comments and code omitted for clarity 'get authentication information to be used to display the logoff button. Call GetLogOffXML()

Chapter 9: ConsolidatedRetail.com Functionality 107 'display error messages Call DisplayExceptions(m_varrExceptions) 'root for the page element. The tag is opened in the PageStart subroutine. Call XMLEndTag("page") End Sub

The XMLEndTag procedure is one of a number of XML helper procedures in Common.asp. (For more information, see the “XML Helper Procedures” section later in this chapter.) It generates an XML closing tag using the following code: Sub XMLEndTag(strTagName) Response.Write mc_strStartTag & mc_strForwardSlashTag & _ Lcase (Replace(strTagName, mc_strBlank,_ mc_strUnderScore)) & _ mc_strEndTag & vbCrLf End Sub

XML documents produced using the PageStart and PageEnd procedures will look similar to the following code sample:

XML Helper Procedures In addition to the XMLEndTag procedure described earlier, Common.asp contains multiple XML-related utility routines. These procedures are used to generate tags to be used in the XML documents produced by the PASP pages in the ConsolidatedRetail.com site. Although in many ways, it would be more efficient to hard-code the required XML characters—such as “” (without the quotation marks)—in the various XML-generating procedures, numerous XML character constants are declared in Common.asp. This helps make the code legible and aids debugging. The constants are: Const Const Const Const Const

mc_strStartTag = "" mc_strForwardSlashTag = "/" mc_strUnderScore = "_" mc_strBlank = " "

108 Reference Architecture for Commerce

These constants are used in the following XML-generating procedures: ● XMLBegTag – This utility writes an opening XML tag (for example, ) based on an strTagName parameter. ● XMLEndTag – This utility (described earlier) writes a closing tag (for example ) based on an strTagName parameter. ● XMLEmptyTag – This utility writes an empty XML tag (for example, ) based on an strTagName parameter. ● XMLTag – This utility writes an XML tag containing a value (for example, myvalue) based on two parameters: strTagName and strTagValue. ● GetXMLFromRS – This utility creates an XML representation of a recordset. ● GetXMLFromRSRow – This utility creates an XML representation of the current row in a recordset. There are also numerous procedures, generically named xxxWithDsplyNm, which produce XML tags containing a displayname attribute, for example: Joe The display name for the tag is based on the tag name and is retrieved from the CatalogDefinitionProperties application-level dictionary object variable. To gain a full understanding of the functionality provided by the XML helper procedures, examine the source code in Common.asp.

XSL Style Sheets in the ConsolidatedRetail.com Site As explained earlier, each page has an associated filename-Config.xml file listing the XSL style sheet to be applied for each client browser or device type. In this implementation, only Internet Explorer 5.5 is supported, although alternative style sheets could be created and added to the site. In most cases, the XSL file for each PASP page is named pagename-IE5.xsl (where pagename is the non-version specific name of the PASP page), and contains XSL code specific to the data on that page. However, to maintain a consistent look and feel to the site, the common user interface (UI) elements for all pages are defined in a separate XSL file named UI_layout-IE5.xsl, which is stored in the Include directory. Each page-specific XSL file uses the XSL Include directive to incorporate the presentation logic in UI_layout-IE5.xsl into the rendering of the current page as shown by the following code snippet:

Chapter 9: ConsolidatedRetail.com Functionality 109

Templates in UI_layout-IE5.xsl The UI_layout-IE5.xsl file contains several templates. The page template is applied to the element in the XML document generated by each PASP page. It refers to the Stylesheet.css cascading style sheet and creates an HTML table consisting of five rows, on which the overall page is based. Other templates in the UI_layoutIE5.xsl file are called to populate the rows. The first row in the table contains a call to the pageheader template defined later in the script. This template renders the top banner of the page, including the images linked to the basket, profile, and home pages. The second row is used to create a space before the third row, which contains a call to the main template. This template includes the logic necessary to render the menu panel at the left side of the page, including the search form. The main template in turn calls the getCatalogsForUser template, the exceptions template, and the advertising or profilemenu or listsmenu template (depending on the presence of an advertising, profilemenu, or listsmenu XML element). The fourth row of the table, like the second, is a spacer before the fifth row, in which the pagefooter template is called. This template renders the bottom panel of the page, including the copyright statement. The page template in UI_layout-IE5.xsl is shown in the following code. The pageheader, main, pagefooter, and other templates used to render the pages in the site can be examined in UI_layout-IE5.xsl. ConsolidatedRetail.com

110 Reference Architecture for Commerce

Rendering Index.pasp You can examine the Index.pasp page to see how this all fits together. The Index.pasp page is the default page, or home page, for the site. Index.pasp contains code to perform the following tasks: 1. Define a constant named mc_strPageName with the value Index.pasp. 2. Call the PageStart procedure in Common.asp to create the appropriate opening tag. 3. Create an empty tag using the XMLEmptyTag procedure. 4. Create the closing tag by calling the PageEnd procedure. The following code performs these tasks:

This code generates the following XML document: localhost%3A81 a http://current-login.passporttest.com/login.asp?id=1& ru=http%3A%2F%2Flocalhost%3A81%2F% 5FProcessPassportLogin%2Easp& tw=120&fs=0&kv=1& ct=998426692&cb=0&ems=1& ver=1.990.1052.1&C=1 img http://current-www.passportimages.org/signin.gif 66 19 0 PassportSignIn

Type mismatch: 'CachedFragmentLookup' error '800a000d'

Type mismatch: 'CachedFragmentLookup'

/include/Common.asp , line 115

The XML is passed to the XSL ISAPI filter, which determines that the appropriate style sheet is identified in Index-Config.xml. The XSL ISAPI filter examines the HTTP request header information to determine the browser type and version. Then it matches the browser information with the appropriate style sheet in IndexConfig.xml. If no matching entry is found, the default style sheet (Index-IE5.xsl) is applied.

112 Reference Architecture for Commerce

Index-Config.xml looks like the following:

When a request is received from Internet Explorer 5 browser, the Index-IE5.xsl style sheet is used to render the page as HTML. (The other entries in the IndexConfig.xml file are for illustration only; the corresponding style sheets are not provided in the ConsolidatedRetail.com site.) The Index-IE5.xsl code is similar to the following:

Chapter 9: ConsolidatedRetail.com Functionality 113

Hello, . Welcome back to ConsolidatedRetail.com Welcome to ConsolidatedRetail.com Welcome to the site where you can purchase everything you need at one convenient location. Look for this feature in the near future.

114 Reference Architecture for Commerce

This style sheet includes the UI_layout-IE5.xsl style sheet, which renders the common user interface elements for the page. In this case, the XML document contains an tag. Therefore, UI_layout-IE5.xsl also uses the advertising template to render the right panel of the page. The resulting Index page is similar to Figure 9.1. The ConsolidatedRetail.com site renders PASP pages as described in the preceding sections. This method—generating XML content in the PASP files and defining presentation in the XSL style sheets—allows you to easily change the style sheets used to display the pages without affecting the business logic in the PASP files, making this a flexible and easily reusable solution.

Chapter 9: ConsolidatedRetail.com Functionality 115

Figure 9.1 Index Page

Caching Commonly Used Information Microsoft Commerce Server 2000 provides components that can be used to cache commonly used sections of a commerce Web site. The Reference Architecture uses these components to provide two types of caches: ● Caches that are not refreshed (emptied) automatically; for example, caches that store the catalog and the shipping methods. These caches are loaded when the application starts and always contain valid (static) data. They are refreshed only when and if the Web site owner uses Commerce Server Business Desk to modify them. ● Caches that are refreshed automatically; for example, caches that store search results and product detail information. These caches store the XML for pages as the user requests them. These caches are emptied at regular intervals as specified in the Global.asa file. They are also refreshed when the catalog changes. The Web site’s PASP pages produce XML output strings, which both cache types store. Using a caching mechanism to store processed XML allows Web pages to be displayed quickly without further processing, thus improving performance and saving system resources. Caches are of the type Commerce.LRUCache because this component automatically removes items from the cache when the cache is filled, and allows the caches to refreshed automatically using the Commerce Server 2000 Commerce.LRUCacheFlush component.

116 Reference Architecture for Commerce

Specific changes in Business Desk are immediately reflected in the caches when the catalog is refreshed or updated (or when the transactions are published using Business Desk). This happens because code in the BDRefresh.asp page refreshes the relevant caches. Refer to the Commerce Server documentation for details regarding how application caches are tied to Business Desk. Note: Cache keys for certain caches contain compound information (for example, catalog name and category name), which is stored in a concatenated form delimited by the greater than (right chevron) sign (>).

Caching of Catalog Names The Reference Architecture stores catalog names in a cache because these names are displayed on every page, thus they must be retrieved from the Commerce Server 2000 database for every page. In addition, catalog information rarely changes in production sites. Therefore, the catalog names cache is not refreshed automatically. Similar functionality is implemented in the Commerce Server 2000 Retail Solution site available for download from the MSDN Web site at http:// www.msdn.microsoft.com/ Pages Affected

Caching of catalog names affects the following pages: ● Global.asa ● include\Cache.asp ● include\Common.asp ● include\Site_const.asp Implementation Details

The cache for catalog names, CatalogSetCache, is created in Global.asa with a RefreshInterval of zero (0). This ensures that the cache never refreshes automatically; that is, the Refresh interval is forever. The cache is also populated in Global.asa with the XML for the catalogs for each CatalogsetId in the Commerce Server 2000 database. The CatalogsetId also serves as the cache key. The CatalogSetId uniquely identifies the catalogs associated with a user. Therefore, the XML to be displayed varies as the CatalogsetId changes to correspond with current user. If you use Business Desk to make any changes to the catalogs, code in BDRefresh.asp automatically propagates the changes to the cache. This design ensures that CatalogSetCache always contains up-to-date information and that the cache can be used directly without performing an “if… exists” check each time.

Chapter 9: ConsolidatedRetail.com Functionality 117

Caching of Categories The Reference Architecture stores category pages in a cache because they are pages that are commonly viewed by most users. Similar functionality is implemented in the Commerce Server 2000 Retail Solution site. Pages Affected

Caching of category pages affects the following pages: ● Category.pasp ● Global.asa ● include\Common.asp ● include\Site_const.asp Implementation Details

The cache for category pages, CategoryCache, is created in Global.asa with a zero RefreshInterval. This ensures that the cache does not refresh itself automatically. The cache is populated when the user first encounters the category page. Subsequent access requests for the same page are fulfilled from the cache, until the cache is refreshed or the LRUCache component removes it from the cache. The cache key is a concatenated string consisting of the catalog name and the category name in the form: CatalogName + > + CategoryName Together, the catalog name and category name provide enough information for the Category.pasp page to obtain the listed products and subcategories. If you use Business Desk to make any changes to the catalogs, code in BDRefresh.asp automatically empties the CategoryCache. This design ensures that CategoryCache contains the most current version of a recently viewed category page.

Caching of Product Information The Reference Architecture stores product pages in a cache because they are pages that are commonly viewed by most users. Similar functionality is implemented in the Commerce Server 2000 Retail Solution site. The Reference Architecture and Commerce Server 2000 Retail Solution Site use the same cache name for this functionality: ProductPageCache.

118 Reference Architecture for Commerce Pages Affected

Caching of product information affects the following pages: ● Global.asa ● include\Common.asp ● include\Site_const.asp ● Product.pasp Implementation Details

The cache for product pages, ProductPageCache, is created in Global.asa with a non-zero RefreshInterval. This ensures that the cache refreshes (that is, it empties itself) automatically at regular intervals. The cache is populated when the user first encounters the product page. Subsequent access requests for the same page are fulfilled from the cache, until the cache is refreshed or the LRUCache component removes it from the cache. The cache key is a concatenated string consisting of the catalog name, the category name, and the product ID in the form: CatalogName + > + CategoryName + ProductId Together, the catalog name, category name, and product ID provide enough information for the Product.pasp page to obtain the product information. If you use Business Desk to make any changes to the catalogs, code in BDRefresh.asp automatically empties the ProductPageCache. This design ensures that ProductPageCache contains the most current version of recently viewed product information.

Caching of Shipping Methods The Reference Architecture stores shipping methods in a cache because these methods rarely change and are used by all users during the check out (or purchasing) phase. Similar functionality is implemented in the Commerce Server 2000 Retail Solution site. The Reference Architecture and Commerce Server 2000 Retail Solution Site use the same cache name for this functionality: StaticSectionsCache. Pages Affected

Caching of shipping methods affects the following pages: ● Global.asa ● include\Common.asp ● include\Cache.asp

Chapter 9: ConsolidatedRetail.com Functionality 119 ● ● ● ● ●

include/Site_const.asp MultiShipping.pasp OrderSummary.pasp Shipping.pasp ShippingMethod.pasp

Implementation Details

The cache for shipping methods, StaticSectionsCache, is created in Global.asa with a RefreshInterval of zero (0). This ensures that the cache never refreshes automatically; that is, the Refresh interval is forever. The cache is populated in Global.asa with the XML for the shipping methods from the Commerce Server 2000 database. The cache key is a string constant, ShippingMethodsXML. If you use Business Desk to make any changes to the shipping methods, code in BDRefresh.asp automatically propagates the changes to the cache. This design ensures that the StaticSectionsCache always contains up-to-date information and that the cache can be used directly without performing an “if… exists” check each time.

Caching of Search Results The Reference Architecture stores search results in a cache because the search facility is commonly used by all users. Similar functionality is implemented in the Commerce Server 2000 Retail Solution site. The Reference Architecture and Commerce Server 2000 Retail Solution Site use the same cache name for this functionality: FTSearchPageCache. Pages Affected

Caching of search results affects the following pages: ● Global.asa ● include\Common.asp ● include\Site_const.asp ● SearchResults.pasp Implementation Details

The cache for search results, FTSearchPageCache, is created in Global.asa with a non-zero RefreshInterval. This ensures that the cache refreshes automatically at regular intervals. The cache is populated when the user first encounters the product page. Subsequent requests to the same page are fulfilled from the cache, until the cache is refreshed or the LRUCache component removes the page from the cache.

120 Reference Architecture for Commerce

The cache key is a concatenated string consisting of relevant search information, as follows: CatalogName + > + CatalogSetId + > + CategoryName + > + SearchPhrase + > + ProductID + > + VariantID + > + SearchStartPosition + > + NumberOfSearchedItemsToDisplay

This key is unique and is the only information that the SearchResults.pasp page needs. If you use Business Desk to make any changes to the catalogs, code in BDRefresh.asp automatically refreshes the FTSearchPageCache. This ensures that FTSearchPageCache contains the most current version of the search results page.

User Authentication and Profiling Microsoft Commerce Server 2000 provides support for an extensible profile system that can store a great deal of user data. This user data, or customer profile, can include shipping addresses and contact information. Customers can use these profiles to store personal data so that they aren’t required to reenter the information each time they visit the site. Thereafter, a company can then use the profile information for business analysis, targeted advertising campaigns, and discount offers. To create and maintain a profile, a customer must register with the site and log on. This creates a unique user ID that identifies the user and retrieves the corresponding profile information from the database. The customer’s user ID is stored in a cookie on the client browser. If a user has not yet logged on, the cookie contains the user ID associated with the anonymous user, and profile information is not available. When the user logs on, the appropriate user ID is retrieved and written to the cookie; thereby making the profile information available for the remainder of the session. Note: Just as the Bdrefresh.asp script clears the Business Desk cache, the RefreshApp.asp script clears the Profiles cache. Clearing either of these caches repeatedly could lead to a denial of service for users.

The site requires browsers to be configured to allow cookies. If a user accesses the site with a browser configured to allow per-session cookies (cookies that are not stored on the user’s hard disk) but not stored cookies, the user can log on and use the site but is not able to place products in the shopping basket. If no cookies are allowed at all, the user is not able to access the site.

Chapter 9: ConsolidatedRetail.com Functionality 121

Registering a User A user can register with the site by using the Registration.pasp page. When this page is rendered using the Registration-IE5.xsl style sheet, it contains a form that posts the data back to itself. The Registration.pasp page contains code to perform the following tasks: 1. Examine the data in the form to determine the Mode and ProcessAction parameters. Mode is used to indicate the page the user should be redirected to when registration is complete (the default is Acct.pasp). ProcessAction is used to decide if the registration form should be displayed so that a user can register, or if the form is being posted back for processing. 2. Pass the registration data to the PutUserObject so that a new profile can be created. PutUserObject is defined in the Profile.asp include file. 3. Redirect the user to the Acct.pasp page (or another page determined by the Mode parameter). The Registration.pasp page retrieves the Mode and ProcessAction values from the query string by using the MSCSAppFrameWork application-level variable, as shown in the following code: strPageMode = _ Application("MSCSAppFrameWork").RequestString( _ "Mode", Null, , , True, True, 0, Null) strProcessingAction = _ Application("MSCSAppFrameWork").RequestString( _ "ProcessAction", Null, , , True, True, 0, Null)

Mode is usually null, meaning that when a user successfully registers, he or she should be redirected to the account management page (Acct.pasp). In some circumstances, Mode contains the name of an alternate page to which the user should be redirected. For example, if an anonymous user adds products to a shopping basket before registering, you may want to send the user back to the checkout page after he or she registers. The ProcessAction parameter is used to determine whether the user accessed the registration page from another page in the site, in which case the registration form renders, or from the registration page itself, in which case the contents of the registration form are used to register the user. If the ProcessAction parameter is EditUserObject, then the user can be registered using the data in the form on the page. Next, the script retrieves the form data and passes it to the PutUserObject function, which is defined in the Profile.asp include file. This include file contains numerous

122 Reference Architecture for Commerce

procedures for managing user profiles that are used by various pages in the site. The PutUserObject function is used to add or update a user profile and returns a Boolean value indicating success or failure. If the user creation is successful, the user is logged on and redirected to another page. If not (for example, because the specified user name already exists), the Registration.pasp page redisplays with an error message indicating the problem. The code calls the GetGuaranteedUserID function in Profile.asp to retrieve the user ID. This function returns an authenticated user ID for a user who is logged on or a profile user ID for an anonymous user. Profile.asp uses the following code to check whether a user with the specified user name already exists: If Not Application("MSCSProfileService") Is Nothing Then strUserID = GetUserID If Not IsNull(strUserName) Then Set objMSCSProfile = Application("MSCSProfileService").GetProfile(strUserName, mc_strUserObject, blnReturnCode) If Not (objMSCSProfile Is Nothing) Then Call AddException(m_varrExceptions, 1, "Username already exists.", mc_strPageName) Set objMSCSProfile = Nothing

If the user name has not been used already, the code generates a globally unique identifier (GUID) to add the user and calls the CreateProfile method of the ProfileService object. The values passed from the registration form are assigned to the profile: strUserID = GenerateGUID() Set objMSCSProfile = Application("MSCSProfileService").CreateProfile(_ strUserName, mc_strUserObject) objMSCSProfile.Fields(mc_strGeneralInfo).Value_ (mc_strUser_ID)= cstr(strUserID) objMSCSProfile.Fields(mc_strAccountInfo).Value_ (mc_strAccount_Status)= CInt(1) objMSCSProfile.Fields(mc_strGeneralInfo).Value_ ("user_type")= strUserType objMSCSProfile.Fields(mc_strGeneralInfo).Value_ (mc_strUser_Security_Password)= strPassword objMSCSProfile.Fields(mc_strAccountInfo).Value_ ("date_registered")= Now() objMSCSProfile.Fields(mc_strProfileSystem).Value_ ("date_created") = strCreateDate

Chapter 9: ConsolidatedRetail.com Functionality 123

Most of the code on the remainder of Profile.asp is used to update existing user objects. Finally, the profile object is updated and the function returns True: objMSCSProfile.Update Set objMSCSProfile = Nothing PutUserObject = True

When this function completes, the new user is registered in the site database. After the user registers, Registration.pasp redirects the browser to Acct.pasp (if the Mode parameter is NULL) or to an alternate page specified in the Mode parameter: If blnRegistered Then If IsNull(strPageMode) Then Response.redirect "Acct.pasp?Mode=" & strPageMode Else Response.Redirect strPageMode & "?Mode=" & strPageMode End If End If

Authenticating a User To access their profile information, registered users must log on and be authenticated. As explained earlier, newly registered users are automatically logged on by the code in Registration.pasp. Returning customers, however, must provide a user name and password to be authenticated. Note: In this sample application, the logon details are passed in plain text using HTTP. In a production site, Hypertext Transfer Protocol, Secure (HTTPS) should be used to encrypt the security credentials. The security of information, including credentials and confidential user data, is the responsibility of the production site developer. Developers should take all necessary precautions to ensure that authentication credentials and confidential information, such as credit card numbers, order history, shopping lists, and so on, are adequately protected.

Users can log on by using the Login.pasp page. Like Registration.pasp, this page posts data to itself and uses the functionality of Profile.asp to process the data. The Login.pasp page contains code to perform the following tasks: 1. Examine the data in the form to determine the Mode and ProcessAction parameters. Mode indicates the page that the user should be redirected to when the logon process is complete (the default is Acct.pasp). ProcessAction designates whether the user credentials form should be displayed so that a user can log on, or if the form is being posted back for processing. 2. Retrieve the user credentials from the form. 3. Pass the credentials to the Logon function in Profile.asp.

124 Reference Architecture for Commerce 4. Redirect the user to the Acct.pasp page (or another page determined by the Mode

parameter). The most important code in Login.pasp is a call to the Logon function in Profile.asp: blnLoginSuccessful = Logon(strUserName, strPassword)

The Logon function is used to validate a user’s user name and password and send an authentication ticket in the form of a cookie to the client browser. The Logon function performs the following tasks: 1. Create and initialize an AuthManager object, as follows: Set objMSCSAuthMgr = _ Server.CreateObject(mc_strAuthManager) Call objMSCSAuthMgr.Initialize _ (Application("MSCSDictConfig").s_SiteName)

2. Remove any existing authentication ticket that the user may have from a previ-

ous session: If objMSCSAuthMgr.IsAuthenticated Then call objMSCSAuthMgr.SetAuthTicket _ ("", blnCookieSupport, _ Application("MSCSDictConfig")._ i_FormLoginTimeOut) End If

3. Check to ensure that a non-blank user name has been provided, and then use the

application-level MSCSProfileService object to load the profile for the user with the specified name: Set objMSCSProfileObject = _ Application("MSCSProfileService").GetProfile(strUserName, _ mc_strUserObject, blnReturnCode)

4. If a matching profile for a registered user is found, retrieve the password and

user ID, and then compare the password to the password provided by the user: strProfilePassword = _ objMSCSProfileObject(mc_strGeneralInfo).Value _ (mc_strUser_Security_Password) strUserID = objMSCSProfileObject(mc_strGeneralInfo). _ Value (mc_strUser_ID) If CStr(strProfilePassword) = CStr(strPassword) Then ...

Chapter 9: ConsolidatedRetail.com Functionality 125

5. One of the design features of the ConsolidatedRetail.com site is the ability to add

products to a shopping basket while browsing anonymously. If the user adds items to the shopping basket prior to logging on, the user will have been issued an anonymous profile ticket. The AuthManager object now retrieves this ticket so that the contents of the anonymous user’s shopping basket can be transferred to the authenticated user’s shopping basket: strProfileUserID = _ objMSCSAuthMgr.GetUserID(mc_bytProfileTicketType)

6. Issue a new (authenticated user) ticket to the user and set the anonymous cookie

to a blank value (thus deleting it): Call objMSCSAuthMgr.SetAuthTicket _ (strUserID, blnCookieSupport, _ Application("MSCSDictConfig"). _ i_FormLoginTimeOut) Call objMSCSAuthMgr.SetUserID(mc_bytAuthTicketType, _ strUserID) Call objMSCSAuthMgr.SetUserID(mc_bytProfileTicketType, "") Call objMSCSAuthMgr.SetProfileTicket("", blnCookieSupport)

7. Transfer any products in the anonymous shopping basket to the authenticated

user’s shopping basket, and then declare the logon a success: If (Len(strProfileUserID) > 0) Then ' get the profile object from their anonymous ' session Set objMSCSUnRegProfileObject = Application( _ "MSCSProfileService").GetProfilebykey( _ mc_strUser_ID, strProfileUserID, _ mc_strUserObject, blnReturnCode) ' if we get a matching anonymous profile back If Not (objMSCSUnRegProfileObject Is Nothing) Then ' transfer basket contents from anon id to registered ' id Call MoveBasketItems(strProfileuserid, strUserID) ' delete the anonymous profile from the profile store Call Application("MSCSProfileService"). _ DeleteProfileByKey(mc_strUser_ID, _ strProfileUserID, mc_strUserObject) End If Set objMSCSUnRegProfileObject = Nothing End if ' return successful logon value Logon = True

126 Reference Architecture for Commerce

For the remainder of the session, the authentication cookie is presented with each request, and the code is able to retrieve the user’s profile information.

Using Passport Authentication The Reference Architecture application provides its own authentication mechanism as described earlier, as well as support for Microsoft Passport single sign-in (SSI) service. The Reference Architecture application (ConsolidatedRetail.com) displays the Passport Sign In button immediately below the Logon button. A user who has a Passport account can choose to click the Passport Sign In button and use Passport’s standard authentication steps to log on to the site. After the authentication process completes, the user is redirected to ConsolidatedRetail.com. If the user is new to the Reference Architecture application, the application creates a profile for that user and stores it in its Commerce Server 2000-based profile store. After the profile is created, the user is logged on to the Reference Architecture’s authentication system. After logon, the Reference Architecture application manages a Passport user as it does any other user, except that a search for the user’s public lists does not reveal his or her user name. This is because Passport participant sites have guaranteed access to the user’s Pairwise Unique ID (PUID) but not to any other user identification information, such as a name. (The PUID is the 64-bit unique user ID used by the Passport service.) The Reference Architecture application does not display a user’s PUID. Note that the Reference Architecture uses Passport in Test mode. Certain Passport features behave differently in Passport Test mode than in Production mode. In the following description, these differences are noted when relevant. Note also that the Reference Architecture does not provide a log off feature; therefore, ConsolidatedRetail.com does not display a Passport Sign Out button. Passport authentication requires modifications to the schema as well as new code to implement the authentication process. To modify the schema, the logon_name profile property is set to the PUID. Support for Passport is incorporated in the following Reference Architecture files: ● include/Common.asp – This file Initializes the Passport Manager and determines when to display the Passport Sign In button. ● _processPassportLogin.asp – This file retrieves the user’s PUID and e-mail address and determines whether the user has a Reference Architecture application user profile. ● include/UI_layout-ie5.xsl – The mspassport XSL template in this file displays the Passport Sign In button.

Chapter 9: ConsolidatedRetail.com Functionality 127

Passport authentication involves the following steps: 1. The include/Common.asp file contains code that initializes the Passport Manager object. It also contains code that determines when to display the Passport Sign In button on the left side of a page and on the Logon page. The GetPassportLogo function determines the display of the Passport Sign In button. GetPassportLogo is called only if the user is anonymous. The operations in GetPassportLogo performs the following tasks: a. It obtains the session expiration time from the Commerce Server 2000 Application Default Configuration options variable, i_FormLoginTimeOut. b. It calls the IsAuthenticated method of the Passport Manager object. IsAuthenticated checks whether the user is still signed in to Passport, but has timed out of the Reference Architecture. In this case, the user is logged on automatically to the Reference Architecture application. 2. Next, the code determines whether the user signed in using the Passport Auto-

matic Sign In facility. If the user did sign in to Passport automatically, he or she is logged on to the Reference Architecture, using the following code: If PassportManager.HasTicket then If PassportManager.HasSavedPassword Then Server.Execute(PassportReturnPage) Exit Sub End If End If

When Passport runs under Test mode, certain Passport cookies are not removed when the user’s session times out or when the user closes the browser. If not removed, these cookies generate a Passport Sign Out button rather than a Passport Sign In button the next time the user accesses the site. To resolve this issue, the code removes these cookies so that the Passport Sign In button can display. (Typically, these cookies are deleted using a log off page. However, because the Reference Architecture does not provide a log off page, the cookies must be deleted by the same page that contains the Passport Sign In button.) To ensure that the cookie deletion code is not called when it isn’t needed, the code is enclosed in an appropriate conditional statement: If PassportManager.HasTicket then . . . End If

3. The code uses the LogoTag() method of the Passport Manager object to display

the Passport Sign In button, which is appropriately inserted into the outgoing XML stream.

128 Reference Architecture for Commerce 4. After the user successfully logs on, Passport redirects the user to

ProcessPassportLogin.asp. This page retrieves the user’s PUID and e-mail address and determines whether the user has a Reference Architecture application user profile. If not, it uses the PutUserObject function to create the user profile. A Passport user’s profile is distinguished from non-Passport user profiles because it has an empty password. After creating the profile, the user is logged on to the Reference Architecture application, and then redirected to an appropriate page.

Retrieving and Updating Profile Information The site allows a user to access, view, and edit his or her profile information from numerous pages. Each page uses similar code to update fields in the user’s profile; therefore, this chapter discusses only the UserProfile.pasp page in detail. You may want to examine the code in EditAddressBook.pasp and ChangePasswd.pasp, which perform similar functions. Note: The ConsolidatedRetail.com site does not make any provisions for deleting or removing expired or stale user information. If you use the Commerce Server 2000 Business Desk to delete a user, that user’s personal information may be persisted in the site databases. This information includes, but is not limited to, addresses, credit card numbers, and order history. You will need to add functionality or processes to delete that information if your business rules so dictate.

The UserProfile.pasp page contains a form that allows a user to view and change the profile values for first name, last name, e-mail address, phone, and fax number. It is similar in design to the Registration.pasp page discussed earlier, and it contains code to perform the following tasks: 1. Check the ProcessAction query string value. ● If the query string value is EditUserObject, then the page has posted the form contents to itself and the profile must be updated. Go to Step 2. ● If the query string value is not EditUserObject, there are no changes to the profile. Go to Step 4. 2. Retrieve the form values from the query string. 3. Pass the form values to the PutUserObject function in Profile.asp. 4. If the form values are not saved successfully or there are no changes to the

profile (that is, the query string value is not EditUserObject), format the existing profile values as XML. As explained earlier, the PutUserObject function is used to register a new user when a user name is passed to it. If no user name is passed, then the function assumes that the user already exists and attempts to update the data in the existing profile.

Chapter 9: ConsolidatedRetail.com Functionality 129

To access the profile, PutUserObject uses the GetUserID function in Common.asp to retrieve the current user’s ID from the authentication ticket, as follows: Function GetUserID() Dim objMSCSAuthMgr 'Authentication Manager Dim strUser_ID ' user id retrieved from the ' authentication manager ' Instantiate and initialize AuthManager object. Set objMSCSAuthMgr = _ Server.CreateObject(mc_strAuthManager) Call objMSCSAuthMgr.Initialize _ (Application("MSCSDictConfig").s_SiteName) strUser_ID = Null ' If user has authenticated and auth ticket hasn't ' timed out If objMSCSAuthMgr.IsAuthenticated Then ' grab the unique logon id they authenticated to. strUser_ID = _ objMSCSAuthMgr.GetUserID(mc_bytAuthTicketType) ' otherwise, If they're browsing anonymously Else ' get profile user id, which is a GUID. ' If the getuserid method return a empty string ' convert the string to Null strUser_ID = _ objMSCSAuthMgr._ GetUserID(mc_bytProfileTicketType) If not isNull(strUser_ID) Then If len(trim(strUser_ID)) = 0 Then strUser_ID = Null End If End If End If ' return the new GUID or their current authenticated ' username GetUserID = strUser_ID Set objMSCSAuthMgr = Nothing End Function

To retrieve the user profile, the code in the PutUserObject function in Profile.asp uses the GetProfileByKey method of the ProfileService object: Set objMSCSProfile = Application("MSCSProfileService").GetProfilebyKey( _ mc_strUser_ID, strUserID, mc_strUserObject, blnReturnCode)

130 Reference Architecture for Commerce

Finally, the code updates the profile fields for the user: objMSCSProfile.Fields(mc_strGeneralInfo).Value( _ mc_strFirst_Name) = strFirstName objMSCSProfile.Fields(mc_strGeneralInfo).Value( _ mc_strLast_Name) = strLastName objMSCSProfile.Fields(mc_strGeneralInfo).Value( _ mc_strEmail_Address)= strEmailAddress objMSCSProfile.Fields(mc_strGeneralInfo).Value( _ mc_strTel_Number) = strTelNumber objMSCSProfile.Fields(mc_strGeneralInfo).Value( _ mc_strWork_Number) = strWorkNumber objMSCSProfile.Fields(mc_strGeneralInfo).Value( _ mc_strWork_Extension) = strWorkExtension objMSCSProfile.Fields(mc_strProfileSystem).Value( _ mc_strDate_Last_Changed) = Now objMSCSProfile.Update

If the profile was not updated (that is, the ProcessAction query string was not set to EditUserObject) or the attempt to update the profile was unsuccessful, then the code in UserProfile.pasp calls the GetUserObjectXML procedure to render the entire user profile as XML (only the fields referenced in UserProfile-IE5.xsl are actually displayed, but the style sheet could be modified to show additional profile information without changing this code). The GetUserObjectXML procedure uses the GetProfileByKey method of the ProfileService object to retrieve the user’s profile. Then the XML helper routines in include/Common.asp are used to render the data. The GetUserObjectXML routine (located in Profile.asp) contains code similar to the following: Sub GetUserObjectXML() Dim Dim Dim Dim Dim

objMSCSProfile strUserID Field Group blnReturnCode

strUserID = GetUserID If Not IsNull(strUserID) Then ' initialize profile service & connect to profile store using specified ' schema If Not Application("MSCSProfileService") Is Nothing Then ' use profile service to retrieve profile object for user, and assign ' that object to function's return value Set objMSCSProfile = Application("MSCSProfileService") _ .GetProfilebyKey(mc_strUser_ID, GetUserID, _

Chapter 9: ConsolidatedRetail.com Functionality 131 mc_strUserObject, blnReturnCode) If Not objMSCSProfile Is Nothing Then Call XMLBegTag(c_strProfile) For Each Group In objMSCSProfile.Fields Call XMLBegTag(Group.Name) For Each Field In Group.value If Field.Name PASSPORT_DEFINATION Then Call XMLTag(Field.Name, Field.Value) End If Next Call XMLEndTag(Group.Name) Next Call XMLEndTag(c_strProfile) End If Set objMSCSProfile = Nothing End If End If End Sub

UserProfile.pasp produces the following XML output: MYCOMP%3A85 15 CheckName txtFirstName Please enter a valid first name. 15 CheckName txtLastName Please enter a valid last name. 40 CheckEmail txtEmailAddress Please enter a valid email address. 14 CheckPhoneFaxNumber txtTelNumber Please enter a valid phone number. 14 CheckPhoneFaxNumber txtWorkNumber

132 Reference Architecture for Commerce Please enter a valid fax number. 1 8/28/2001 5:53:00 PM {AD855214-144A-432B-A03C-7F6F261B64EF} Kim [email protected] 1 Abercrombie Kim 555-555-5555 555-555-5555 8/28/2001 5:54:58 PM 8/28/2001 5:52:23 PM Browse Catalogs: Books Books Hardware Hardware

The ConsolidatedRetail.com site provides effective profile functionality and demonstrates the basic techniques for creating, retrieving, and updating user profile information. You could extend this functionality to creating custom profile properties by using the Commerce Server Manager, and you could use the profile information to personalize the site for individual users. For more information about using Commerce Server 2000 profiling functionality, refer to the Commerce Server 2000 documentation.

Chapter 9: ConsolidatedRetail.com Functionality 133

Product Catalogs One of the most important aspects of implementing an e-commerce site is providing an easy way for customers to browse the catalogs. The ConsolidatedRetail.com site does this in four ways: ● Catalogs are always listed in the user interface. ● Users can browse through hierarchically organized categories. ● Users can search all or some of the catalogs for a particular string. ● Users can browse through the product detail pages in a single catalog or in a search result (wizard browsing).

Catalog Access There may be catalogs for which limited access is appropriate. To require authentication for access to a specific catalog, you can use the Business Desk to specify that user authentication is required. Thereafter, each time a user attempts to browse, search, or use a list to view products in a restricted catalog, the Reference Architecture application checks to see that the user is authenticated and has access to that catalog. (To prevent performance degradation, this validation process uses the CatalogsetId and CatalogSetCache.) The Reference Architecture code performs this validation when a user attempts to access the following pages: ● Public or private Shopping List ● Save for Later basket ● Product detail page ● Category browse page ● Search results ● Advanced search results Code to enable this validation appears in the following files: ● Include/Basket.asp ● Include/Site_Const.asp ● Xml/rc.xml ● _additem.asp ● _additemsfromlist.asp ● _moveitemsfromsfl.asp ● Basket.asp ● Category.pasp ● Product.pasp ● SearchResults.pasp ● StepSearch.pasp

134 Reference Architecture for Commerce

The catalogs available to the current user are always listed in the left pane of the user interface. This is achieved by including the code to determine the available catalogs and display them in the PageEnd procedure in Common.asp, as described next: 1. Retrieve a list of catalogs based on user type by checking the constant for CatalogSetCache, which identifies the catalog set assigned to the user: Sub PageEnd() Dim strOut strOut = CachedFragmentLookup( CATALOGSET_CACHE , GetDefaultCatalogSet() ) Response.Write strOut

2. Call GetDefaultCatalogSet, which returns the registered default catalog set for

an authenticated, registered user or the anonymous default catalog set for all other users. To confirm the user’s authentication credentials, instantiate and initialize an AuthManager object: GetDefaultCatalogSet() Dim objMSCSAuthMgr Set objMSCSAuthMgr = Server.CreateObject(mc_strAuthManager) Call objMSCSAuthMgr.Initialize(Application("MSCSDictConfig").s_SiteName)

3. If the user is authenticated, and the authentication ticket has not timed out,

retrieve the catalog set assigned to that user. If objMSCSAuthMgr.IsAuthenticated() Then 'DefaultRegisteredCatalogSet GetdefaultCatalogSet = Application("MSCSDictConfig"). s_AuthenticatedUserDefaultCatalogSet

4. Otherwise, retrieve the catalog set for anonymous users, and clear the

AuthManager object. Else 'DefaultAnonymousCatalogSet GetDefaultCatalogSet = Application("MSCSDictConfig").s_ AnonymousUserDefaultCatalogSet End If Set objMSCSAuthMgr = Nothing End Function

When the XML produced by this code is rendered using the UI_layout-IE5.xsl style sheet, the resulting Web page displays the name of each catalog in the catalog set as a link to Category.pasp. The XML fragment generated looks like the following: Books Books

Chapter 9: ConsolidatedRetail.com Functionality 135 Hardware Hardware

Browsing the Catalogs The catalogs in the ConsolidatedRetail.com site are implemented as hierarchical structures. Two catalogs, called books and hardware, each contain several categories. The books catalog also contains a layer of sub-categories. Products can be stored in any level of the catalog. The page used to browse the catalog data in the ConsolidatedRetail.com site is Category.pasp. The page can be used in one of two modes: root-level mode and category mode. In root-level mode, the page retrieves the products and categories from the root of the specified catalog. In category mode, the page retrieves the products, sub-categories, and parent categories from the specified category. The page contains code to perform the following tasks: 1. Use the MSCSAppFrameWork object to retrieve the txtCatalog and txtCategory values passed in the request string. If no txtCatalog value is found, the page redirects the user to Index.pasp. 2. Call PageStart to generate the XML header for the page. 3. Retrieve the ProductCatalog object for the specified catalog from the MSCSCatalogManager application variable, and write the catalog name into a XML element. 4. Render the properties of the catalog as XML. This allows properties such as the catalog name to be rendered in the user interface. 5. Determine whether or not a category name was passed in the request string. If no category name was specified, then the page retrieves the categories and products from the root of the catalog and formats them as XML. If a category was provided, then the page retrieves the data from that category and formats it as XML. 6. Call the PageEnd procedure to close the XML document. Before using the Commerce Server Catalog objects to retrieve catalog information, the page uses the following code to create a element: Call XMLTag(c_strSearchScope, strCatalogName)

The UI_layout-IE5.xsl style sheet uses this element to pass the current catalog name to the search functionality, thus scoping the search. (The search functionality is described in detail later in this chapter.)

136 Reference Architecture for Commerce

The actual catalog data is retrieved using a hierarchy of Commerce Server automation objects. At the top of the hierarchy is the CatalogManager object, which is used for all programmatic access to the catalog system. The CatalogManager object contains ProductCatalog objects, which represent the catalogs in the site. In Category.pasp¸ the GetCatalog method of the MSCSCatalogManager applicationlevel variable is used to retrieve the specified catalog as shown in the following code snippet: Set objMSCSPrdCat = Application("MSCSCatalogManager"). _ GetCatalog(strCatalogName)

The properties of a ProductCatalog object can be retrieved as an ActiveX® Data Objects (ADO) recordset by using the GetCatalogAttributes method. The code in Category.pasp uses this method and passes each row in the recordset to the GetXMLFromRSWithDsplyNm routine in Common.asp, which formats the row as XML: Set rsProperties = objMSCSPrdCat.GetCatalogAttributes If Not (rsProperties.EOF And rsProperties.BOF) Then strOut = strOut & XMLBegTagEx(c_strGetCatalogAttributes) Do While Not rsProperties.EOF 'get xml version of recordset row strOut = strOut & GetXMLFromRSWithDsplyNmEx(rsProperties) rsProperties.MoveNext Loop If IsNull(strCategoryName) Then strOut = strOut & XMLTagEx("currentcatagoryname", "") Else strOut = strOut & XMLTagEx("currentcatagoryname", strCategoryName) End If strOut = strOut & XMLEndTagEx(c_strGetCatalogAttributes) End if

This results in an XML fragment with the following format: Books Books 8 8 12/8/1999 12%2F8%2F1999 12/8/2006 12%2F8%2F2006 ISBN ISBN Title Title USD

Chapter 9: ConsolidatedRetail.com Functionality 137 USD lbs lbs 1 1 False False 6/7/2001 11:23:01 AM 6%2F7%2F2001+11%3A23%3A01+AM 6/7/2001 11:22:17 AM 6%2F7%2F2001+11%3A22%3A17+AM

A recordset object is also used to represent the categories in the root of a catalog. The RootCategories method is used to retrieve this as shown in the following code snippet from Category.pasp (note the use of the Fields collection property to retrieve a named data field from the recordset): Set rsCategories = objMSCSPrdCat.RootCategories If Not (rsCategories.EOF And rsCategories.BOF) Then strOut = strOut & XMLBegTagEx(c_strRootCategories) Do While Not rsCategories.EOF strOut = strOut & XMLBegTagEx(c_strRootCategory) strOut = strOut & XMLTagWithDsplyNmEx("catalogname", objMSCSPrdCat.catalogname) strOut = strOut & XMLTagWithDsplyNmEx("catalognameurl", Server.URLEncode(objMSCSPrdCat.catalogname)) strOut = strOut & XMLTagWithDsplyNmEx("categoryname", rsCategories.fields("CategoryName").value) strOut = strOut & XMLTagWithDsplyNmEx("categorynameurl", Server.URLEncode(rsCategories.fields("CategoryName").value)) strOut = strOut & XMLEndTagEx(c_strRootCategory) rsCategories.MoveNext Loop

This produces an XML fragment, similar to the following: Books Books Business Software Business+Software Books Books Development Tools

138 Reference Architecture for Commerce Development+Tools Books Books Featured Products Featured+Products Books Books Games Games Books Books Hardware Hardware Books Books Home Productivity Home+Productivity Books Books Internet Products Internet+Products Books Books Operating Systems Servers Operating+Systems++Servers Books Books Reference Reference Browse Categories:

Similarly, a recordset containing products in the root of a catalog can be retrieved using the RootProducts method: Set rsProducts = objMSCSPrdCat.RootProducts

Chapter 9: ConsolidatedRetail.com Functionality 139

XML similar to the following is generated for each product in the rsProducts recordset: 64 SDKBook 19.99 19.99 4 -1 Microsoft Age of Empires II: The Age of Kings: Inside Moves Microsoft Age of Empires II: The Age of Kings: Inside Moves 0-7356-0513-0 Master all the vital strategic gambits, tips, and tricks for winning with this official guide to the exciting new version of Microsoft Age of Empires! MICROSOFT AGE OF EMPIRES II: AGE OF KINGS: INSIDE MOVES shows you how to survive and thrive in the thousand years from the fall of Rome to the Middle Ages. boxshots/press/2388.gif 120 120 Microsoft Corporation Microsoft Age of Empires II: The Age of Kings: Inside Moves 280 a href=http://mspress.microsoft.com/ prod/books/2388.htm target =_a http://mspress.microsoft.com/prod/books/2388.htm /a 1999 Microsoft Press All Levels Books

If your code needs to delve deeper into the catalog and retrieve the contents of one of the categories, you can use a Category object. The Category.pasp page uses a Category object to access the contents of a specified category. The object is instantiated using the GetCategory method of the ProductCatalog object, as shown in the following code snippet: Set objMSCSCategory = _ objMSCSPrdCat.GetCategory(strCategoryName)

140 Reference Architecture for Commerce

You can retrieve the products in a category as a recordset by using the Products property: Set rsProducts = objMSCSCategory.products

The Category object also provides a ChildCategories property for retrieving a recordset of sub-categories and a ParentCategories property for returning a recordset of the parent level of categories. You can use the Commerce Server Business Desk to create relationships between categories and products in a product catalog, regardless of their location in the hierarchy. The Category object provides RelatedCategories and RelatedProducts properties to retrieve recordsets containing these. You can see examples of the use of all of these objects in Category.pasp.

Viewing a Product The style sheet used to render the catalog data generates HTML, so that when a user clicks the Get Details link for a particular product, the Product.pasp page is requested. This page displays data specific to the selected product. The code in Product.pasp begins very similarly to Category.pasp. It checks the request string to retrieve the catalog, product ID, and optional product variant values, and then redirects the user to Index.pasp if the catalog or product ID parameters are missing. Then it calls PageStart to begin generating the XML for the page. The code begins to get interesting when a Commerce Server Product object is retrieved from the Catalog object by using the GetProduct method: Set objMSCSPrd = objMSCSPrdCat.GetProduct(strProductID)

You can retrieve the properties of the product, such as its name and price, in a recordset object by using the GetProductProperties method: Set rsProduct = objMSCSPrd.GetProductProperties

Products in a Commerce Server catalog support variants (such as color or size). You can retrieve the list of variants for a particular product as a recordset by using the Variants property. Additionally, you can retrieve any related products or categories by using the RelatedProducts and RelatedCategories properties, which allow links to be created for cross-selling opportunities. These properties are all used in the Product.pasp page to produce the XML data for the product, a fragment of which is shown in the following code:

Chapter 9: ConsolidatedRetail.com Functionality 141 Books SDKBook SDKBook 19.99 19%2E99 19.99 a+href%3Dhttp%3A%2F%2Fmspress%2Emicrosoft%2Ecom%2Fprod%2Fbooks% 2F2388%2Ehtm++target+%3D%5Fa+++http%3A%2F%2Fmspress%2Emicrosoft%2Ecom%2Fprod% 2Fbooks%2F2388%2Ehtm+%2Fa 1999 1999 Microsoft Press Microsoft+Press All Levels

142 Reference Architecture for Commerce All+Levels Microsoft Age of Empires II: The Age of Kings: Inside Moves Microsoft+Age+of+Empires+II%3A+The+Age+of+Kings%3A+Inside+Moves

Depending on the user’s request, the XML is then rendered using the appropriate XSL style sheet. ● If the user’s request returns a category of products, the Category-IE5.xsl style sheet is used. The category page uses the productvariant/productfamily template to display product variants, as shown in the following code sample: Family: Product.pasp?txtCatalog=&txtCategory=&txtProductID=&isVariant=1 — ●

If the user’s request returns one or more products, the Product-ie5.xsl style sheet is used. The product page uses the productvariant/productfamily template and the variant template to display product variants, as shown in the following code sample:

Chapter 9: ConsolidatedRetail.com Functionality 143

		price: $ qty: Item added ( items in shopping cart)
About the
If you are interested in this product, you may also be interested in these items. If you are interested in this product, you may also be interested in this 1 item.

146 Reference Architecture for Commerce . . .

Chapter 9: ConsolidatedRetail.com Functionality 147

Navigating the Product Detail Pages The Product.pasp pages include Next and Previous buttons, which allow the user to move from one product detail page to the next and back again. The code implements this functionality as follows. 1. Determine if there are next and/or previous products in the category, and if so, assign a product identifier to them: If Not IsNull(strCategoryName) Then Set objMSCSPrdCat = Application("MSCSCatalogManager").GetCatalog(strCatalogName) If Not (objMSCSPrdCat Is Nothing) Then Set objMSCSCategory = objMSCSPrdCat.GetCategory(strCategoryName) If Not (objMSCSCategory Is Nothing) Then Set rsProducts = objMSCSCategory.Products If Not (rsProducts Is Nothing) Then rsProducts.Find "productid = #" & strProductID & "#"

2. If the user clicks the Previous button and this isn’t the first product in the record-

set, display the detail page for the product identified as the previous product: rsProducts.MovePrevious If Not (rsProducts.BOF) Then strOut = strOut & XMLBegtagEx("Previous") strOut = strOut & GetXMLFromRSWithDsplyNmEx(rsProducts) strOut = strOut & XMLEndTagEx("Previous") End If

148 Reference Architecture for Commerce 3. If the user clicks the Next button and this isn’t the last product in the recordset,

display the detail page for the product identified as the next product: rsProducts.MoveNext rsProducts.MoveNext If Not (rsProducts.EOF) Then strOut = strOut & XMLBegtagEx("Next") strOut = strOut & GetXMLFromRSWithDsplyNmEx(rsProducts) strOut = strOut & XMLEndTagEx("Next") End If

Note: The Category browse page displays products with variants at the end of the page. For example, if the user displays the Featured Products category of the Hardware catalog, a product with variants — such as the Microsoft IntelliMouse® with IntelliEye™ — is listed at the end of the page. However, if a user clicks the Next or Previous button to display product details, the product pages are displayed sequentially based on their product ID values. For example, if a category contains five products that have product IDs of 1, 2, 3, 4, and 5, and products 2 and 4 have variants, the Category browse page displays the products in the following order: 1, 3, 5, 2, and 4 (products with variants are displayed at the end of the page). If a user selects the product with product ID 1, clicks the Get Details button, and then clicks the Next button, the next product to be displayed is product ID 2 (despite the fact that it has variants).

Searching the Catalogs In addition to providing pages that allow users to browse the catalogs, an effective site also provides a search capability. In the ConsolidatedRetail.com site, users can enter search criteria and search all catalogs or a single catalog for a specific product. In addition, users can specify parameters, such as greater than (>), less than (product(s) found for search criteria 'Age of Empires'.

Depending on the user’s request, the XML is then rendered using the appropriate XSL style sheet. ● If the user uses the Search box to search by keywords, the SearchResults-IE5.xsl style sheet is used. The search results page uses the productvariant/ productfamily template to display product variants, as shown in the following code sample: Family: Product.pasp?txtCatalog=&txtCategory=&txtProductID=&isVariant=1 — ●

If the user uses Advanced Search, the StepSearch-IE5.xsl style sheet is used. The search results page uses the productvariant/productfamily template to display product variants, as shown in the following code sample: Family: Product.pasp?txtCatalog=&txtCategory=&txtProductID=&isVariant=1 —

Adding a New Catalog To add a catalog to the Reference Architecture application, follow the instructions provided in Chapter 2 to import a catalog through Commerce Server 2000 Business Desk.

Shopping Basket Management Like most business-to-consumer sites, ConsolidatedRetail.com uses the concept of a shopping cart or basket to contain products that a user selects for purchase. ConsolidatedRetail.com allows customers who log on as well as anonymous users to add products to a shopping basket; however, anonymous users must log on before checking out.

152 Reference Architecture for Commerce

Adding Products to the Shopping Basket When a user clicks the add to cart button on the product detail page, the product and quantity information are posted to the _additem.asp page. Before redirecting the user to the Basket.pasp page, where the contents of the shopping basket are displayed, this page contains code to perform the following tasks: 1. Use the catalogset ID to confirm that the user can view and order the requested item. (To prevent performance degradation, this validation step uses the CatalogSetCache.) 2. Retrieve the category, product, variant, and catalog values posted in the query string. 3. Validate the quantity value passed in the query string (if no quantity is passed, then 1 instance of the item is added). 4. Load the user’s shopping basket into an OrderGroup object. 5. If the product is already listed in the shopping basket, add the specified quantity to the existing entry; otherwise, create a new entry for this product. 6. Redirect the user to Basket.pasp. The _additem.asp page calls the LoadBasket function in the Basket.asp include file to retrieve an OrderGroup object containing the current user’s shopping basket. The LoadBasket function looks like the following: Function LoadBasket(strUserID) Dim objMSCSOrderGroup Set objMSCSOrderGroup = Server.CreateObject( _ mc_strOrderGroup) Call objMSCSOrderGroup.Initialize(Application( _ "MSCSDictConfig").s_TransactionsConnectionString, _ strUserID) Call objMSCSOrderGroup.LoadBasket() Set LoadBasket = objMSCSOrderGroup Set objMSCSOrderGroup = Nothing End Function

Notice that an OrderGroup object is created and initialized by passing the transaction connection string defined in the MSCSDictConfig application variable and the current user’s user ID. (The user ID is obtained from the GetGuaranteedUserID function in the Profile.asp include file, which returns an authenticated user ID for a user who is logged on or a profile user ID for an anonymous user.) Next the LoadBasket method of the OrderGroup object is called to retrieve the contents of the shopping basket associated with the current user. After loading the shopping basket, the code in _additem.asp searches the line items in the shopping basket to find out if the requested product is already listed. If it is

Chapter 9: ConsolidatedRetail.com Functionality 153

already in the shopping basket, the specified quantity is added to the order, as follows: blnSkuMatched = False 'If there are line items If objMSCSOrderGroup.Value("total_lineitems") > 0 Then 'loop through each one to look for a matching sku For Each colItem in objMSCSOrderGroup.Value _ ("OrderForms").Value("default").Items If IsNull(strVariantID) Then If (Trim(Cstr(colItem.product_id)) = _ Trim(Cstr(strProductID))) And _ IsNull(colItem.product_variant_id) Then blnSkuMatched = True Exit For End If Else If (Trim(Cstr(colItem.product_id)) = Trim(Cstr(strProductID))) Then If Not IsNull(colItem.product_variant_id) Then If (Trim(Cstr(colItem.product_variant_id)) = Trim(Cstr(strVariantID)))_ Then blnSkuMatched = True Exit For End If End If End If End If Next If blnSkuMatched Then ' item exist in basket, add new item quantity to existing item quantity Dim intItemtotal intItemtotal = colItem.Quantity + intProductQty If intItemtotal > MAX_ITEM_QUANTITY Then intItemtotal = MAX_ITEM_QUANTITY End If colItem.Quantity = intItemtotal 'Save the new basket Call objMSCSOrderGroup.SaveAsBasket()

If the product is not already listed in the shopping basket, the code calls the AddItemToBasket local function to add it. The AddItemToBasket function creates a Dictionary object to represent the item, and then adds it to the shopping basket by using the AddItem method of the OrderGroup object. Then the shopping basket is saved by the SaveAsBasket method. The code for the AddItemToBasket function resembles the following: Function AddItemToBasket(objMSCSOrderGroup, strProductID, _ strCatalogName, intProductQty, strVariantID, strCategoryName) Dim objMSCSProductDictionary Dim strVariantIdName Dim strVariantName Dim strVariantValue

154 Reference Architecture for Commerce 'create the product dictionary Set objMSCSProductDictionary = Server.CreateObject(mc_strDictionary) objMSCSProductDictionary.lineitem_uid = GenerateGUID() objMSCSProductDictionary.product_id = strProductID objMSCSProductDictionary.product_catalog = strCatalogName objMSCSProductDictionary.Quantity = intProductQty If Not IsNull(strVariantID) Then Call GetProductVariantInfo(strCatalogName,strProductID,strVariantID,_ strVariantIdName,strVariantName,strVariantValue) objMSCSProductDictionary.product_variant_id_name = strVariantIdName objMSCSProductDictionary.product_variant_name = strVariantName objMSCSProductDictionary.product_variant_value = strVariantValue objMSCSProductDictionary.product_variant_id = strVariantID End If If Not IsNull(strCategoryName) Then objMSCSProductDictionary.product_category = strCategoryName End If Call objMSCSOrderGroup.AddItem(objMSCSProductDictionary) Call objMSCSOrderGroup.SaveAsBasket() Set objMSCSProductDictionary = Nothing End Function

Note that the item is added by creating a Dictionary object to represent it and passing it to the AddItem method of the OrderGroup object representing the shopping basket. After the shopping basket is updated, the code in _additem.asp redirects the user to Basket.pasp.

Viewing the Shopping Cart or Save for Later Basket The user can view and edit the contents of the Shopping Cart or Save for Later basket by using the Basket.pasp page. Basket.pasp contains code to perform the following tasks: 1. Check for shopping basket integrity. 2. Retrieve the user’s user ID (from an authenticated ticket or an anonymous profile ticket). 3. If the user’s shopping basket is not empty, use the PAGBasket pipeline to retrieve the shopping basket information to be displayed. 4. Write the total line item count in an XML tag. 5. Convert the shopping basket contents to XML using a Commerce Server DictionaryXMLTransforms object and write it to the response. The page loads the user’s shopping basket and checks to see if there are any products in it by using the following code: Set objMSCSOrderGroup = LoadBasket(strUserID) 'Check to see if the basket has items If Not IsBasketEmpty(objMSCSOrderGroup) Then blnBasketIsEmpty = False End If

Chapter 9: ConsolidatedRetail.com Functionality 155

The code that calls the IsBasketEmpty function, which is in Basket.asp, checks to see if there are items in the OrderGroup object. If the shopping basket contains products, then the basket is passed to the PAGBasket pipeline to prepare it for display: Set objMSCSPipelines = Application("MSCSPipelines") intErrorLevel = _ RunMtsPipeline(objMSCSPipelines.PAGBasket, _ objMSCSPipelines.LogFolder & strUserID & _ ".log", _ objMSCSOrderGroup)

PAGBasket Pipeline Pipelines are used to configure a series of components that operate on a business object in a set sequence. The operations of the pipeline are divided into stages. In this case, the PAGBasket pipeline contains components that operate on the OrderGroup object that represents the user’s shopping basket. You can use the Commerce Server Pipeline Editor to view the configuration of the PAGBasket pipeline by opening the PAGBasket.pcf file in the Pipelines folder of the site. The PagBasket pipeline is illustrated in Figure 9.2:

Figure 9.2 PAGBasket Pipeline

156 Reference Architecture for Commerce

Each time the shopping basket is displayed, the PAGBasket pipeline gathers all data and performs the calculations required to show the shopping basket. Besides running prior to displaying the shopping basket, this pipeline is also executed during the final stages of the checkout process to calculate final order totals. The PAGBasket pipeline includes the following stages: ● The pipeline starts with the Product Info stage. This stage, which is used to manage the product information, consists of the following two components: ● QueryCatalogInfo – The QueryCatalogInfo component retrieves product information from the Catalog System for every product in the order. It adds the retrieved information to each Item dictionary in the order form. ● RequiredProdInfo – The RequiredProdInfo component checks all items in the items collection in the OrderForm, and deletes any products that have the delete key set to 1. ●

●

●

The Order Initialization stage is then used to initialize the proper values in the OrderGroup object. This stage consists of a single component: RequiredOrderInitCy. First, RequiredOrderInitCy ensures that the order_id key has a value. If it does not, RequiredOrderInitCy generates a unique order ID and assigns it to this key. Next, to ensure order integrity, the component initializes the various total keys by assigning NULL to them. Finally, for each item in the items collection, RequiredOrderInitCy copies the value stored in quantity to the _n_unadjusted key to initialize the undiscounted quantity of the item and initialize the _oadjust_adjustedprice (the total cost of the item) to zero (0). The Order Check stage verifies that the order being presented is valid and has all entries necessary for subsequent processing. This stage consists of one component: RequiredOrderCheck. The RequiredOrderCheck component ensures that the items list of the OrderForm is not empty. The Item Price stage sets the _iadjust_regularprice on each item in the OrderForm. This stage consists of the following two components: ● DefaultItemPriceCy – For each item in the order form (each item in the items collection), DefaultItemPriceCy assigns the _iadjust_regularprice key to the value stored in the product_cy_list_price. Stages that follow the Item Price stage in the pipeline contain components that depend upon the _iadjust_regularprice key being set. If this key does not have a value, these components fail. ● RequiredItemPriceCy – The RequiredItemPriceCy component verifies that the _cy_iadjust_regularprice has been set for each item in the items list. Before the RequiredItemPrice component runs, the items list should have been initialized by the DefaultItemPriceCy component to contain the most current pricing information for the item. If _cy_iadjust_regularprice does not contain a value, an error is generated.

Chapter 9: ConsolidatedRetail.com Functionality 157 ●

●

●

The Item Adjust Price stage sets the _iadjust_currentprice on each item in the order form. This stage consists of one component: RequiredItemAdjustPriceCy. RequiredItemAdjustPriceCy verifies that the current price (_cy_iadjust_currentprice) exists for each item in the items list. If this value does not exist, the component creates it and initializes it to the regular price (_cy_iadjust_regularprice). In addition, the component checks the placed price (cy_placed_price) against the current price (cy_iadjust_currentprice) to see if the current price has changed since the user placed the product in the shopping basket. If the placed price does not exist, the component creates it and sets it to the current price (cy_iadjust_currentprice). If the placed price exists, but is not equal to the current price, RequiredItemAdjustPriceCy retrieves the warning message text for a bad placed price from the MessageManager, and writes the message text to the _Basket_Errors collection of the order form. The Order Adjust Price stage sets the _oadjust_adjustedprice on each item in the order form to account for price discounts. This stage consists of the RequiredOrderAdjustPriceCy and OrderDiscount components. For each item, RequiredOrderAdjustPriceCy first calculates the cost of the non-discounted quantity. It multiplies the current price of the item (_cy_iadjust_currentprice) by the undiscounted quantity of the item (n_unadjusted) and adds it to the total cost of the item (_cy_oadjust_adjustedprice). Next, it calculates the discount for the item (cy_oadjust_discount) by calculating the total cost for the item (multiplying the current price of the item (_cy_iadjust_currentprice) by the total quantity (quantity) and subtracting the previously calculated cost of the undiscounted items. OrderDiscount calculates the total of all discounts for the order and displays it on the Basket, Payment, OrderSummary, and ThankYou pages. The Order Subtotal stage sets the _oadjust_subtotal on the order form. This stage consists of the following three components: ● DefaultOrderSubTotalCy – The subtotal (_cy_oadjust_subtotal) is calculated by summing the total cost for each item (_cy_oadjust_adjustedprice) in the items SimpleList in the OrderForm. ● PersistUtility – PersistUtility is a custom component used to copy values within the OrderForm. This is mainly used to persist values. Otherwise, OrderForm values with names that begin with an underscore (_) are not persisted. The source code for the PersistUtility component (written in Visual C++) is provided with the Reference Architecture for Commerce. ● RequiredOrderSubTotalCy – RequiredOrderSubtotalCy checks the _oadjust_subtotal key in the OrderForm to ensure that the value assigned to it is not NULL.

158 Reference Architecture for Commerce

Note: The PAGBasket pipeline contains two additional stages: Merchant Information and Shopper Information. ConsolidatedRetail.com does not use these stages, and they contain no components.

Converting the Basket Contents to XML After the pipeline runs, the code in Basket.pasp checks the OrderGroup object again to ensure that it still contains some products because some may have been removed in the pipeline). If the shopping basket contains products, the contents are converted to XML using a Commerce Server DictionaryXMLTransforms object and written to the Response object. The XML produced by the DictionaryXMLTransforms object is similar to the following: orderform_id="{0F111D4C-E79F-4615-B1AD-9193C811DE86}" saved_cy_oadjust_subtotal="24.99">

The Basket-IE5.xsl style sheet is then used to render the shopping basket page as HTML.

The Lists Pipeline The Lists pipeline is similar to the PAGBasket pipeline, except that it doesn’t verify quantity and price. The Lists pipeline contains components that operate on the OrderGroup object to create a public or private shopping list. You can use the Commerce Server Pipeline Editor to view the configuration of the Lists pipeline by opening the List.pcf file in the Pipelines folder of the site. The Lists pipeline is illustrated in Figure 9.3.

Chapter 9: ConsolidatedRetail.com Functionality 159

Figure 9.3 Lists Pipeline

The Lists pipeline includes the following stages: ● The pipeline starts with the Product Info stage. This stage, which is used to manage the product information, consists of the following two components: ● QueryCatalogInfo – The QueryCatalogInfo component retrieves product information from the Catalog System for every item in the order. It adds the retrieved information to each Item dictionary in the order form. ● RequiredProdInfo – The RequiredProdInfo component checks all items in the items collection in the OrderForm and deletes any items that have the delete key set to 1. ●

●

The Order Initialization stage initializes the proper values in the OrderGroup object. This stage consists of a single component: RequiredOrderInitCy. First, RequiredOrderInitCy ensures that the order_id key has a value. If it does not, RequiredOrderInitCy generates a unique order ID and assigns it to this key. Next, to ensure order integrity, the component initializes the various total keys by assigning NULL to them. Finally, for each item in the items collection, RequiredOrderInitCy copies the value stored in quantity to the _n_unadjusted key to initialize the undiscounted quantity of the item and initializes the _oadjust_adjustedprice (the total cost of the item) to zero (0). The Order Check stage verifies that the order being presented is valid and has all entries necessary for subsequent processing. This stage consists of one component: RequiredOrderCheck. The RequiredOrderCheck component ensures that the items list of the OrderForm is not empty.

160 Reference Architecture for Commerce

The RecordEvent Pipeline The RecordEvent pipeline contains components that record the occurrence of particular events that occur during the shopping process — such as a user clicking a particular ad or discount. You can use the Commerce Server Pipeline Editor to view the configuration of the RecordEvent pipeline by opening the RecordEvent.pcf file in the Pipelines folder of the site. The RecordEvent pipeline is illustrated in Figure 9.4:

Figure 9.4 RecordEvent Pipeline

The RecordEvent pipeline includes the following stages: ● The pipeline starts with the Load Context stage. Microsoft Commerce Server 2000 includes no components for this stage. This stage is provided for custom extensions or for future enhancements to Commerce Server 2000. ● The Record stage contains components that record the selection made to a database, the server log file, or a history string. This stage consists of the following two components: ● RecordEvent – This component records event delta counts for the selected content items in the Performance dictionary. The values are used to calculate the need of delivery of an item. ● IISAppendToLog – This component appends information about the result of the content selection process in the QueryString key of the IIS log file. This log file can be imported into the Data Warehouse for use with reporting and analysis.

Chapter 9: ConsolidatedRetail.com Functionality 161

Advertising Pipeline Targeted advertising allows a site to display promotional information to users based on products that the user has already selected. The Advertising pipeline is used to generate these targeted advertisements. It is a content selection pipeline that contains components which gather, filter, score, and select advertisements. You can use the Commerce Server Pipeline Editor to view the configuration of the Advertising pipeline by opening the Advertising.pcf file in the Pipelines folder of the site. The Advertising pipeline is illustrated in Figure 9.5:

Figure 9.5 Advertising Pipeline

162 Reference Architecture for Commerce

The Advertising pipeline includes the following stages: ● The pipeline starts with the Load Context stage, which contains components that prepare for the execution of the rest of the pipeline. This stage includes the following components: ● InitCSFPipeline – This component is used at the beginning of the pipeline to initialize the values needed in the rest of the pipeline. The InitCSFPipeline component is responsible for setting up numerous values in the Order and Context dictionaries for efficient access by subsequent components in the pipeline. ● LoadHistory – This component retrieves a history string from a HTTP cookie, CampaignHistory. This component makes the history string easily accessible to other pipeline components by hiding its source. ●

●

●

●

The Filter stage contains a component that filters or trims the content list. This stage consists of a single component: FilterContent. This component is used to apply provided filters to a content list in the pipeline. The filters to apply are retrieved from FilterRequire and FilterExclude dictionaries in the Order dictionary. The list of content is contained in the ContentList object identified by the _content entry in the Order dictionary. The Initial Score stage sets an initial score for each content item. This stage consists of a single component: AdvertisingNeedOfDelivery. This component scores ads so that they are selected often enough to meet business commitments. This component calculates the Need of Delivery (NOD) for ad items in the ContentList object and assigns these as the initial scores for the items. The Scoring stage contains components that adjust the scores of each content item. This stage consists of the following two components: ● HistoryPenalty – This component applies penalties to content items based on how recently they have been selected, as well as on exposure limits the items may have. Penalties are values between zero (0) and one (1), which are multiplied by the current score of an item. This tends to reduce a score and thus reduces the possibility that the item is selected. ● EvalTargetGroups – This component targets particular groups for advertising, by evaluating a list of expressions for each item in a list and adjusting item selection. The Select stage selects one or more content items for return. This stage consists of a single component: SelectWinners. This component chooses items based on their final scores. To communicate the winners, the SelectWinners component builds a new SimpleList object that contains the ContentList object indexes up to the requested number of winning content items.

Chapter 9: ConsolidatedRetail.com Functionality 163 ●

The Record stage contains components that record the selection made to a database, the server log file, or a history string. This stage consists of the following components: ● RecordEvent – This component records event delta counts for the selected content items (the winners) in the Performance dictionary. The values are used to calculate the need of delivery of an item. ● IISAppendToLog – This component appends information about the result of the content selection process in the QueryString key of the IIS log file. This log file can be imported into the Data Warehouse for use with reporting and analysis. ● RecordHistory – The RecordHistory component is responsible for managing the size of the history list and truncates it when necessary. The component removes the oldest entries from the string when it exceeds the maximum length. The property page for the RecordHistory component allows the maximum number of entries in the history to be configured. This component trims the least recent history list entries, as necessary, to assure that this limit is not exceeded. ● SaveHistory – This component is used to save the history string in the HTTP cookie, CampaignHistory.

●

The Format stage contains components that format selected items as HTML or XML for return to the page that ran the pipeline. This stage consists of a single component: FormatTemplate. This component merges data from selected items and their associated templates to form formatted strings.

Discounts Pipeline Discounts are another form of targeted advertising. Discounts allow a site to display promotional information about specific discounted items to users based on products that the user has already selected. The Discounts pipeline is a content selection pipeline that contains components to gather, filter, score, and select discounts. You can use the Commerce Server Pipeline Editor to view the configuration of the Discounts pipeline by opening the Discounts.pcf file in the Pipelines folder of the site. The Discounts pipeline is illustrated in Figure 9.6 on the next page.

164 Reference Architecture for Commerce

Figure 9.6 Discounts Pipeline

The Discounts pipeline includes the following stages: ● The pipeline starts with the Load Context stage, which contains components that prepare for the execution of the rest of the pipeline. This stage contains the following two components: ● InitCSFPipeline – This component is used at the beginning of the pipeline to initialize the values needed in the rest of the pipeline. The InitCSFPipeline component is responsible for setting up numerous values in the Order and Context dictionaries for efficient access by subsequent components in the pipeline.

Chapter 9: ConsolidatedRetail.com Functionality 165 ●

●

●

●

●

LoadHistory – This component retrieves a history string from the HTTP cookie, CampaignHistory. This component makes the history string easily accessible to other pipeline components by hiding its source.

The Filter stage contains components that filter or trim the content list. This stage consists of a single component: FilterContent. This component is used to apply provided filters to a content list in the pipeline. The filters to apply are retrieved from FilterRequire and FilterExclude dictionaries in the Order dictionary. The list of content is contained in the ContentList object identified by the _content entry in the Order dictionary. The Scoring stage contains components that adjust the scores of each content item. This stage contains the following components: ● ScoringDiscounts – This component adjusts the score of discount content items with the goal of promoting discounts most relevant to the current user. The OrderDiscount component applies the discounts whose scores are adjusted by the ScoreDiscounts component. The ScoreDiscounts component saves the scores in the ContentList object held by the CacheManager object. That ContentList object is then used by the OrderDiscount component in PAGBasket pipeline. ● HistoryPenalty – This component applies penalties to discounts based on how recently they have been selected, as well as on exposure limits the items may have. Penalties are values between zero (0) and one (1), which are multiplied by the current score of an item. This tends to reduce a score and thus reduces the possibility that the item is selected. ● EvalTargetGroups – This component targets particular groups for discounts, by evaluating a list of expressions for each item in a list and adjusting item selection. The Select stage selects one or more content items for return. This stage consists of a single component: SelectWinners. This component chooses items based on their final scores. To communicate the winners, the SelectWinners component builds a new SimpleList object that contains the ContentList object indexes up to the requested number of winning content items. The Record stage contains components that record the selection made to a database, the server log file, or a history string. This stage contains the following components: ● RecordHistory – The RecordHistory component is responsible for managing the size of the history list and truncates it when necessary. The component removes the oldest entries from the string when it exceeds the maximum length. The property page for the RecordHistory component allows the maximum number of entries in the history to be configured. This component trims the least recent history list entries, as necessary, to assure that this limit is not exceeded.

166 Reference Architecture for Commerce ●

●

●

●

SaveHistory – This component is used to save the history string in the HTTP cookie, CampaignHistory. RecordEvent – This component records event delta counts for the selected content items (the winners) in the Performance dictionary. The values are used to calculate the need of delivery of an item. ISAppendToLog – This component appends information about the result of the content selection process in the QueryString key of the IIS log file. This log file can be imported into the Data Warehouse for use with reporting and analysis.

The Format stage contains components that format selected items as HTML or XML for return to the page that ran the pipeline. This stage consists of a single component: FormatTemplate. This component merges data from selected items and their associated templates to form formatted strings.

Order Processing When a user decides to check out, the user must perform the following steps: 1. Specify a shipping address for the order (or choose to have different products delivered to different addresses). 2. Choose a shipping method. 3. Provide payment information for the order. 4. Confirm the order details. 5. Complete the order process. The ConsolidatedRetail.com site uses Commerce Server objects and pipeline components to handle these processes.

Specifying a Shipping Address In general, the user specifies a shipping address by using Shipping.pasp. This page contains a form listing all shipping addresses in the user’s profile (and the option to create a new address or edit existing ones). The user simply specifies the address to which he or she wants the items shipped. The page then posts the form back to itself and updates the OrderGroup object that represent the shopping basket contents with the specified address. When the user specifies a shipping address, the code in Shipping.pasp begins by using the GetUserID function in the Common.asp include file to retrieve the current user’s ID. Shipping.pasp then calls the LoadBasket routine in the Basket.asp include file to populate an OrderGroup object, as follows: strUserID = GetUserID Set objMSCSOrderGrp = LoadBasket(strUserID)

Chapter 9: ConsolidatedRetail.com Functionality 167

Next, the code retrieves the supplied address ID from the query string, and updates each item in the shopping basket with the specified address ID: For Each strOrderFormName In objMSCSOrderGrp.Value.OrderForms Set objMSCSOrderForm = objMSCSOrderGrp.Value.OrderForms _ (strOrderFormName) For each colItem in objMSCSOrderForm.Items colItem.value("shipping_address_id") = strAddressID Next Next

Finally, the shipping address for the overall OrderGroup object is set, any unreferenced addresses that had been previously set are removed and the shopping basket is saved. The user is then redirected to ShippingMethod.pasp to specify a shipping method for the order: Call objMSCSOrderGrp.SetShippingAddress(strAddressID) Call objMSCSOrderGrp.SaveAsBasket() Set objMSCSOrderGrp = Nothing Response.Redirect "ShippingMethod.pasp"

However, if this is the customer’s first visit to the Shipping.pasp page, the list of possible addresses must be retrieved from the user’s profile to be displayed in the form. The code in Shipping.pasp does this using an ADO query to the addresses table in the site database, as shown in the following: strUserID = GetUserID() Set cnBizDesk = server.CreateObject(mc_stradodb_connection) Set rsAddress = server.CreateObject(mc_stradodb_recordset) cnBizDesk.Open _ Application("MSCSDictConfig").s_BizDataStoreConnectionString rsAddress.Open "select g_address_id as 'address_id', i_address_type as 'address_type', u_description as 'description', u_address_name as 'address_name', u_address_line1 as 'address_line1', u_address_line2 as 'address_line2', u_city as 'city', u_region_name as 'region_code', u_region_name as 'region_name', u_postal_code as 'postal_code' from addresses where g_id = '" & strUserID & "' and i_address_type=" & mc_lngShippingAddress & "ORDER BY u_address_name", cnBizDesk

If the user has no addresses listed in his or her profile, the user is redirected to the EditAddressBook.pasp page with a Mode parameter. This parameter returns the user to this page after the address is added: If rsAddress.EOF Then 'no address have been entered for the user ID rsAddress.Close Set rsAddress = Nothing cnBizDesk.Close Set cnBizDesk = Nothing Response.Redirect "EditAddressBook.pasp?Mode=" & mc_strPageName End If

168 Reference Architecture for Commerce

If the user profile has one or more addresses, the address information is added to the shopping basket (the last address specified is the default shipping address), and rendered as XML: Call XMLBegTag(mc_strAddresses) Do While Not rsAddress.EOF strAddressID = rsAddress.Fields("address_id").value strDescription = rsAddress.Fields("description").value strAddressName = rsAddress.Fields("address_name").value strAddressLine1 = rsAddress.Fields("address_line1").value strAddressLine2 = rsAddress.Fields("address_line2").value strCity = rsAddress.Fields("city").value strRegionCode = rsAddress.Fields("region_code").value strRegionName = rsAddress.Fields("region_name").value strPostalCode = rsAddress.Fields("postal_code").value blnSaveSuccessful = PutOrderAddress(objMSCSOrderGrp, _ mc_lngShippingAddress, strAddressID, strAddressName, _ strAddressLine1, strAddressLine2, strCity, strRegionName, _ strPostalCode, strDescription) If blnSaveSuccessful Then Call XMLBegTag(mc_strAddress) Call XMLTag(mc_strAddress_ID, strAddressID) Call XMLTag(mc_strDescription, strDescription) Call XMLTag(mc_strAddress_Name, strAddressName) Call XMLTag(mc_strAddress_Line1, strAddressLine1) Call XMLTag(mc_strAddress_Line2, strAddressLine2) Call XMLTag(mc_strCity, strCity) Call XMLTag(mc_strRegion_Code, strRegionName) Call XMLTag(mc_strRegion_Name, strRegionName) Call XMLTag(mc_strPostal_Code, strPostalCode) Call XMLEndTag(mc_strAddress) 'Set the billing address If rsAddress.Fields("address_type").value = 2 Then objMSCSOrderGrp.Value("OrderForms").Value _ ("default").Value("billing_address_id") = strAddressID End If End If rsAddress.MoveNext Loop Call XMLEndTag(mc_strAddresses) End If

The format of the XML produced by this code is shown in the following code: {0243FFF8-E633-4DE4-AA2E-2083E9D5ABB4} Home Address Kim Abercrombie My House My Street

Chapter 9: ConsolidatedRetail.com Functionality 169 Redmond Washington Washington 12345 {B87EDB27-8FBE-4BDA-83BE-ED037A0B7E4C} Work Address Kim Abercrombie Microsoft Corp. 1 Microsoft Way Redmond Washington Washington 54321

Specifying a Shipping Method After the user specifies an address for the order, he or she must choose a shipping method. Commerce Server 2000 supports the configuration of multiple shipping methods, each with different price bands depending on the weight, item quantity, or total cost of the order. (For more information about defining shipping methods, refer to the Commerce Server 2000 documentation.) The ShippingMethod.pasp page allows the user to select one of the shipping methods defined in the site database. The page contains a form listing each shipping method as an option. After the user chooses an option, the choice is posted back to the page for processing. The shipping methods are retrieved for display from the application-level ShippingMethodsXML variable. The list of available shipping methods is retrieved from the application-level ShippingMethodsXML variable, which is initialized using the GetShippingMethodsXML function in Common.asp, as shown in the following code: Function GetShippingMethodsXML(MSCSDictConfig) Dim MSCSShipMgr Dim rsShippingMethods Dim strXMLStream strXMLStream = "" Set MSCSShipMgr = Server.CreateObject("Commerce.ShippingMethodManager")_ MSCSShipMgr.Initialize(MSCSDictConfig.s_TransactionConfigConnectionString) Set rsShippingMethods = MSCSShipMgr.GetInstalledMethodList("",_ "shipping_method_name", Array("shipping_method_id", "shipping_method_name"))

170 Reference Architecture for Commerce If Not (rsShippingMethods.EOF And rsShippingMethods.BOF) Then Do While Not rsShippingMethods.EOF strXMLStream = strXMLStream & vbCrLf & "" strXMLStream = strXMLStream & vbCrLf & "" & _ rsShippingMethods.Fields("shipping_method_id").Value & _ "" strXMLStream = strXMLStream & vbCrLf & _ "" & _ rsShippingMethods.Fields("shipping_method_name").Value & _ "" strXMLStream = strXMLStream & vbCrLf & "" rsShippingMethods.MoveNext Loop End If Set MSCSShipMgr = Nothing GetShippingMethodsXML = strXMLStream End Function

The ShippingMethod.pasp page includes the list of available shipping methods in the following XML format: {00000000-0000-0000-0000-003688009465} Express {00000000-0000-0000-0000-001140002642} Standard

After a user chooses a shipping method, its ID and name must be stored in the OrderGroup object. Because only the ID is passed from the form, the name must be retrieved from the database by using the Commerce Server ShippingMethodManager object. This object provides a GetInstalledMethodList method that can be used to retrieve methods that match a specified criterion as a recordset. The code to retrieve the relevant method name for the supplied ID is similar to the following: Set objMSCSShpMthMgr = _ Server.CreateObject(mc_strShippingMethodManager) objMSCSShpMthMgr.Initialize(Application("MSCSDictConfig"). _ s_BizDataStoreConnectionString) set rsShpMthName = objMSCSShpMthMgr.GetInstalledMethodList _ ("shipping_method_id = '" & strShippingMethodID & "'", "", _ Array(mc_strshipping_method_name))

Chapter 9: ConsolidatedRetail.com Functionality 171 set objMSCSShpMthMgr = nothing If Not (rsShpMthName.EOF and rsShpMthName.BOF) then strShippingMethodName = rsShpMthName.Fields(0).Value End If rsShpMthName.Close Set rsShpMthName = Nothing

After the shipping method name is retrieved, the products in the shopping cart are updated with the shipping method data and the user is redirected to Payment.pasp to specify the payment information: For Each strOrderFormName In objMSCSOrderGroup.Value.OrderForms Set objMSCSOrderForm = objMSCSOrderGroup.Value. _ OrderForms(strOrderFormName) For each colItem in objMSCSOrderForm.Items colItem.value(mc_strshipping_method_id) = strShippingMethodID colItem.value(mc_strshipping_method_name) = strShippingMethodName Next Next Call objMSCSOrderGroup.SaveAsBasket() Set objMSCSOrderGroup = Nothing Response.Redirect "Payment.pasp"

Specifying Multiple Shipping Addresses and Methods The user can specify a different shipping address and method for each item in the shopping cart. The code to support this functionality is in the MultiShipping.pasp page. Note: If a user chooses to specify multiple addresses for an order, the Reference Architecture application requires that the user specify an address for each individual item in the order. This approach works for small orders, but users who place large orders will not find this acceptable. Users who include large amounts of a single item or a great number of items in an order should be advised that sending multiple orders, each to a single address, is a better option.

When the user requests a shipping method and address for each item, the form is posted back to MultiShipping.pasp, and the OrderGroup object representing the shopping basket is updated. The following code is used to update the shipping method and address data for each item: ' populate each item with shipping method id objMSCSOrderGroup("split_shipment") = True For Each strOrderFormName In objMSCSOrderGroup.Value.OrderForms Set objMSCSOrderForm = objMSCSOrderGroup.Value.OrderForms(strOrderFormName) For Each colItem In objMSCSOrderForm.Items intQuantity = colItem.value("Quantity") strOriginalUID = colItem.value("lineitem_uid") colItem.value("Quantity") = 1

172 Reference Architecture for Commerce If intQuantity > 1 Then For intIndex = 1 To (intQuantity - 1) 'create the product dictionary Set objMSCSProductDictionary = Server.CreateObject(mc_strDictionary) objMSCSProductDictionary.lineitem_uid = GenerateGUID() objMSCSProductDictionary.product_id = colItem.value("product_id") objMSCSProductDictionary.orig_lineitem_uid = strOriginalUID objMSCSProductDictionary.product_catalog = colItem.value("product_catalog") objMSCSProductDictionary.Quantity = 1 If Not IsNull(colItem.value("product_variant_id")) Then objMSCSProductDictionary.product_variant_id =_ colItem.value("product_variant_id") objMSCSProductDictionary.product_variant_id_name =_ colItem.value("product_variant_id_name") objMSCSProductDictionary.product_variant_name = colItem.value("product_variant_name") objMSCSProductDictionary.product_variant_value = colItem.value("product_variant_value") End If If Not IsNull(colItem.value("product_category")) Then objMSCSProductDictionary.product_category = colItem.value("product_category") End If Call objMSCSOrderGroup.AddItem(objMSCSProductDictionary) Set objMSCSProductDictionary = Nothing Next Else 'store the original lineitem_uid for reconstituting the basket If IsNull(colItem("orig_lineitem_uid")) Then colItem("orig_lineitem_uid") = strOriginalUID End If End If 'populate the original item If IsNull(colItem("orig_lineitem_uid")) Then colItem("orig_lineitem_uid") = strOriginalUID End If Next Next Call objMSCSOrderGroup.PurgeUnreferencedAddresses() ' routine to retreive common xml structures required for every page Call PageStart(mc_strPageName) Call XMLTag("pagemode", mc_strPageName) ' display advertising information in right hand frame 'XMLEmptyTag(mc_strAdvertisingMenu) strUserID = GetUserID() Set cnBizDesk = server.CreateObject(mc_stradodb_connection)

Chapter 9: ConsolidatedRetail.com Functionality 173 Set rsAddress = server.CreateObject(mc_stradodb_recordset) cnBizDesk.Open Application("MSCSDictConfig").s_BizDataStoreConnectionString rsAddress.Open "select g_address_id as 'address_id', i_address_type as_ 'address_type', u_address_name as 'address_name', u_Description as_ 'description', u_address_line1 as 'address_line1', u_address_line2 as 'address_line2', u_city as 'city', u_region_name as 'region_code', u_region_name as 'region_name', u_postal_code as 'postal_code' from addresses where g_id = '" & strUserID & "' and i_address_type = " & mc_lngShippingAddress & " ORDER BY u_address_name", cnBizDesk If Not (rsAddress.EOF And rsAddress.BOF) Then Call XMLBegTag(mc_strAddresses) Do While Not rsAddress.EOF strAddressID = rsAddress.Fields("address_id").value strAddressName = rsAddress.Fields("address_name").value strAddressLine1 = rsAddress.Fields("address_line1").value strAddressLine2 = rsAddress.Fields("address_line2").value strCity = rsAddress.Fields("city").value strRegionCode = rsAddress.Fields("region_code").value strRegionName = rsAddress.Fields("region_name").value strPostalCode = rsAddress.Fields("postal_code").value strDescription = rsAddress.Fields("description").value blnSaveSuccessful = PutOrderAddress(objMSCSOrderGroup, mc_lngShippingAddress, strAddressID, strAddressName, strAddressLine1, strAddressLine2, strCity, strRegionName, strPostalCode, strDescription) If blnSaveSuccessful Then Call XMLBegTag(mc_strAddress) Call XMLTag(mc_strAddress_ID, strAddressID) Call XMLTag(mc_strAddress_Name, strAddressName) Call XMLTag(mc_strAddress_Line1, strAddressLine1) Call XMLTag(mc_strAddress_Line2, strAddressLine2) Call XMLTag(mc_strCity, strCity) Call XMLTag(mc_strRegion_Code, strRegionName) Call XMLTag(mc_strRegion_Name, strRegionName) Call XMLTag(mc_strPostal_Code, strPostalCode) Call XMLEndTag(mc_strAddress) End If rsAddress.MoveNext Loop Call XMLEndTag(mc_strAddresses) End If

Specifying Payment Information As part of the checkout process, the user must provide payment details for the order. The Payment.pasp page handles this portion of the order processing sequence.

174 Reference Architecture for Commerce

Note: In this sample application, the payment details are passed in plain text using HTTP. In a production site, HTTPS should be used to encrypt the payment data.

The Payment.pasp page contains a form that allows a user to specify credit card and billing address details from his or her profile. When a user enters credit card information, he or she will be asked to specify a Listed As value for each credit card added to the user profile. The user cannot use the same Listed As value for multiple cards; the Listed As value must be unique per card, per user. The Reference Architecture for Commerce performs a system-wide check to ensure that each credit card number is unique and checks to ensure that the combination of User Name/Listed As values are unique. Billing addresses also require Listed As values; however, these are not unique because a billing address can also be a shipping address. The AddressBook page displays all shipping addresses that the user has entered. If any of these addresses has the same Listed As value as the billing address, then the message, “Also the billing address” is displayed below the Listed As designation. Note that the message appears if the Listed As values match, even if the underlying address details are different. A user can modify a billing address so that its Listed As value is the same as an existing shipping address. Similarly, a user can modify a shipping address so that its Listed As value matches the billing address. However, any changes made to one address record are not reflected in the other. Developers who use the Reference Architecture code as the basis for a production retail Web site may want to consider changing this functionality to ensure that a shipping address and billing address with the same Listed As value remain synchronized. If the user has no billing address defined, he or she is redirected to the EditAddressBook.pasp page to add it. The EditAddressBook page displays an existing address or shows a blank form for entering a new address. If the new address form is displayed and no billing address exists, the Make this my billing address also check box is selected by default. If an existing shipping address has the same Listed As value as that of the billing address, the contents of the selected shipping address is displayed and the Make this my billing address also check box is selected by default. If a user has already designated an address as a billing address, the check box is cleared by default. If the user has other existing shipping addresses, those addresses are also displayed with the check box cleared by default. The Payment.pasp page simply reads the payment details from the form, and then writes them to the OrderGroup object that represents the user’s shopping basket.

Chapter 9: ConsolidatedRetail.com Functionality 175 strUserID = GetUserID If Not IsNull(GetUserID) Then Set objMSCSOrderGroup = LoadBasket(strUserID) If isnull(objMSCSOrderGroup("split_shipment")) then response.redirect "shipping.pasp" End if ' Check to see if the basket has items If objMSCSOrderGroup.Value("total_lineitems") > 0 Then blnBasketIsEmpty = False Else Response.Redirect "basket.pasp" End If ' If there is no billing address in the OrderForm, then ' check if the user has specified a default address. If so, ' insert that into the OrderForm. If not, redirect to EditAddressBook.pasp ' so that the user can enter one. If IsNull(strBillAddress) or (Not IsNull(strBillAddress) And_ Len(strBillAddress) = 0 ) then strBillAddress = GetUserBillingAddressId() End if If IsNull(strBillAddress) then Response.Redirect "EditAddressBook.Pasp?Mode=" & mc_strPageName & "&txtAddressType=billing" End If ' If we are coming back here from the EditShippingAddress.pasp page, ' we need to populate the billing address id that was just entered If Not IsNull(strBillAddress) Then objMSCSOrderGroup.Value("OrderForms").Value("default").Value("billing_address_id") = strBillAddress Call SetBillingAddressToOG(objMSCSOrderGroup) End If ' determine whether or not there is a billing address Call XMLTag("billingaddressstatus",_ objMSCSOrderGroup.Value("OrderForms").Value("default").Value_ ("billing_address_id")) End If ' Retrieve the credit cards that are stored for the user Call XMLBegTag(mc_strCreditCards) intCardTotal = GetUserCreditCardsXMLEx() Call XMLEndTag(mc_strCreditCards) ' If there are no credit cards, return to add one If intCardTotal < 1 Then Response.Redirect "EditCreditCard.Pasp?Mode=" & mc_strPageName & "&txtbilladdressid=" & strBillAddress End If For Each strOrderFormName In objMSCSOrderGroup.Value.OrderForms Set objMSCSOrderForm = objMSCSOrderGroup.Value.OrderForms(strOrderFormName) For Each colItem In objMSCSOrderForm.Items if Isnull(colItem.value(mc_strshipping_method_id) )then Response.Redirect "shipping.pasp" End If Next Next

176 Reference Architecture for Commerce Set objMSCSPipelines = Application("MSCSPipelines") intErrorLevel = RunMtsPipeline(objMSCSPipelines.PAGBasket, objMSCSPipelines.LogFolder & strUserID & ".log", objMSCSOrderGroup) Call AddPipeErrors(objMSCSOrderForm, intErrorLevel) intErrorLevel = RunMtsPipeline(objMSCSPipelines.PAGTotal, objMSCSPipelines.LogFolder & strUserID & ".log", objMSCSOrderGroup) Call AddPipeErrors(objMSCSOrderForm, intErrorLevel) Set objMSCSPipelines = Nothing ' Grab the default orderform Set objMSCSOrderForm = objMSCSOrderGroup.Value("OrderForms").Value("default") Call objMSCSOrderGroup.SaveAsBasket() Set objMSCSOrderGroup = Nothing Set objXMLTransforms = Server.CreateObject(mc_strXMLTransforms) Set objXMLSchema = GetTransformSchema() Set objXMLOrderForm = objXMLTransforms.GenerateXMLForDictionaryUsingSchema(objMSCSOrderForm, objXMLSchema) Set objXMLSchema = Nothing Set objMSCSOrderForm = Nothing Set objXMLTransforms = Nothing If not isEmpty(objXMLOrderForm) Then Response.Write objXMLOrderForm.xml Else Call AddException(m_varrExceptions, "1222", "Error converting orderform to XML.", "basket.asp") End if Set objXMLOrderForm = Nothing

After the payment information is complete, the user is redirected to the OrderSummary.pasp page.

Confirming the Order Details The user is given a chance to confirm or change the order details before the final part of the ordering process is completed. The order details are displayed on the OrderSummary.pasp page. The code uses two pipelines to retrieve the order details for display. First, the PAGBasket pipeline retrieves the shopping basket contents. Then, the PAGTotal pipeline calculates shipping costs and subtotals. For a description of the PAGBasket pipeline, refer to the “Viewing the Shopping Cart or Save for Later Basket” section earlier in this chapter. The PAGTotal pipeline is described in the following section.

The PAGTotal Pipeline The PAGTotal pipeline, which you can view by opening Total.pcf in the Commerce Server Pipeline Editor, is illustrated in Figure 9.7.

Chapter 9: ConsolidatedRetail.com Functionality 177

Figure 9.7 PAGTotal Pipeline

The PAGTotal pipeline includes the following stages: ● The Shipment Splitter stage prepares a shipping dictionary. This stage contains two components: ● Commerce.Splitter – The splitter component generates a dictionary of shipments (shipments) that is placed on the OrderForm. This dictionary contains the individual shipments that are created based upon the shipping_address_id and shipping_method_id values in the order. ● Commerce.ShippingMethodRouter – The ShippingMethodRouter component reads the ShippingManagerCache by using the CacheManager object to map shipping methods to particular shipping components. The component steps through the list of shipping methods and, if there are shipments using a given method, it collects the dictionaries for those shipments, passes the shipments to the shipping component, and then runs the relevant shipping component. The individual shipping components calculate the total shipping charges for the shipments passed to it. After all of the shipments are processed, the total of all of the shipping charges is calculated.

178 Reference Architecture for Commerce ●

●

The Shipping stage applies shipping discounts to an order. There is one component in this stage: ShippingDiscountAdjust. This component examines the _shipping_discount_type and adjusts the total shipping for the order. If the discount is blank, the component does nothing. If the discount type is 1 or 2, the component applies the discount. If the discount is none of these, the component returns an error. The _shipping_discount_type value is determined using the OrderDiscount object. The Handling stage sets the _handling_total on the order form. This stage consists of the following two components: ● DefaultHandlingCy – This component assigns zero (0) to the total handling cost in the Order dictionary. It is a placeholder component that would be replaced by another handling component in actual use. ● RequiredHandlingCy – The RequiredHandlingCy component verifies that the order._handling_total key is present.

●

The Tax stage sets the _tax_total and _tax_included values on the order form. This stage consists of the following two components: ● SampleRegionalTax – This component sets the tax fields (_cy_tax_total, shipments._cy_tax_total and _cy_tax_included) to an appropriate tax value based on the tax information in the RegionalTaxCache. ● RequiredTaxCy – This component verifies that the _cy_tax_total and _cy_tax_included keys exist in the order form. If either value does not exist, RequiredTaxCy uses the pur_badtax constant to retrieve error message text from the MessageManager, and stores this message in the _Purchase_Errors collection of the OrderForm.

●

The Order Total stage sets the _total_total value on the order form. This stage consists of the following three components: ● DefaultTotalCy – This component verifies that all four totals on the order are set. If all four values exist, they are added together and assigned to the complete total in the Order dictionary. If any value is missing, the component stops and returns an error. ● PersistUtility – This is a custom component used to copy values within the OrderForm. This is mainly used to make values persistent. Otherwise, OrderForm values with names that begin with an underscore (_) do not persist. The source code for the PersistUtility component (written in Visual C++) is provided with the Reference Architecture for Commerce. ● RequiredTotalCy – This component goes through the keys and values in the _Verify_With dictionary and makes sure that each key exists in the order form and has the same value.

Chapter 9: ConsolidatedRetail.com Functionality 179 ●

The last stage, Fixes, contains a single component: Truncate Description. This component, written in VBScript, provides a workaround for a known issue in Commerce Server 2000 where any field longer than 255 characters is assumed to be of type Text.

Obtaining the User’s E-mail Address After the pipelines execute, the code in OrderSummary.pasp retrieves a ProfileObject for the current user, and extracts the e-mail address to be used for the order confirmation message. This is then added to the default OrderForm for the OrderGroup object, and the OrderGroup object is saved: 'Grab the default orderform Set objMSCSOrderForm = objMSCSOrderGroup.Value("OrderForms").Value("default") 'Set the email address for the order confirmation email. Set objMSCSProfileObject = GetUserObject() objMSCSOrderForm.user_email_address = objMSCSProfileObject_ (mc_strGeneralInfo).Value(mc_strEmail_Address) Set objMSCSProfileObject = Nothing Call objMSCSOrderGroup.SaveAsBasket()

The code then verifies the total amount and displays an error if the order total and the total in the OrderSummary and ThankYou page don’t match: 'Add new hidden HTML field to verify the total amt Call XMLTag("verify_with_total" ,_ objMSCSOrderGroup.Value("saved_cy_total_total")) Set objMSCSOrderGroup = Nothing 'If this request is from the ThankYou page '(i.e. if there was an order total mismatch), 'display the appropriate error Dim sErr : sErr = Application("MSCSAppFrameWork").RequestString_ ("err" , "", , , true, true, 0, Null) if sErr = C_BAD_VERIFY_ERRCODE then Call AddException( m_varrExceptions, "1222",_ Application("MSCSMessageManager").GetMessage("pur_badverify",_ Application("MSCSMessageManager").DefaultLanguage) , mc_strPageName) End If

For security purposes, the code then truncates the credit card information before displaying the summary or sending the confirmation and ensures that the truncated credit card number is not persisted: 'Truncate credit card number before display. 'Ensure that the orderform is not saved again, so that the 'truncated CC number is not persisted. Dim ccNumber : ccNumber = objMSCSOrderForm.value("cc_number") objMSCSOrderForm.value("cc_number") = TruncateCC(ccNumber)

180 Reference Architecture for Commerce

The contents of the OrderGroup object are converted to XML, using a Commerce Server DictionaryXMLTransforms object, and written to the Response object as shown in the following code: Set objXMLTransforms = Server.CreateObject(mc_strXMLTransforms) Set objXMLSchema = GetTransformSchema() Set objXMLOrderForm =_ objXMLTransforms.GenerateXMLForDictionaryUsingSchema_ (objMSCSOrderForm, objXMLSchema) Set objXMLSchema = Nothing Set objMSCSOrderForm = Nothing Set objXMLTransforms = Nothing If not isEmpty(objXMLOrderForm) Then Response.Write objXMLOrderForm.xml Else Call AddException(m_varrExceptions, "1222", _ "Error converting orderform to XML.", "basket.asp") End if Set objXMLOrderForm = Nothing

Finally, the shipping methods are retrieved and displayed: Call XMLBegTag("shipping_methods") ' retrieve the shipping methods Response.Write ( CachedFragmentLookup( STATIC_SECTIONS_CACHE ,_ SHIPPING_METHODS_XML ) ) Call XMLEndTag("shipping_methods")

This produces the following XML representation of the OrderGroup object:

Completing the Order Process After the user confirms the order details, the order process can be completed. The code to handle the final part of the order process is implemented in the Thankyou.pasp page. The Thankyou.pasp page begins by running the PAGBasket and PAGTotal pipelines as described previously. Then, the PAGFinal pipeline is executed to complete the order.

The PAGFinal Pipeline You can view the PAGFinal pipeline by opening Final.pcf in the Commerce Server Pipeline Editor. The PAGFinal pipeline is illustrated in Figure 9.8:

Figure 9.8 PAGFinal Pipeline

182 Reference Architecture for Commerce

The only stage in the ordering process is called Order Transfer. This stage contains one component: QueueEmail Class. This is a custom pipeline component that is used to send order confirmation in e-mail to the user_e-mail_address field in the default OrderForm.

Sending an Order Confirmation E-mail QueueEmail Class is a pipeline component (COM object) that implements the IPipelineComponent interface. The QueueEmail Class component takes information from the OrderForm, converts it to XML, and then sends it as an e-mail message by using the custom QueuedEMailer.CMailer queued component. By calling a queued component to send the e-mail message, the process is made asynchronous, thus preventing any latency caused by the e-mail process from causing a negative effect on response time for the user checking out. A custom property page for the QueueEmail Class component is used to configure the component in the Pipeline Editor. This allows you to set the appropriate message queue, moniker, and ProgID used to instantiate the queued component that will actually be used to send the e-mail, as illustrated in Figure 9.9:

Figure 9.9 QueueEmail Class Custom Property Page

QueuedEMailer.CMailer The process of actually sending the e-mail message is handled by the QueuedEMailer.Cmailer queued component. This component is installed in a COM+ application that has been marked as queued. In addition, the _CMailer Interface is also marked as queued, allowing methods on that interface to be called asynchronously through a message queue. The _CMailer interface contains one method; SendMail, which is defined using the following method signature:

Chapter 9: ConsolidatedRetail.com Functionality 183 HRESULT SendMail( [in] BSTR strXMLOrderForm, [in] VARIANT_BOOL blnUseHTMLMail);

Notice that both parameters are marked as [in], because queued components do not support [out] or [retval] parameters. The strXMLOrderForm parameter is used to pass the XML representation of the order form to the component. The blnUseHTMLMail parameter is a Boolean value that is used to determine if the e-mail message should be sent in HTML format or plain text. The QueuedEMailer.CMailer component is also configured to support object construction. This means that the component implements the IobjectConstruct interface, which contains a method named Construct that is called by COM+ when the object is instantiated. A constructor string is passed to the Construct method containing configuration information that can be used by the object. The constructor string passed to QueuedEMailer.CMailer is in the following XML format: [email protected] Order Confirmation C:\Inetpub\b2cref\xml\emailtext.xsl C:\Inetpub\b2cref\xml\emailhtml.xsl False

This constructor is configured using the Component Services Microsoft Management Console (MMC) snap-in as illustrated in Figure 9.10 on the next page. The QueuedEMailer.CMailer object uses the MSXML3 and CDOSYS objects. Loading of the XML and XSL is accomplished by the XMLDomDocument, which uses the MSXML3 object. The actual sending of the e-mail message is accomplished by the IMessage object (CDO-collaboration data objects), which uses the CDOSYS object. The Collaboration Data Objects (CDO) for Microsoft Windows 2000 (Cdosys.dll), which implements the 2.0 version of the CDO API specification, is a COM component designed to simplify writing programs that create or manipulate Internet messages.

184 Reference Architecture for Commerce

Figure 9.10 Component Services MMC Snap-in

Conclusion At this point, you should understand the basic functionality and development decisions behind the ConsolidatedRetail.com application. The code comments provide additional detail and information. The next chapter provides an overview of the debugging and testing processes and best practices, with specific references to the actual tests performed on the Reference Architecture application.

10 Debugging and Testing As with any application, it is the responsibility of the developer to ensure that an e-commerce application delivers both the correct business functionality and the required level of performance and scalability. To make sure that the application meets its goals, it must be debugged thoroughly and performance tested. The first section of this chapter describes procedures for debugging the ConsolidatedRetail.com site as well as for viewing and debugging the Extensible Markup Language (XML) output from the pre-processed Active Server Pages (PASP) scripts. The chapter then goes on to describe types and levels of testing, the functional testing process, performance testing, and general guidance for evaluating the test results.

Debugging the Site Debugging a Web site brings with it several challenges, particularly when serverside logic such as Active Server Pages (ASP) scripting is used. The preferred development environment for building and debugging Web-based applications on computers running Windows is Visual Studio, which includes Visual InterDev, a development suite for Web sites. You can use this environment to debug the Reference Architecture application by adding the FrontPage Server Extensions to the Web site and creating a new Visual InterDev project based on the site. For more information about debugging with Visual InterDev, refer to the Visual InterDev documentation in the MSDN developer program library.

186 Reference Architecture for Commerce

Debugging XML Output from PASP Scripts Another challenging aspect of debugging the ConsolidatedRetail.com site is viewing the XML produced by the PASP scripts. The response stream from these pages is intercepted by the Extensible Stylesheet Language (XSL) Internet Server Application Programming Interface (ISAPI) filter and rendered using the specified style sheet. However, there will be occasions when you should check the XML produced by the script without applying a style sheet. The easiest way to view the XML output is to make an .asp copy of each .pasp file in the site, and access the .asp files using Microsoft Internet Explorer. Because the .asp versions of the files will not be intercepted by the XSL ISAPI filter, the XML response will be returned to the browser and can be seen by viewing the source of the resulting page. You can access many of the scripts simply by specifying the URL address of the file, while for others you must pass parameters in a query string appended to the URL. The following list describes how you can view the XML results of each of the PASP files in the site. Note: The XML output for the PASP pages provided in the ConsolidatedRetail.com site is reproduced in Appendix A. XML output can vary slightly depending upon input in user data fields and whether or not Microsoft Passport authentication is used. ●

●

●

●

Acct.pasp – Save the page as Acct.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected when you try to view Acct.asp). You can then use Internet Explorer to access Acct.asp by specifying a URL address with no parameters (in the form http://servername:81/ Acct.asp). To view the XML, click Source on the View menu. AddressBook.pasp – Save this page as AddressBook.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected when you try to view AddressBook.asp). You can then use Internet Explorer to access AddressBook.asp by specifying a URL address with no parameters (in the form http://servername:81/AddressBook.asp). To view the XML, click Source on the View menu. For more meaningful results, use the site to add at least one address to your address book first. AddtoList.pasp – Save this page as AddtoList.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected when you try to view the page). You can then use Internet Explorer to access AddtoList.asp by specifying a URL address with no parameters (in the form http://servername:81/ AddtoList.asp). To view the XML, click Source on the View menu. For more meaningful results, use the site to add items to a shopping list first. AddtoListResp.pasp – Save this page as AddtoListResp.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected when you try to view the page). You can then use Internet Explorer to access

Chapter 10: Debugging and Testing 187

●

●

●

●

●

AddtoListResp.asp by specifying a URL address with no parameters (in the form http://servername:81/AddtoListResp.asp). To view the XML, click Source on the View menu. For more meaningful results, use the site to add items to a shopping list first. Basket.pasp – Save this page as Basket.asp. You can then use Internet Explorer to access Basket.asp by specifying a URL address with no parameters (in the form http://servername:81/Basket.asp). To view the XML, click Source on the View menu. For more meaningful results, use the site to add a few items to your shopping cart first. Category.pasp – Save this page as Category.asp. You can then use Internet Explorer to access Category.asp by specifying a URL address with values for the following parameters: ● txtCatalog – The name of the catalog you want to browse. ● txtCategory (optional) – The name of a specific category in the specified catalog). For example, you could view the XML representation of the Books catalog by specifying the following URL http://servername:81/ Category.asp?txtCatalog=Books To view the Games category in the Books catalog, you would use the following URL http://localhost/Category.asp?txtCatalog=Books&txtCategory=Games When the page is returned, click Source on the View menu to see the XML. Changepasswd.pasp – Save this page as Changepasswd.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected when you try to view Changepasswd.asp). You can then use Internet Explorer to access Changepasswd.asp by specifying a URL address with no parameters (in the form http://servername:81/Changepasswd.asp). To view the XML, click Source on the View menu. CreditCards.pasp – Save this page as CreditCards.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected when you try to view the page). You can then use Internet Explorer to access CreditCards.asp by specifying a URL address with no parameters (in the form http:// servername:81/CreditCards.asp). To view the XML, click Source on the View menu. EditAddressBook.pasp. Save this page as EditAddressBook.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will not be able to view any address information). The URL for this page can include values for the following parameters: ● txtAddressType – Address type, such as billing or shipping. If no value is provided, then the shipping address is used. ● txtAddressID – Globally unique identifier (GUID) for the address. If a value is specified, then that address is returned.

188 Reference Architecture for Commerce

●

●

●

●

●

For example, to view the XML produced when a user wants to add a new shipping address, use Internet Explorer to navigate to the URL http://servername:81/ EditAddressBook.asp To view the XML produced when a user wants to add a new billing address, use Internet Explorer to navigate to the URL http://servername:81/ EditAddressBook.asp?txtAddressType=Billing To view the XML produced when a user wants to edit a specific address, use Internet Explorer to navigate to the URL http://servername:81/ EditAddressBook.asp?txtAddressID=AddressGUID After you retrieve the page, click Source on the View menu to see the XML. EditCreditCard.pasp – Save this page as EditCreditCard.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected when you try to view the page). You can then use Internet Explorer to access EditCreditCard.asp by specifying a URL address with no parameters (in the form http://servername:81/EditCreditCard.asp). To view the XML, click Source on the View menu. ForgotPasswd.pasp – Save this page as ForgotPasswd.asp, and then navigate to the ConsolidatedRetail.com site. You can then use Internet Explorer to access ForgotPasswd.asp by specifying a URL address with no parameters (in the form http://servername:81/ForgotPasswd.asp). To view the XML, click Source on the View menu. Index.pasp – Save this page as Index.asp. You can then use Internet Explorer to access Index.asp by specifying a URL address with no parameters (in the form http://servername:81/Index.asp). To view the XML, click Source on the View menu. ListBase.pasp – Save this page as ListBase.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will not be able to view the information). The URL for this page can include values for the following parameters: ● ListPage – List type, such as shopping lists (lists) or save for later (sfl). ● ListName – User-specified name for the shopping list. For example, to view the XML for a shopping list called “MyClass,” use Internet Explorer to navigate to the URL http://servername:81/ listbase.asp?ListPage=lists&ListName=MyClass To view the XML, click Source on the View menu. For more meaningful results, use the site to create a shopping list first. ListSearch.pasp – Save this page as ListSearch.asp. You can then use Internet Explorer to access ListSearch.asp by specifying a URL address with no parameters (in the form http://servername:81/ListSearch.asp). You will see the blank search form.

Chapter 10: Debugging and Testing 189

When the form is completed, the URL for this page can include values for the following parameters: ● txtLogon – Logon name of the user who created the public list. ● txtListName – User-specified name for the shopping list. ● txtEmailAddress – E-mail address of the user who created the shopping list. ● txtSearch – Verifies that the search form is completed. This must return the value True or an error message is displayed asking the user to enter complete data.

●

●

●

●

For example, the URL for a shopping list called “Kim” would be similar to the following: http://servername:81/ListSearch.asp?txtLogon=UserName &txtListName=Kim&txtEmailAddress=EmailName &txtSearch=True To view the XML, click Source on the View menu. For more meaningful results, use the site to create a public shopping list first, and then search for that list. Login.pasp – Save this page as Login.asp. Close any current sessions with the ConsolidatedRetail.com site (or you will be redirected to Acct.pasp when you try to access Login.asp). You can then use Internet Explorer to access Login.asp by specifying a URL address with no parameters (in the form http://servername:81/ Login.asp). To view the XML, click Source on the View menu. MultiShipping.pasp – Save this page as MultiShipping.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected to Login.pasp when you try to view MultiShipping.asp). Then add at least one item to your shopping cart (or you will be redirected to Basket.pasp when you try to access MultiShipping.asp). You can then use Internet Explorer to access MultiShipping.asp by specifying a URL address with no parameters (in the form http://servername:81/MultiShipping.asp). To view the XML, click Source on the View menu. OrderHistory.pasp – Save this page as OrderHistory.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected to the Logon page when you try to view OrderHistory.asp). Place an order. You can then use Internet Explorer to access OrderHistory.asp by specifying a URL address with no parameters (in the form http://servername:81/OrderHistory.asp). To view the XML, click Source on the View menu. OrderHistoryDetail.pasp – Save this page as OrderHistoryDetail.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected to the Logon page when you try to view OrderHistoryDetail.asp). Place at least one order, and then you can view OrderHistoryDetail.asp using Internet Explorer by specifying a URL address with a single parameter, order, which should be the GUID identifying an existing order (or an error will occur). The URL to

190 Reference Architecture for Commerce

●

●

●

●

access this page is similar to the following: http://servername:81/ OrderHistoryDetail.asp?order= {0FA626B0-852E-4707-93D5-A00619C6A35B} After you retrieve the page, click Source on the View menu to see the XML. OrderSummary.pasp – Save this page as OrderSummary.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected to the Logon page when you try to view OrderSummary.asp). Place an order and confirm the shipping address, shipping method, and payment information. The Order Confirmation page should appear. Do not click submit. You can then use Internet Explorer to access OrderSummary.asp by specifying a URL address with no parameters (in the form http://servername:81/OrderSummary.asp). Click Source on the View menu to see the XML. Payment.pasp – Save this page as Payment.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected to the Logon page when you try to view Payment.asp). Add an item to your shopping cart (or you will be redirected to Basket.pasp when you try to view Payment.asp). Click the Shopping Cart icon, and the click the check out button. On the Shipping page, click Ship to this Address. On the shipping method selection page (ShippingMethod.pasp), select a shipping method and click continue. Enter credit card information, and then click submit. You can then use Internet Explorer to access Payment.asp by specifying a URL address with no parameters (in the form http://servername:81/Payment.asp). Click Source on the View menu to see the XML. Product.pasp – Save this page as Product.asp. You can then use Internet Explorer to access Product.asp by specifying a URL address with values for the following parameters: ● txtCatalog – The name of the catalog you want to browse. ● txtProductID – The ProductID for the product you want to view. ● txtVariantID (optional) – The variant ID for the product. For example, you could view the XML representation of the book named Code by specifying the following URL http://servername:81/ Product.asp?txtCatalog=Books&txtProductID=Code Click Source on the View menu to see the XML. Registration.pasp – Save this page as Registration.asp. You can then use Internet Explorer to access Registration.asp by specifying a URL address with no parameters (in the form http://servername:81/Registration.asp). To view the XML, click Source on the View menu.

Chapter 10: Debugging and Testing 191 ●

●

●

●

SearchResults.pasp – Save this page as SearchResults.asp. You can then use Internet Explorer to access SearchResults.asp by specifying a URL address with values for the following parameters: ● txtSearchPhrase – The phrase you are searching for. ● txtCatalog – The name of the catalog you want to search. ● txtSearchRowsToReturn (optional) – The number of results you want to return to the user interface. ● txtSearchStartPos (optional) – The row number you want to start the search from. For example, you could search for the word Age in the Books catalog by specifying the following URL http://servername:81/ SearchResults.asp?txtSearchPhrase=age&txtCatalog=Books Shipping.pasp – Save this page as Shipping.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected to Login.pasp when you try to view Shipping.asp). Add an item to the shopping cart, and then click the Shopping Cart icon. You can then use Internet Explorer to access Shipping.asp by specifying a URL address with no parameters (in the form http://servername/Shipping.asp). To view the XML, click Source on the View menu. ShippingMethod.pasp – Save this page as ShippingMethod.asp, and then navigate to the ConsolidatedRetail.com site and log on (or you will be redirected to Login.pasp when you try to view ShippingMethod.asp). Add an item to the shopping cart, and then click the Shopping Cart icon. You can then use Internet Explorer to access ShippingMethod.asp by specifying a URL address with no parameters (in the form http://servername/ShippingMethod.asp). To view the XML, click Source on the View menu. StepSearch.pasp – Save this page as StepSearch.asp. You can then use Internet Explorer to access StepSearch.asp by specifying a URL with no parameters (in the form http://servername/StepSearch.asp). To view the XML, click Source on the View menu. StepSearch.pasp has the following required parameters: ● hdnCatalog – The catalog that contains the items to search. ● txtCategory – The search category within the catalog. ● txtChildCategory (optional) – The subcategory within the category previously defined.

192 Reference Architecture for Commerce

StepSearch can include additional optional parameters for each catalog and category. For example, the catalog books could have the category business software and the subcategory database. The search for database software books could allow the following additional parameters: ● Author ● ISBN ● PageCount ● Publisher ● ReadingLevel ● Title

●

●

The URL address for such a search would be similar to the following: http://servername/StepSearch.asp?hdnorder=Author%7CISBN%7CPagecount %7CPublisher%7CReading+Level%7CTitle&hdncatalog=Books&txtcategory =Business+Software&txtchildcategory=Database&Author=&ISBN=&Pagecount =&Publisher=&Reading+Level=&Title= ThankYou.pasp – Save this page as Thankyou.asp, and then navigate to the ConsolidatedRetail.com site and log on. Place at least one order and follow the ordering procedure until the OrderSummary.pasp page is displayed. Do not click submit. You can then use Internet Explorer to access Thankyou.asp by specifying a URL address with no parameters (in the form http://servername/ Thankyou.asp). To view the XML, click Source on the View menu. UserProfile.pasp – Save this page as UserProfile.asp, and then navigate to the ConsolidatedRetail.com site and log on. You can then use Internet Explorer to access UserProfile.asp by specifying a URL address with no parameters (in the form http://servername/UserProfile.asp). To view the XML, click Source on the View menu.

Debugging a Custom Site Built on the Reference Architecture If you build a custom business-to-consumer Internet site based on the Reference Architecture code, you should be aware of the following when you debug the application. In some cases you will need to manually enable Visual InterDev debugging for your ASP applications. These situations are documented in article Q258929, “HOWTO: Debug ASP Applications Manually Against Windows 2000 Web Server,” in the Microsoft Knowledge Base at http://search.support.microsoft.com/ Before you attempt to debug the application: 1. Complete the procedures documented in Microsoft Knowledge Base article Q278751, “BUG Error 800a0046 After You Install Visual Studio 6.0 SP4.”

Chapter 10: Debugging and Testing 193

Complete these procedures even if you install Service Pack 5 (and earlier service packs are not present). For more information, see Q244272, “INFO: Visual InterDev 6.0 Debugging” in the Microsoft Knowledge Base. 2. Install Visual Studio Service Pack 5 (SP5), which is available for download at http://msdn.Microsoft.com/vstudio/sp/vs6sp5/dnldoverview.asp/. Refer to the readme file included in the Service Pack download for any additional requirements.

Developing a Test Strategy The test effort requires a focus because there are many possible test areas and different types of testing available for each one of those areas. Because there are always resource constraints — whether these are time, people, or money — prioritization of the test areas and the type and level of testing to be done are very important decisions, and are the focus of preliminary test planning.

Possible Test Areas The following are possible areas to focus your testing: ● User Interface testing – These tests check form and consistency. Checks include those for screen appearance (font, size, colors, and appearance in general), as well as checks on the data validations for all of the fields in all of the forms in the application. Both of these tests should be based on the specification documents. (See Appendix B for more information about data validation in the Reference Architecture.) ● Business Logic testing – The functional specification document defines the business logic that is expected in the implementation. Therefore, there should be a set of test cases for checking the business logic. For the Reference Architecture implementation, this could be done either from the user interface or from the Commerce Server Business Desk utility. This testing should include testing for different kinds of users and for different entry paths into the site. ● Backend testing – Ideally, back-end tests should be done in the database. Because the Reference Architecture uses Microsoft Commerce Server 2000, which is tightly integrated with the SQL Server 2000 tables, the test team could use the Commerce Server objects to interact with the tables. The test team could write stubs to test the Commerce Server objects in an isolated manner, and then compare the results from the stub with the XML output that the code generates. You could also perform this comparison at the user interface layer.

194 Reference Architecture for Commerce

Possible Test Types The test team may want to perform the following types of tests: ● Functional testing ensures that the system provides the functionality described in the functional specification document. ● Regression testing checks whether or not the identical actions performed using an earlier build of a product function the same on a new build of the product. This process determines whether a previously reported problem is still there, whether the problem has been completely resolved; and whether the resolution caused new problems or revealed related problems. ● Security testing guarantees that only users with the appropriate authority are able to use the applicable features of the system. Systems engineers establish different security settings for each user in the test environment. ● Performance testing ensures that the application responds in the time limit set by the user. ● Stress testing verifies that the application responds appropriately with many users and activities happening simultaneously. The number of users must be agreed upon beforehand, and the hardware environment for system testing must mirror production. ● Automated testing can be used for regression and functional testing. This can be very helpful if the system is stable and not changed often. ● Platform testing certifies that the application runs successfully on the operating system and browser combinations agreed upon in the master test plan, which is discussed in the “Testing Methodology” section later in this chapter. ● Internet service provider (ISP) smoke testing confirms that the application responds to requests made over an ISP connection. ● End-to-end interface testing checks all of the inputs and outputs as well as the system. This ensures that the application interacts properly with external systems as defined by the functional specifications. ● Input and boundary testing guarantees that the system allows only valid input. This includes testing to ensure that the maximum number of characters for a field cannot be exceeded and that boundary conditions function correctly (such as valid ranges and off-by-one, null, maximum, minimum, tab order from field to field on the screen, and so on). ● Windows/Internet GUI standards testing verifies that the application has a standardized look and feel. ● Localization testing guarantees that the application will work properly in different languages. ● Euro-compliant testing is used when an application will receive monetary values from the Economic and Monetary Union (EMU).

Chapter 10: Debugging and Testing 195 ●

●

●

●

●

●

●

●

●

●

●

●

Conversion testing checks any data that must be converted to ensure that the application works properly. This could be conversion from a legacy system or changes needed for the new schema. Installation/upgrade testing checks the setup/upgrade routine to ensure that the application can be installed over an existing copy. The test team may decide whether to test only full builds or to also test incremental builds. Usability testing ensures that the application is easy to work with, limits keystrokes, and is easy to understand. The best way to perform this testing is to bring in experienced, medium, and novice users, and solicit their input on the usability of the application. Ad hoc testing is done to test the system with unstructured scenarios to ensure that it responds appropriately. To accomplish this, you can ask someone to perform a function without telling them the steps for doing it. Environment security testing guarantees that the application installs and runs in the production environment. For this testing, the SQL Server and Internet Information Services (IIS) security settings must be identical to those used in production. Network testing determines what happens to the application when different network latencies are applied. For example, it can uncover possible problems with slow network links. Disaster recovery (backup/restore) testing is done to ensure that adequate procedures are in place for restoring the application and its data store in the event of a disaster. This testing is owned by production support. Application-based failover functionality testing ensures that application-based failover works in documented failure situations. User acceptance testing is typically performed by those who are similar in skill set and background to the target audience. The purpose is to determine how well the application meets user requirements and expectations (the user requirements drive the test). Note that the test team doesn’t actually perform this testing, but may supervise or design it. Out of memory and memory leaks testing ensures that the application runs in the amount of memory specified in the technical documentation. This testing also detects memory leaks associated with starting and stopping the application many times. Migration testing of applications from earlier versions of the operating system ensures that the application runs after a later version of the operating system is installed. Help testing is done to ensure that the details provided in Help are relevant and provide a solution to the problem faced. The test team does not check the validity of the business rules while verifying the Help content.

196 Reference Architecture for Commerce

The test team must decide on the level of testing that needs to be done in each of these areas, as follows: ● High – Very important to thoroughly test this area ● Medium – Perform standard testing ● Low – Test if time allows The next section focuses on functional testing.

Functional Testing While developing an e-commerce solution, you should carefully test each build to ensure that it provides the functionality described in the application functional specification. This involves ensuring that the application behaves in the expected manner when each of the user scenarios identified in the application design occurs.

Testing Methodology In most medium-to-large scale projects, a testing team is assigned the task of performing functional testing, and an iterative cycle of application builds and tests lead to the eventual release of the software. Figure 10.1 shows a typical application development and test cycle. Refer to the appropriate subsection in this chapter for a description of each stage in the cycle.

Stage 1 – Document the Test Goals and Master Plan The testing effort begins with the documentation of the test goals and how these goals are to be achieved. It is essential to plan and put in writing the test assumptions, schedule, priorities to test, level of testing, responsibilities, expectations and dependencies, risks, and mitigation plans — all in the context of the testing effort. At the end of this planning, you will have a master test plan document, which is a living document through the test life cycle. The source documents required during this phase are the functional specification document and the high-level release schedule of the code. Refer to the “Developing a Test Strategy” section earlier in this chapter for a description of the areas and types of tests that the team should consider when developing the master test plan.

Stage 2 – Prepare the Detailed Test Plan The detailed test plan describes the various usage scenarios and entry paths for all of the users or accounts. These test usage scenarios are based on the usage scenarios identified during the application design process. The detailed test plan also identifies the priority of each of the scenarios to be tested.

Chapter 10: Debugging and Testing 197

1. Test Goals / Master Test Planning

2. Detailed Test Planning

3. Test Plan Review

4. Test Case Generation

5. Test Execution / Defect Isolation

6. Cycle Complete?

9. Test Report Generation

10. Release

7. Triage Meeting

Key

Test Team

8. Bug Fix

Development Team

Figure 10.1 Typical Test Cycle

The source documents required during this phase are the functional specification document and the high-level application and architectural design. Refer to Appendix C for a sample detailed test plan.

Stage 3 – Review the Detailed Test Plan The development team must review the detailed test plan to ensure that it matches the functional testing requirements for the application. After the testing plan is approved, testing can begin.

Stage 4 – Define the Test Cases The approved detailed test plan is used to generate detailed test cases that define the action to be performed on the application, as well as the input data, expected results, and the need to record the results in a prescribed format. During this stage, you should prioritize the detailed test cases based on the criticality of the function being tested. (It may be necessary to expand each scenario in the detailed test plan into one or more test cases in the detailed test case document.) In addition, you may need to generate a test case sequencing document to reduce execution time. Refer to Appendix D for sample detailed test cases.

198 Reference Architecture for Commerce

Stage 5 – Test the Application During the actual testing stage, you should test all of the application paths end-toend to ensure that they conform to the functional specification. The test team uses a defect-tracking tool to report all of the defects uncovered during testing to program management. In addition, the test team may isolate the defects. The documents necessary for this phase are the detailed test cases.

Stage 6 – Determine if the Build/Test Cycle Is Complete It is unlikely that the application will be ready for release after a single round of testing. The decision to perform another build and test iteration depends on many factors, including the severity of the remaining bugs, budgetary constraints, and milestone dates. Your project plan should allow for several build/test iterations before release.

Stage 7 – Hold Triage Meetings The test team, program management team, and development team discuss the defects during triage meetings, and each defect is assigned to a development team member for resolution.

Stage 8 – Fix and Resolve Bugs The development team must work together to resolve all of the bugs identified during the triage meeting. After resolving them, each bug is assigned back to the owner (the test engineer who raised the bug) for verification and closure, if verification is successful. After a defect — or bug — is resolved, the defect is assigned back to the owner (the test engineer who identified the bug) for closure if it is fixed or for further action if issues are unresolved.

Stage 9 – Generate the Test Report The test report contains status information about specific items listed in the test plan, along with defect information categorized by severity level. This report is crucial for the Go/No Go meeting (discussed in the following subsection).

Stage 10 – Conduct the Go/No Go Meeting When testing is complete, the program management team conducts a Go/No Go meeting to decide whether or not the application is ready to be released. In addition to program management, the required attendees are the test team and the development team. The key documents for this meeting are the release criteria (decided during the master test plan stage) and the test report.

Chapter 10: Debugging and Testing 199

Performance Testing Before deploying an e-commerce solution into a production environment, the application should be thoroughly tested to ensure that it meets the required performance and scalability targets. Generally speaking, an application should be tested in terms of response time and throughput to verify that it provides an acceptable level of performance when used by the target number of users.

Response Time Response time is a measurement of the performance of the application from the individual user’s perspective. It measures the interval between a user request and the response from the application. What constitutes an acceptable response time will vary from site to site, and perhaps from page to page (for example, a user may be prepared to wait longer for his or her user credentials to be authenticated than for the products in a requested category to be displayed), and while a “the faster the better” approach may seem to be the preferred design pattern, you should be aware that in some cases, response time should be compromised to provide adequate security or scalability. The two main factors that contribute to poor response time in an e-commerce application are network latency and application processing time. Network latency can be minimized in a number of ways. For example: ● Deploy the application on suitable infrastructure architecture. For example, use fast switches rather than hubs and specify high performance networking hardware. ● Minimize the physical distance between application tiers. ● Minimize the number of cross-network function calls between components. ● Cache data to avoid unnecessary database access calls. Application processing time is the “think” time that the application requires to perform particular tasks. You can minimize this time by ensuring that your code is well written and that the application uses an appropriate mix of interpreted script and compiled code. Additionally, using an asynchronous programming model where possible can greatly enhance response time. Response time generally degrades as the load on an application increases. Additionally, some programmatic bugs (such as those resulting in memory leaks) can be detected under high load levels only. Therefore, response time tests must be performed under a suitable simulation of the expected load.

200 Reference Architecture for Commerce

Throughput Throughput is a more holistic view of the application’s performance. It measures the ability of the application to cope with the load placed on it by multiple concurrent users. Throughput is generally measured in pages per second or requests per second, and it is an indication of how well the application scales when accessed by large numbers of users. Strategies to improve throughput include scaling out (using multiple servers configured in a load balancing cluster to share the user load), partitioning data across multiple database servers using a hashed value as a partitioning key, minimizing resource contention by utilizing pooling technologies (such as database connection pooling and COM+ object pooling), and scaling up (adding hardware resources to servers in order to cope with the increased load). To accurately test throughput in an e-commerce site, you must profile the kinds of activity your users will be performing. In particular, you must identify the anticipated buy-to-browse ratio (the expected percentage of users who make a purchase compared to the percentage of users who simply browse the catalog). This can vary widely between different types of sites (for example, in a business-to-consumer retail site you may expect only around 20 percent of users to actually make a purchase, while in an Internet banking solution, most users will require a transaction of some sort). To a large extent, this information can be accurately identified only after the site is in production, but you should test using the most accurate estimations available based on the metrics from similar sites. When simulating user load for test purposes, you should try to reflect the expected usage patterns as much as possible to gain an accurate picture of how the application will perform in production. Testing should be performed on a realistic basis. The test infrastructure should be as close as possible to the production environment in which you intend to deploy the application. For example, you should use multiple Web servers configured with some kind of Internet Protocol (IP)-based load balancing. Don’t rely on performance metrics gathered from testing on a single computer! Remember that security measures such as firewalls and encryption affect performance, and incorporate these measures into your test environment.

Performance Testing Tools and Utilities There are a variety of tools that can be used to gather performance statistics. These include monitoring tools such as Microsoft Windows 2000 System Monitor and Netmon, SQL Server Profiler, system log files such as those generated by IIS, dedicated testing tools such as Microsoft Web Application Stress (WAS) tool, and many other third-party stress testing tools. Each tool has its own strengths and weaknesses, so to get an accurate picture of your application’s performance, do not rely on a single tool. Instead, test the application using a variety of different tools.

Chapter 10: Debugging and Testing 201

The WAS tool can be used to simulate the load placed on your application by a number of concurrent users. To do this, you can record a sequence of HTTP requests to your site, and have the WAS tool play those requests back for a specified number of concurrent users. The tool gathers response time and throughput statistics, which can then be used to evaluate your application’s performance. You can learn more about the WAS tool and download it at http://webtool.rte.microsoft.com/ default.htm When using stress testing tools such as WAS, you should create several scripts simulating different user scenarios, rather than a single script. This allows you to run the scripts individually when you are trying to identify a specific performance bottleneck, or simultaneously when you are trying to simulate a realistic load on the application. Most stress testing tools allow you to configure the relative stress placed on the system by each script as a percentage of the total stress, allowing you to more accurately reflect the usage patterns you expect to find in production.

Performance Testing Methodology The customers of an e-commerce site expect the site to perform well at all times. Performance, scalability, and overall reliability of the application are fundamental to the Web application design. The methodology of performance analysis includes the following distinct steps: 1. Preparing for the analysis 2. Creating a stress script 3. Executing the test 4. Analyzing the results 5. Documenting and delivering the results. Each of these steps is examined in the following sections.

Preparing for the Analysis The first step of the analysis involves gathering information. This information should provide you with the details necessary to duplicate the application environment and understand how the application is used; it should also tell you of any existing performance issues. Sources for this information include marketing forecasts, production IIS logs, performance logs, and functional specifications for the application. Of course, much of this information is available for an existing production site only. For a new site, you should rely on marketing forecasts and metrics obtained from similar sites. The information you collect is critical to the success of the performance analysis. It will help determine the requirements for the test environment and will be used through all phases of the analysis — from staging the environment to deciphering test results.

202 Reference Architecture for Commerce

You should also identify all deliverables for the performance analysis before the analysis begins. Think of the deliverables as the contract between the test team and the application owners. Often when conducting performance analysis, the application owners may not know what they are looking for out of the analysis. Creating a set of deliverables can answer this for them. Create a Replica of the Production Environment

For the most accurate test results, the test facility should mimic the current or expected production environment. This includes both hardware and software configurations. If load-balancing solutions such as Microsoft Network Load Balancing or the Windows NT Load Balancing Service (NLB/WLBS) are deployed in production, your test environment should reflect this. Server roles and the number of servers deployed in production should similarly be configured in the test facility. For example, if you are using a cluster of three IIS servers in production, match that configuration in the stress test lab. CPU, RAM and disk configurations for each IIS server should also match what is in production. Service packs, drivers, and BIOS versions for hardware must be duplicated. Matching hardware and software enables you to produce more accurate benchmark numbers and eliminates the need to extrapolate data. You may not be able to create an exact replica of your production environment due to budget constraints or other limitations. In that case, be sure to note the differences when you are performing your data analysis. To test the ConsolidatedRetail.com site, the application was deployed on the test infrastructure shown in Figure 10.2. The workstations were used to simulate Internet clients (one of the computers ran Windows 2000 Professional, while the other two ran Windows 98), accessing the site through a level three switch. The IIS servers in the Web tier then communicated through a second switch to the database server. All Commerce Server objects and pipelines were deployed on the IIS servers (that is, there was no separate physical tier of application servers) and all of the site data, with the exception of the direct mail database, which was stored on the SQL Server database server behind the second switch. The direct mail database was deployed on the IIS servers. This infrastructure was designed to provide an approximation of the deployment environment for the application.

Chapter 10: Debugging and Testing 203

IIS Server (4x500 MHz, 512 Mb RAM)

IIS Server (4x700 MHz, 512 Mb RAM)

Switch

Ethernet

Ethernet

Ethernet

Test Workstation (P2, 266, 128Mb RAM)

Switch

Test Workstation (P2, 266, 128Mb RAM)

SQL Server (8x500 MHz, 2098 Mb RAM)

IIS Server (4x700 MHz, 512 Mb RAM)

Test Workstation (P2, 266, 128Mb RAM)

IIS Server (4x700 MHz, 512 Mb RAM)

Figure 10.2 Test Infrastructure

Involve the Application Owner

Many times the application owners have conducted research of their own. Discussing performance issues with the application owners may save you time. They will be able to provide you keen insight into performance anomalies with their application. In particular, the application developers may have specific areas of concern and knowledge that a manager may not be able to provide. If their research uncovers existing bottlenecks, your task could simply involve verifying these trouble areas and providing the developers with greater detail.

204 Reference Architecture for Commerce Understand the Technology Behind the Application

Understanding the technologies behind the application before proceeding is imperative. The more in-depth understanding you have of the application, the more thorough your performance/stress analysis will be. For example, if you know that a particular application relies heavily on XML, you should become familiar with the performance tuning aspects of XML. In the case of the ConsolidatedRetail.com application, the test team needed to be confident in the deployment and use of Commerce Server 2000, as well as XML and the XSL ISAPI filter. Define the Transaction or User Scenarios

To complete a successful performance/stress analysis, you must know how end users use an application on a daily basis. You will find that users tend to do one task more than others. Your performance/stress scripts should reflect this usage pattern. When you are determining these usage patterns, be sure to contact marketing and product support staff. These people generally have more contact with users and will have insight into these statistics. IIS logs are also a good source for understanding how often application components or pages are accessed. Logs can also be extremely useful, not only for defining user scenarios to script, but also for verifying page view distribution in production compared to stress test distributions. In the case of the ConsolidatedRetail.com site, the expected usage pattern is a browse to buy ratio of 80 percent. Additionally, of the 20 percent of users who make a purchase, it is expected that half of them will be returning users who have already registered, and half will be new customers who must register before checking out. Define the Goals

Be sure to define the goals of the analysis, and include these goals in the test plan so that everyone has the same understanding of what the deliverables are. This reduces the risk of having to re-run test scripts, which wastes time and resources and can negatively affect the analysis because the test team may tend to rush through the data due to a lack of time.

Creating the Stress Script After gathering the required information and preparing your test environment, the next step in the performance/stress analysis is to create a stress script that accurately simulates the expected traffic for the site. This can be accomplished using historical data from the current build/version of the site or expected data from the marketing or business analysts. To generate bulletproof stress scripts, consider the factors discussed in the following subsections.

Chapter 10: Debugging and Testing 205

Create More Than One Script

When dealing with multiple scenarios, you should avoid creating a single script that contains all of the scenarios. Using a single large script will make it difficult to isolate the particular scenario that is slowing down the entire script. For example, if you want to simulate a common e-commerce site, you may have a user scenario in which the user browses categories and products, another in which the user adds to the shopping cart and checks out, and yet another that allows the user to search for products. If the test team creates three separate scripts, the team can execute stress tests separately, identify the bottlenecks in each user scenario and simultaneously simulate the anticipated traffic mix of the site. Avoid Record and Play Back

The days of static Web sites have long been over. A majority of today’s sites, particularly those created for the purpose of e-commerce, have content that is purely dynamic. For that reason, you cannot accurately script the site by simply recording and playing back the basic get and post commands. You may need to customize if the site dynamically generates items such as shopper IDs, basket IDs, order IDs, and GUIDs. Many test tools have features to capture the dynamically changing variables for each thread (virtual user), but you need to verify the script results to ensure variables are being generated properly. Many test tools also have the ability to import data from a .csv or .txt file. This feature allows you to dump a list of products and categories from the SQL database and use the data contained in the files as the means to make your script more dynamic (instead of making your script use the same products repeatedly). The WAS tool allows you to create a list of variables to include in your script, for example; user names, passwords, products, and categories can all be created as variables. Verify the Actions of the Stress Tool

Before proceeding with a large-scale test, you should always verify that the stress tool is accurately using the site as an actual user. To do this, you must understand what each ASP page accesses and executes on the IIS server and SQL Server. The IIS server log file and the SQL Profiler/Trace files are excellent resources to use when tracking the behavior of ASP pages. A more accurate method is to walk through the site with a browser and make note of all SQL commands and stored procedures that are called for each page. In addition, note all of the Web content (such as GIF, XML, ASP, and HTML files) that appears in the IIS log for each page included in the stress script. You can then play the script back for one user going through the scenario a single time and verify that the identical server-side activity occurs in the SQL trace file and IIS log.

206 Reference Architecture for Commerce

Executing the Performance/Stress Test At this point, you should have an environment built to host the application and a script created that simulates client load. The third step of a performance/stress analysis is to execute the stress test by running your script. The following subsections outline some basic points to use when executing a performance/stress test. Smoke Test the Site

Smoke testing allows you to identify the number of clients and number of threads necessary to find the application system bottleneck. Microsoft recommends using several clients running a lower number of threads, rather than a single client running a high number of threads. Smoke testing means running several short stress tests to focus into the optimal ratio between clients and virtual user threads. Optimal means the ratio that is producing a performance degradation or bottleneck on the servers, not on the stress clients. Start Gather Performance Data

When you have the correct ratio between clients and threads, set up the test by starting System Monitor on all of the servers and logging every counter. For tests that are 30 minutes or less, you can use 15- or 30-second intervals. For longer tests, use 60- to 300-second intervals to keep the log file size to a minimum. Reset the IIS Log Before Starting Your Test

Clearing the IIS logs eases the process of data analysis. You can reset the logs by shutting down the IIS Administrator Service (iisadmin) by using the iisreset command or the net stop iisadmin /y command. Next, delete the IIS log file found in C:\Winnt\System32\LogFiles, and restart the w3svc service by using the net start w3svc command. Clear the Windows Events System, Security, and Application Logs

Clearing the Windows Events logs allows you to identify any abnormal error messages resulting from the site during stress testing. Configure and Start the SQL Profiler

On the SQL Server, start the SQL Profiler, create a new trace, and add the T-SQL and Locks events only. This trace shows all of the SQL commands and stored procedures, reads, writes, and command durations, and any deadlocks that occur. Note that SQL trace files rapidly grow in size as the test proceeds. Therefore, only collect them for the entire test if you are running a test of 30 minutes or less. For an extended test, Microsoft recommends running SQL Profiler at 30-minute intervals in the beginning, middle, and end of the test. If you have an additional SQL Server, you can set up your trace to log to a database instead of a file.

Chapter 10: Debugging and Testing 207

Create a Controlled Environment

If possible, try to execute the stress test with no other activity on the IIS cluster or SQL Server(s). Using this controlled environment, you can make sure that there are no abnormal error messages, page views, network traffic, or load coming from any source other than your stress clients.

Analyzing the Results After you run the tests and generate the test data, you can begin the analysis phase. First, you should verify that the stress test ran through the simulation successfully, and then proceed with a complete analysis of the data. This process is outlined in the following subsections. Stop the Simulation and Halt Data Collection

Stop the stress scripts, System Monitor, and SQL Profiler on all of the clients and servers in the test environment. Make sure that the System Monitor, SQL Profiler trace, IIS log, and Windows Event Logs have been saved in a separate directory, allowing you to archive and organize your test data. Review the Windows Event Log

Read through the Windows Event Log and make sure that no abnormal messages were generated as a result of your stress script. Errors generated as a result of the stress test are acceptable. Analyze the Performance Monitor Data

System Monitor data can help you determine metrics such as system CPU utilization, memory utilization, disk queuing, and w3svc counters. Analyze the SQL Trace File

When you analyze the SQL trace file, search for SQL commands and stored procedures that have long durations (more than a second), and a high number of SQL reads or writes. If you are not familiar with the performance tuning aspects of SQL Server, forward your findings to a SQL architect for further analysis. Tuning the SQL Server may involve adding a few indexes and changing code within the stored procedures, or it can become a more involved process of re-architecting the design of the database. Verify the Pages Accessed

IIS log files should help identify all of the page views accessed during the stress test. Additionally, Commerce Server 2000 statistics and IIS log files can be imported into a data warehouse and examined using the Reports module of Commerce Server Business Desk. This can provide an in-depth picture of the site activity during the test.

208 Reference Architecture for Commerce Measure Throughput for the Site

Throughput is measured in terms of successful completions of user scenarios. For example, successful shopping basket creations, orders processed, and searches performed are considered successful completions for an e-commerce site. These metrics are understandable by most everyone, not just developers. One of the easiest and most accurate methods to define throughput is by using a table in the database and measuring the delta before and after the test. You can then reconcile this data using the IIS log, counting the number of actual page views. Use SQL Tables for Throughput Analysis

As mentioned earlier, SQL databases also have tables that can be used to count the number of successful transactions. For example, if there is a shopping basket table, run a row count before and after the stress test. The difference is the number of shopping baskets created during the stress test. The results of the query, along with the time stamps at the beginning and end of the test, help determine a transaction/ time throughput rate. Verify Throughput Numbers

The key questions to answer during this verification is whether the number of transactions indicated by the IIS log correlate with the number of total new transactions indicated by entries in the database, and if not, why. Another potential source for verifying throughput is stress tool reports, although these reports can be overly optimistic when compared to server side data. Therefore, you may want to trust the server side data if there is a discrepancy. Verifying throughput from two or more sources enables you to be more confident in the results.

Conclusion This chapter provided instructions that will allow you to access and debug output from the PASP script files included in the Reference Architecture application. In addition, it provided an overview of the debugging and testing processes and best practices, with specific references to the actual tests performed on the Reference Architecture application. You can use this chapter as a reference when developing a test plan for customized software based on the Reference Architecture. For more information and specific examples to use when preparing detailed test plans and test cases, refer to Appendices C and D.

Part 4 Appendices Part 4 of the Developer’s Guide for the Reference Architecture for Commerce provides additional reference materials that you may find helpful when reviewing the Reference Architecture application code or when building or testing a solution based on the Reference Architecture. The materials included in Part 4 are intended primarily for application developers and testers. Part 4, “Appendices,” includes the following: ● Appendix A: XML Output from ConsolidatedRetail.com ● Appendix B: Data Field Validation ● Appendix C: Sample Detailed Test Plan ● Appendix D: Sample Detailed Test Cases

Appendix A XML Output from ConsolidatedRetail.com This appendix contains the XML output from the following ConsolidatedRetail.com PASP files: ● Acct.pasp ● AddressBook.pasp ● AddtoList.pasp ● AddtoListResp.pasp ● Basket.pasp ● Category.pasp ● ChangePasswd.pasp ● CreditCards.pasp ● DeleteAddressBook.pasp ● EditAddressBook.pasp ● EditCreditCard.pasp ● ForgotPasswd.pasp ● Index.pasp ● ListBase.pasp ● ListSearch.pasp ● Login.pasp ● MultiShipping.pasp ● OrderHistory.pasp ● OrderHistoryDetail.pasp

212 Reference Architecture for Commerce ● ● ● ● ● ● ● ● ● ●

OrderSummary.pasp Payment.pasp Product.pasp Registration.pasp SearchResults.pasp Shipping.pasp ShippingMethod.pasp StepSearch.pasp Thankyou.pasp UserProfile.pasp

Acct.pasp The following XML is a sample of the output produced when an authenticated user accesses Acct.pasp. (This XML was generated for a user who logged on using SQL Server authentication rather than Passport; therefore, the tag appears in the XML output.) localhost%3A81 Browse Catalogs: Books Books Hardware Hardware

Appendix A: XML Output from ConsolidatedRetail.com 213

AddressBook.pasp The following XML is a sample of the output produced when an authenticated user accesses AddressBook.pasp. (This XML was generated for a user who logged on using SQL Server authentication rather than Passport; therefore, the tag appears in the XML output.) In addition, note that has a value of 1, which indicates that the billing address is same as the shipping address: localhost%3A81 {CDBD249A-3D16-4952-A2CC-947EA9D6985B} 1 Kim Abercrombie Home My House Redmond Washington 12345 019182782 1 Browse Catalogs: Books Books Hardware Hardware

214 Reference Architecture for Commerce

AddtoList.pasp The following XML is a sample of the output produced when a user adds items to a shopping list: localhost%3A81 Microsoft Age of Empires II: The Age of Kings: Inside Moves Books 1 0 Browse Catalogs: Books Books Hardware Hardware

AddtoListResp.pasp The following XML is a sample of the output produced when a user views the contents of an updated shopping list: localhost%3A81 Your item has been added to your list.

Appendix A: XML Output from ConsolidatedRetail.com 215 Browse Catalogs: Books Books Hardware Hardware

Basket.pasp The following XML is a sample of the output produced when a user accesses Basket.pasp and has a product in the basket: localhost%3A81 http://MYCOMP:81/index.pasp — 1 Browse Catalogs:

216 Reference Architecture for Commerce Books Books Hardware Hardware

Category.pasp The following XML is a sample of the output produced by Category.pasp: localhost%3A81 Hardware Hardware Hardware Hardware 2/10/2000 2%2F10%2F2000 2/10/2000 2%2F10%2F2000 SKU SKU prodid prodid USD USD lbs lbs 2 2 False False 9/27/2001 3:33:47 PM 9%2F27%2F2001+3%3A33%3A47+PM

Appendix A: XML Output from ConsolidatedRetail.com 217 9/27/2001 3:33:42 PM 9%2F27%2F2001+3%3A33%3A42+PM Hardware Hardware Featured Products Featured+Products Hardware Hardware Gaming Devices Gaming+Devices Hardware Hardware Keyboards Keyboards Hardware Hardware Mice Mice Browse Categories: no products found at the root level for catalog 'Hardware'. Browse Catalogs: Books Books Hardware Hardware

218 Reference Architecture for Commerce

ChangePasswd.pasp The following XML is a sample of the output produced by ChangePasswd.pasp: localhost%3A81 255 CheckPassword txtCurrentPassword Please enter your current password. 255 CheckPassword txtNewPassword Please enter a new password. 255 CheckPassword txtConfirmPassword Please confirm the new password. Browse Catalogs: Books Books Hardware Hardware

Appendix A: XML Output from ConsolidatedRetail.com 219

CreditCards.pasp The following XML is a sample of the output produced by CreditCards.pasp after a user saves credit card information in his or her profile: localhost%3A81 {CDF383A4-7932-4674-867A-085F7B6E181A} Kim Abercrombie xxxxxxxxxxxxxxx5231 01 2002 Personal {E246BE62-8937-4CF2-A312-178DEC172A5F} Visa Browse Catalogs: Books Books Hardware Hardware

220 Reference Architecture for Commerce

DeleteAddressBook.pasp The following XML is a sample of the output produced by DeleteAddressBook.pasp when no address parameter is specified: localhost%3A81 Shipping AddressBook.pasp {372BB421-8990-4D41-9F23-6F9E682E8321} 1 a b a a a Alabama 12345 12345 0 Alabama Alaska Arizona Arkansas California Colorado Connecticut Delaware District of Columbia Florida Georgia Hawaii Idaho Illinois Indiana Iowa Kansas Kentucky Louisiana Maine Maryland Massachusetts

Appendix A: XML Output from ConsolidatedRetail.com 221 Michigan Minnesota Mississippi Missouri Montana Nebraska Nevada New Hampshire New Jersey New Mexico New York North Carolina North Dakota Ohio Oklahoma Oregon Pennsylvania Rhode Island South Carolina South Dakota Tennessee Texas Utah Vermont Virginia Washington West Virginia Wisconsin Wyoming Browse Catalogs: Books Books Hardware Hardware

222 Reference Architecture for Commerce

EditAddressBook.pasp The following XML is a sample of the output produced by EditAddressBook.pasp when no address parameter is specified: localhost%3A81 Alabama Alaska Arizona Arkansas California Colorado Connecticut Delaware District of Columbia Florida Georgia Hawaii Idaho Illinois Indiana Iowa Kansas Kentucky Louisiana Maine Maryland Massachusetts Michigan Minnesota Mississippi Missouri Montana Nebraska Nevada New Hampshire New Jersey New Mexico New York North Carolina North Dakota Ohio Oklahoma Oregon Pennsylvania

Appendix A: XML Output from ConsolidatedRetail.com 223 Rhode Island South Carolina South Dakota Tennessee Texas Utah Vermont Virginia Washington West Virginia Wisconsin Wyoming 255 CheckListedAs txtListedAs Please enter a valid 'Listed As' name. 34 CheckFullName txtAddressName Please enter a valid name. 20 CheckAddress1 txtAddressLine1 Please enter a valid address line 1. 20 CheckAddress2 txtAddressLine2 Please enter a valid address line 2. 22 CheckCity txtCity Please enter a valid city. CheckState txtRegionName Please select a state. 14

224 Reference Architecture for Commerce CheckZipCode txtPostalCode Please enter a valid zip code. 14 CheckPhoneFaxNumber txtPhoneNumber Please enter a valid phone number. Shipping 1 Browse Catalogs: Books Books Hardware Hardware

The following XML is a sample of the output produced by EditAddressBook.pasp when an address parameter is specified: localhost%3A81 AddressBook.pasp Alabama Alaska Arizona Arkansas California Colorado Connecticut Delaware District of Columbia Florida

Appendix A: XML Output from ConsolidatedRetail.com 225 Georgia Hawaii Idaho Illinois Indiana Iowa Kansas Kentucky Louisiana Maine Maryland Massachusetts Michigan Minnesota Mississippi Missouri Montana Nebraska Nevada New Hampshire New Jersey New Mexico New York North Carolina North Dakota Ohio Oklahoma Oregon Pennsylvania Rhode Island South Carolina South Dakota Tennessee Texas Utah Vermont Virginia Washington West Virginia Wisconsin Wyoming 255 CheckListedAs txtListedAs Please enter a valid 'Listed As' name. 34

226 Reference Architecture for Commerce CheckFullName txtAddressName Please enter a valid name. 20 CheckAddress1 txtAddressLine1 Please enter a valid address line 1. 20 CheckAddress2 txtAddressLine2 Please enter a valid address line 2. 22 CheckCity txtCity Please enter a valid city. CheckState txtRegionName Please select a state. 14 CheckZipCode txtPostalCode Please enter a valid zip code. 14 CheckPhoneFaxNumber txtPhoneNumber Please enter a valid phone number. Shipping {14505FF4-8B94-4102-9745-0AD40CC2010B} {CDBD249A-3D16-4952-A2CC-947EA9D6985B} 1 Kim Abercrombie Home My House

Appendix A: XML Output from ConsolidatedRetail.com 227 Redmond Washington 12345 019182782 1 Browse Catalogs: Books Books Hardware Hardware

EditCreditCard.pasp The following XML is a sample of the output produced by EditCreditCard.pasp before a user submits revised credit card information for his or her profile: localhost%3A81 {CDF383A4-7932-4674-867A-085F7B6E181A} {E246BE62-8937-4CF2-A312-178DEC172A5F} Kim Abercrombie xxxxxxxxxxxxxxx5231 Visa 01 2002 Personal

228 Reference Architecture for Commerce visa Visa mastercard MasterCard amex American Express discover Discover 01 January 02 February 03 March 04 April 05 May 06 June 07 July 08 August 09 September

Appendix A: XML Output from ConsolidatedRetail.com 229 10 October 11 November 12 December 2001 2002 2003 2004 2005 2006 255 CheckListedAs txtCCNickName Please enter a valid 'Listed As' name. 34 CheckFullName txtCCName Please enter a valid card name. Browse Catalogs: Books Books Hardware Hardware