Microsoft Commerce Server 2000 Resource Kit with CD-ROM by Microsoft Corporation, Corporation Microsoft, Microsoft Corporation (Manufactured by)

From Barnes & Noble

The Barnes & Noble Review
Microsoft's new Commerce Server 2000 is the most robust, powerful e-commerce solution Microsoft has yet delivered. A far cry from yesteryear's Site Server product family, Commerce Server 2000 doesn't just deliver shopping carts and catalogs; it offers comprehensive personalization, profiling, merchandising, and targeting capabilities. Commerce Server ought to help companies bring powerful B2B, B2C and supply-chain e-business applications to market a whole lot faster. But by virtue of its sheer breadth and depth, it'll require an awful lot of planning and care. For instance, you wouldn't dare to deploy it without first carefully reviewing the Microsoft Commerce Server 2000 Resource Kit.

This 600+ page kit covers the whole e-Business lifecycle: planning, custom application development, site testing, deployment, management, maintenance, optimization, and troubleshooting. Microsoft walks you through defining project vision and scope; planning for growth and availability; and preparing a complete project plan. (As you're reviewing this material, you might also want to refer to the complete sample sites on the Kit's CD-ROM.)

You'll find detailed techniques and best practices for working with the Commerce Server 2000 Profile System, which lets you build sophisticated dynamic profiles using data you already have, either within your site or in external systems -- and then customize content delivery "on the fly," based on those profiles.

Microsoft consultants then review every step of deployment, including customizing the Commerce Server Site Packager, which makes it easier to migrate sites among servers, for testing, staging, production, and distribution.

In addition to sample sites, the kit's CD-ROM contains population tools that help you generate profiles for large numbers of users at once; a Prediction Viewer that helps you make the most of Commerce Server's powerful business analytics; and a sample component illustrating the art of programming custom business process pipelines.

Commerce Server virtually defines mission-critical application. And the Commerce Server 2000 Resource Kit defines essential resource. (Bill Camarda)

Bill Camarda is a consultant and writer with nearly 20 years' experience in helping technology companies deploy and market advanced software, computing, and networking products and services. His 15 books include Special Edition Using Word 2000 and Upgrading & Fixing Networks For Dummies®, Second Edition.

From the Publisher

With this Microsoft RESOURCE KIT, IT professionals learn how to deploy and manage the server platform built for e-business with expertise from those who know the technology best-the Microsoft Commerce Server 2000 product team. This powerhouse reference packs 500 pages of technical drill-down-including detailed information on Commerce Server features and guidelines for implementing specific e-commerce scenarios.

Coverage includes:

• defining site requirements and planning for growth

• using built-in development tools and services

• creating applications for direct marketing, supply-chain integration, and corporate procurement

• managing security and privacy issues

• integrating third-party systems

• migrating code

• using pipeline objects

• extending the data warehouse

• administrative tools

• testing

• and deployment.

Plus, the CD-ROM comes loaded with exclusive productivity tools and utilities-straight from the Commerce Server development team. This essential kit offers everything IT professionals need to help maximize the productivity of their e-commerce operations, save time, and reduce support costs!

Booknews

Deals with deployment of the Commerce Server 2000 to support business- to-consumer and business-to-business e-commerce web sites. The guide uses scenarios to illustrate considerations for business goals, site architecture, planning methodologies and considerations, development best practices, deployment procedures, and system administration for typical retail and supplier sites. Specialized topics include planning for scalability and high availability, integrating Commerce Server with ERP systems, and designing for an international audience. The CD-ROM contains tools, utilities, and sample sites. Annotation c. Book News, Inc., Portland, OR (booknews.com)

Product Details

• Table of Contents
• Forewords & Introductions
• Read an Excerpt
• Read a Sample Chapter

Table of Contents

Forewords & Introductions

About This Book

The Microsoft Commerce Server 2000 Resource Kit consists of one book and a single compact disc (CD) containing tools, additional reference materials, and a fully searchable online version of the book.

Resource Kit Support Policy

The software supplied in the Commerce Server 2000 Resource Kit is not supported. Microsoft does not guarantee the performance of the tools, response times for answering questions, or bug fixes for the tools. However, Microsoft does provide a way for customers who purchase the Commerce Server 2000 Resource Kit to report bugs and to receive possible fixes for their issues. You can do this by sending e-mail to rkinput@microsoft.com. This e-mail address is only for issues related to the Commerce Server 2000 Resource Kit. For issues related to the Microsoft Commerce Server 2000 product, see the support information included with the product. For more information about support for Microsoft products, see http://suppoft.microsoft.com.

Additional Information Online

Updates and information about deploying sites with Commerce Server 2000 are available at http://www.microsoft.com/commerceserver on an ongoing basis. Additional information and resources,including white papers and hosted online chats, are available at http://www.microsoft.com/technet/comm.

Read an Excerpt

Chatper 1: Overview and Scenarios

The Commerce Server 2000 Resource Kit supplements Microsoft Commerce Server 2000 product software and documentation in the same way that a good tour guide supplements a set of detailed street maps. Commerce Server 2000 Help contains step-by-step descriptions for using the software. It is procedural information-a guide to the features of the product and instructions for using them. The Commerce Server 2000 Resource Kit expands on this information by providing real-world scenarios and guidelines for setting up e-commerce Web sites with Commerce Server.

Introduction to Commerce Server 2000

Commerce Server 2000 delivers a scalable e-commerce platform that provides ready-to-use features for developing, deploying, and upgrading effective e-commerce applications for the Web. This extensible platform enables customers, Independent Software Vendors (ISVs), and Internet Service Providers (ISPs) to build solutions that scale with business needs and integrate with existing systems and data. Using Commerce Server scalable server architecture with Microsoft Windows 2000, you can meet the increasing performance demands of growing e-commerce infrastructures. Commerce Server is comprised of five systems: the Business Analytics System, the Product Catalog System, the TargetingSystem, the Profiling System, and the Business Process Pipelines System. Each system is designed so that you can easily customize it to meet your business needs.

Business managers use Commerce Server Business Desk to work with the five Commerce Server systems. For example, they can use Business Desk to update catalogs, target content to users, profile users and organizations, and analyze site usage and productivity. System administrators use Commerce Server Manager to configure system resources and manage the applications, databases, and Web servers.

Commerce Server and .NET Enterprise Servers

Although Commerce Server is a stand-alone product, it is designed to operate seamlessly with other Microsoft .NET Enterprise Servers. The .NET Enterprise Servers are Microsoft's comprehensive family of server applications for building, deploying, and managing scalable, integrated Web solutions with fast time to market. You can use .NET Enterprise Servers to build systems that integrate Commerce Server sites with the rest of your management information system. If you need this level of integration, you can implement one or more of the other .NET technologies in conjunction with Commerce Server.

Some of the .NET technologies that typically are used with Commerce Server include:

• COM+ Services (an extension to the Component Object Model)
• Microsoft Application Center 2000
• Microsoft BizTalk Server 2000
• Microsoft Host Integration Server 2000
• Microsoft SQL Server 2000

COW Services

COM+ Services (Component Services, including MTS) is a unified programming model that you can use to build component-based, three-tier distributed applications. COM+ builds on the Microsoft Component Object Model (COM) by combining COM with the transactional features of Microsoft Transaction Server (MTS). It extends the programming environment by adding a rich set of features to make it easier to develop, deploy, and administer highly scalable, distributed, component-based solutions.

Application Center

Application Center is a high-availability deployment and management tool for Web applications built on Windows 2000. It extends the core set of Web application services found in Windows 2000 (Internet Information Services (IIS) 5.0, Active Server Pages (ASP), COM+, Message Queuing), and provides a suite of monitoring, testing, and diagnostic tools not available in the core operating system. Application Center is designed for customers with high-end requirements for scalability and availability.

You can use Application Center with Commerce Server to deploy content and make incremental updates to your Web site. For more information about using Application Center with Commerce Server, see "Deploying Your Site" in Commerce Server 2000 Help and Chapter 15, "Deploying Content," in the Commerce Server 2000 Resource Kit...

Read a Sample Chapter

• Gift Certificate Feature
• Business Desk Modifications
• Site Resource Modifications
• Site Page Modifications
• Checkout Pipeline Modifications
• Profile Modifications
• Report Modifications
• Site Term Modifications
• Campaign Modifications
• Deployment Summary
• Profiling System Utilities
• Profiles Schema Mover
• Site Terms Viewer
• Profiling System: Operational Considerations
• Profile Definition Keys
• Profiling System Design Considerations
• Managing Pre-Existing Accounts in Active Directory Stores
• User Profile Import DTS Task
• Advertising Scoring and Selection
• Campaign Goals and Item Goals
• Initial Scoring
• Scoring (Targeting)
• Selection
• Troubleshooting Ad Scoring and Selection

The features that you can implement with the Microsoft Commerce Server 2000 software are limited only by your imagination. Many procedures for developing an e-commerce site using Commerce Server are described in Commerce Server 2000 Help, the Commerce Server 2000 Software Development Kit (SDK), and other chapters in this book. This chapter supplements that information with the four sections described in the following table.

Section	Describes
Gift Certificate Feature	How to add a Gift Certificate feature to the Retail Solution Site
Profiling System Utilities	Functionality and operation of two tools you can use to develop profiles: Profiles Schema Mover Site Terms Viewer
Profiling System: Operational Considerations	Guidelines for using the Profiling System
Advertising Scoring and Selection	How the advertising engine leverages the Content Selection Framework (CSF) to determine which advertisements to display on a Web site

Gift Certificate Feature

This section describes how the Contoso, Ltd. company described in Chapter 2 ("A Retail Scenario") added a Gift Certificate feature to its site. (Before reading this chapter you should be familiar with the basic features and implementation details of the Retail Solution Site described in documentation available at http://www.microsoft.com/commerceserver/solutionsites. You should also read Chapter 2, to see how Contoso decided to implement its site.)

Contoso identified the data requirements listed in the following table for its gift certificates.

Data requirement	Value and type
Certificate identification	Eight-digit alphanumeric code (primary key) (string)
Purchaser information	Name and contact information (string)
Value of certificate	Currency value (currency)
Recipient	Name and contact information (string)
Current balance	Currency value (currency)
Date of purchase	Date (date)

Contoso's gift certificates can be used only for online shopping. The gift certificates issued by the online store can't be used to make purchases from their mail order catalog. The Contoso team did recognize, however, that when they issued an online gift certificate, they also had to adjust the revenue and liability accounts of their accounting system accordingly.

Contoso decided to add the new gift certificates feature to its online catalog. They set the minimum value for a gift certificate at $20, with value increments of $5 up to a maximum of $300. Each gift certificate contains a unique redemption code that customers use to make purchases. Contoso will mail (or e-mail if the purchaser provides an e-mail address for the recipient) the gift certificate, including the redemption code and instructions for using it to make a purchase, to the recipient.

When recipients log in to use their gift certificates, they can either register or shop as guests. To make purchases with their gift certificates, they simply select the Gift Certificate option on the Order Summary page. When they select this option, they are redirected to the Gift Certificate Redemption page and asked to enter the certificate redemption code. Customers can't use only part of a gift certificate's amount to make a purchase; they must use the full amount on their purchases.

The Contoso team made the implementation decisions listed in the following table for their gift certificate feature.

Requirement	Implementation decision
Site management	Add Commerce Server Business Desk modules to the Orders category.
Site administration	Create a new site resource to set the connection string for the gift certificates data source.
Profile information	Store contact information and account balance data in Microsoft SQL Server 2000 in a table added to the Contoso_Commerce database.
Site implementation	Add two new pages: A page for buying a gift certificate. Similar to Contoso's shipping address form, but with additional boxes for the e-mail address and for entering a message to include with the gift certificate. A page for purchasing merchandise with a gift certificate. Enables customers to enter their gift certificate redemption codes.
Order processing	Add a new pipeline component to the Checkout pipeline.
Accounting updates	Create a Component Object Model (COM) object that communicates asynchronously with the accounting system, using Microsoft Host Integration Server 2000.
Management reports	Create the following dynamic and static reports: Gift Certificate Sales Report Gift Certificate Percentage Report (percentage of total online sales) Number of Gift Certificate Purchases (added to the Order Events report) Gift Certificate Buyers (static)
Targeting requirements	Display a gift certificate advertisement to previous gift certificate buyers. This is a house ad.

The modifications Contoso made to implement gift certificates on its site are described in the following sections.

Business Desk Modifications

The development team decided to add three Business Desk modules to manage gift certificate sales. They placed these modules in the Orders category in the Business Desk navigation pane, and provided the features listed in the following table.

Feature	Implementation
List and delete current gift certificates	List sheet
Create and edit gift certificates	Edit sheet
Update gift certificate caches	Refresh

To implement the necessary changes in their Business Desk, the development team followed the steps outlined in the "Building Business Desk Modules" section of Commerce Server 2000 Help. The following steps summarize what the development team did:

1. Add a new configuration file.

The team first added a new configuration file, named GiftCerts.xml, to the ContosoBD\config directory. The following excerpt from the file shows the action "View Certificates" and the ASP files associated with this new module:

<config xmlns="x-schema:bdmodule-schema.xml">

  <actions>

<action id='orders/cert_list.asp''helptopic=''cs_ft_certs_EXTN.htm''>

<name>Certificate List</name>

<tooltip>View Certificates</tooltip>

  <tasks>

    <task icon=''taskopen.gif'' id=''open''>

      <postto action=''orders/certstatus_view.asp''   formname=''selectform'' />

<name>&lt;U&gt;O&lt;/U&gt;pen</name>

<key>o</key>

<tooltip>Open Certificate</tooltip>

</task>

</tasks>

</action>

2. Add a module entry to the master configuration file.

Because the Contoso team decided to add the new modules to the Orders category, they had to add the following module entry to the moduleconfigs section of the master configuration file, Bizdesk.xml:

<moduleconfig id="GiftCerts.xml" category="orders" />

3. Implement list sheet, edit sheet, and refresh functions.

The team implemented the three functions in the following Active Server Pages (ASP) files:

• Cert_list.asp. This file implements a list sheet and is based on the Orderstatus_view.asp file included with Commerce Server.
• Cert_edit.asp. This file implements an edit sheet and is based on the Orderstatus_list.asp file included with Commerce Server.
• Refresh.asp. This file refreshes the cache provided by the Retail Solution Site and is included with Commerce Server.
4. Extend Business Desk Help.

The team created four new Help files to extend the Business Desk Help system delivered by Commerce Server. They also extended the index and table of contents of the Business Desk Help system to make it easier for business managers to find the new Help topics. They made the following additions to the Bizdesk.hhc and Bizdesk.hhk files, which are installed in the Business Desk\docs folder (for example, Retailbizdesk\docs):

• Added content to Business Desk Help.

The development team decided that the Help topics should appear in the "Orders" section of the Business Desk Help system, so they added their entries after the Object entry for the Orders topics. They also decided to follow the same organizational scheme employed in the Help system, so that their topic structure would appear consistent with the Help topics delivered by Commerce Server.

The following entries are a sub-set of the values they added to the Bizdesk.hhc file:

<LI>

<OBJECT type="text/sitemap">

<param name="Name" value="Workflow for Gift Certificate Management">

<param name="Local" value="htm/cs_bd_orders_xygh.htm">

</OBJECT>

<LI>

<OBJECT type="text/sitemap">

<param name="Name" value="About Certificates">

<param name="Local" value="htm/cs_bd_orders_iaaz.htm">

</OBJECT>

….

• Added index entries for new Help topics.

To make sure that new topics are referenced in the Business Desk Help index, they added the following entries to the Bizdesk.hhk file:

<LI> <OBJECT type="text/sitemap">

   <param name="Name" value="gift certificates">

   <param name="Name" value="Certificate Workflow">

   <param name="Local" value="htm/cs_bd_orders_xygh.htm">

   </OBJECT>

<OBJECT type="text/sitemap">

   <param name="Name" value="gift certificates">

   <param name="Name" value="About">

   <param name="Local" value="htm/cs_bd_orders_iaaz.htm">

   </OBJECT>

Site Resource Modifications

The development team decided to add a new resource for system administrators to use to manage the databases in which gift certificate information is stored. They named this resource Certificates. The Certificates resource uses the Generic Properties dialog box as described in "Levels of Integration" in Commerce Server 2000 Help.

The only configuration information required for the Certificates resource is the connection string for the Certificates database. To add this resource, the development team created the SQL script CertificatesInit.sql, which they based on the SiteStatusInit.sql file included with the Commerce Server 2000 SDK. This SQL script makes the changes needed to include the Certificates resource in the Commerce Server Site Packager file (with a .pup extension) that the team used to move the finished site from the development environment to the test and production environments.

The following excerpt is from the CertificatesInit.sql script:

IF NOT EXISTS(SELECT s_ClassName FROM SystemProps WHERE
 s_ClassName = ''Certificates'' )

insert into SystemProps (s_Name, s_ClassName, s_ResourceType,
 f_ResourceFlags, f_PupFlags, s_ProgIDSnapin) VALUES
 ('''',''Certificates'',''Certficates'',6,0,''Shoesnet.CertResource'')

IF NOT EXISTS(SELECT s_PropertyName FROM ExtendedProps WHERE
 s_PropertyName = ''s_AppName'' )

insert into ExtendedProps VALUES
 (''Certificates'',''s_AppName'',0,1,0,''Contoso'',8200,'''',''s_AppName'')

Site Page Modifications

The development team consulted the marketing team to decide on the best way to position the new gift certificate feature. They consulted the site designers to see how to best present it. This consultation concluded with the following decisions:

• The team added a Gift Certificate page on which customers can purchase new gift certificates.
• The marketing team created an advertisement for gift certificates to display to registered users who had previously purchased gift certificates. This advertisement was displayed on the home page.
• The link to the new Gift Certificate page appeared on the menu that is displayed on all pages, and the advertising banner included a click-through link to the Gift Certificate page.
• The team integrated purchases made with a gift certificate into the checkout process by including an option button on the Summary page.
• Gift certificates were added to the Contoso online catalog. These items included a not-taxable property that the tax component checked to calculate the tax for orders that include gift certificates.

Checkout Pipeline Modifications

The development team decided to create a new pipeline component, called GiftCert, to reduce the billing amount on the order form when a purchase is made with a gift certificate. They added this new pipeline component to the Payment stage of the Checkout pipeline. The following table summarizes the values read and values written by the GiftCert component (three values read and one value written).

Values read	Values written
certificate_code	Billing_amount
redemption_amount
billing_amount

COM Object Development The development team identified the following requirements for a new COM object they created:

• Create a unique identifier for each new online certificate.
• Update the online and back-end databases with new balance information when a gift certificate is created or used to make a purchase.

The development team implemented the new COM object with the following attributes:

• It creates the unique identifier by first generating a globally unique identifier (GUID) and using a hashing algorithm to develop a four-digit alphanumeric code to append to the first four characters of the recipient's last name.
• It updates the back-end system asynchronously by calling a Host Integration Server connector object and passing in the sales and gift certificate information.
• It uses COM+ queuing.
• It implements the "Both" threading model and aggregates the Free Threaded Marshaller object.

Profile Modifications

The Contoso development team decided to create a new profile for the gift certificates. The gift certificate profile stores recipient identification, including the recipient's address. The profile is stored in Contoso's SQL Server database.

Report Modifications

The development team based the new dynamic reports on a SQL Server Analysis cube. The static report, Gift Certificate Buyers, is based on a SQL query. They also created a new cube named Certificates. The development team then created the Extensible Markup Language (XML) framework for the new dynamic reports, in the manner described in "Creating Dynamic Reports Using Cubes" in Commerce Server 2000 Help.

After adding the new Analysis cube and XML framework, the development team used the Analysis – New Dynamic OLAP Report.sql script provided in the SDK\Samples\Business Analytics\Scripts directory to add the report definition to their Commerce Server Data Warehouse.

The team also created the SQL script for generating the static reports, based on the example in "Creating Custom Reports" in Commerce Server 2000 Help.

Site Term Modifications

To display the Certificates advertisement to customers who previously purchased gift certificates, the development team added a new site term, called Certificate Buyer. They used the Site Terms Editor module in Business Desk to do this. The new site term has the properties listed in the following table.

Property	Values
Name	Certificate_Buyer
Display Name	Certificate Buyer
Term Names	No, Yes
Term Display Name	No, Yes

The development team mapped the new Certificate Buyer site term to one of the custom properties of the User object.

Campaign Modifications

The development team used the Campaigns modules in Business Desk to create a new advertising campaign for the gift certificates. The campaign contained a single house ad targeted to customers for whom the expression Certificate_Buyer = Yes evaluates to True. They added registered users to the Certificate_Buyer group by exporting the Gift Certificate Buyers static report to the List Manager module, and then targeting the certificates ad to this group. The click Uniform Resource Locator (URL) for this new advertisement is the Certificates page.

Deployment Summary

The Contoso development team used the tools listed in the following table to deploy and replicate the new gift certificate feature.

Feature elements	Deployment tool	Replication tool
New site pages	Site Packager	Microsoft Application Center 2000
New Business Desk modules	Site Packager	Application Center
New pipeline component	Setup program	Setup program
New database	Site Packager	SQL Server replication
New COM component	COM+ application	Application Center

After the team finished testing the new gift certificate feature, they deployed the changes in their production environment by packaging the new version of the site using Site Packager. This new package included the site pages, Business Desk modules, and site data. They created a Microsoft Windows Installer file to set up the new GiftCert pipeline component on the servers in their Web farm. Because the COM+ object is implemented as a COM+ Queued Component, they added the object to a COM+ application. This made it possible to use the Application Center Deployment Wizard to deploy the object to all of the servers in the Web farm. (For more information about using the Application Center Deployment Wizard, see Chapter 15, "Deploying Content.")

Profiling System Utilities

The profile schema for a Commerce Server site is stored and maintained in the Profiles database. By default, this database is named <SiteName>_COMMERCE when you unpack a site. A profile schema is a hierarchy made up of the following nodes:

Catalog

Business Object Profile

   Business Object Profile Attribute (to store Data Warehouse class name)

   Group

   Property

   Property Attribute

   Data Ref (to store linked Data Member name)

   Data Source

      Source Info (to store Data Source Partition settings
 such as default partition flag and connection string)

         Source Info Attribute

      Data Object

      Data Member

• Profile Definitions catalog
• Site Terms catalog

The nodes are provided by default in the Site Packager file for the Blank Solution Site. The Profile Definitions catalog stores the business object profile schemas, such as User Object, Address, and Organization, as well as the data source settings. The Site Terms catalog stores the site term definitions.

The Commerce Server 2000 Resource Kit CD contains the tools listed in the following table to help you develop profiles.

Tool	Description
Profiles Schema Mover	A compiled Microsoft Visual Basic application that enables you to define and configure the profile schema in one Commerce Server environment (such as your development environment), then migrate it to another (such as your test or production environment). You can also use this tool to change the data source connection strings for the target environment when you migrate the schema.
Site Terms Viewer	The Site Terms Viewer is a Visual Basic script that shows how to access site terms programmatically.

This section describes the architecture of these two tools and describes how to use the Profiles Schema Mover to import and export a profile schema.

Profiles Schema Mover

You use the Profiles Schema Mover tool to migrate the profile schema you configured in one Commerce Server site environment to another Commerce Server site environment.

If you create a data object or a data member through Commerce Server Manager, the specific database table/column or LDAP class/attribute is visible only to the Profiling System. You must create the necessary database tables or LDAP classes to expose them before you migrate the data objects and members.

Installation

The Profiles Schema Mover tool is a stand-alone application (.exe file), and there are no additional resource files or dynamic-link libraries (DLLs) that you need to install. To use it, copy the executable file to the server on which Commerce Server is installed.

The Profiles Schema Mover tool is written in Visual Basic and references the following type libraries:

• Microsoft Commerce 2000 Configuration Type Library
• Microsoft Commerce 2000 BizData Admin Type Library
• Microsoft XML, version 2.0
• Microsoft ActiveX Data Objects 2.5 Type Library
• Microsoft OLE DB Service Component 1.0 Type Library
• Active DS Type Library

Operation

You run the Profiles Schema Mover tool on the server on which Commerce Server is installed because it must interact directly with the run-time services and components that Commerce Server provides. You must run the Profiles Schema Mover tool in the environment in which the profile schema is located. If you want to copy the profile schema from one environment to another, you must first run the Profiles Schema Mover tool in the source environment to export the schema, and then run the tool in the destination environment to perform the import.

Figure 9.1 shows the user interface (UI) for the Profiles Schema Mover tool.

Figure 9.1 Profiles Schema dialog box (Image unavailable)

The following sections provide a detailed description of how to export and then import catalogs.

Exporting a Catalog

Clicking the Export Catalog button in the Profiles Schema dialog box shown in Figure 9.1 generates a single XML file describing the profile schema settings for the Commerce Server site selected in the Site Name box. The XML file generated follows the Commerce Server profiles XML schema format. To export a catalog, the tool does the following:

1. Obtains a list of sites.
2. Connects to the data store.
3. Obtains profile and data source names.
4. Obtains profile definitions.
5. Obtains the Site Terms catalog.
6. Saves the profile schema XML document.

Obtaining a List of Sites

The Site Name box in the Profiles Schema dialog box contains the names of sites found in the Administration database for the Commerce Server environment in which the Profiles Schema Mover tool is running. The tool obtains a list of sites by using the Commerce.GlobalConfig object to retrieve global configuration settings stored in the Administration database. The following code demonstrates how to retrieve the settings:

Dim oGlblCfg As New GlobalConfig

           Dim rsSites As New Recordset

           oGlblCfg.Initialize

           Set rsSites = oGlblCfg.Sites

           For Each Site In rsSites.Fields

                   SitesList.AddItem Site.Name

           Next      

The tool uses the Commerce.SiteConfigReadOnly object to access the site configuration settings for the selected site. It calls the Initialize method of the Commerce.SiteConfigReadOnly object to load the configuration settings for the site and site resources from the Administration database and return them in the Fields property of the SiteConfigReadOnly object instance.

The tool then reads this property and retrieves the connection string from the Profiles data store (defined in the _BizDataStoreConnectionString property of the Profiles global resource in Commerce Server Manager).

Using the Commerce.BusinessDataAdmin object to modify the profile schema is not supported; at this time the only supported approach for modifying the profile schema is to use the Profile Designer UI in either Commerce Server Manager or in Business Desk. The UI enforces the appropriate validation rules during the creation and modification of a profile schema. If you bypass these validation rules by using the Commerce.BusinessDataAdmin object, your profile schema may be corrupted, preventing your site's Profiling System from working properly.

Connecting to the Data Store

After the Profiles Schema Mover has obtained a connection string to the Profiles data store, it calls the Connect method for the Commerce.BusinessDataAdmin object, passing in the connection string to establish a connection to the data store. The following code demonstrates how to connect to the data store:

Public Function LoadBDAO(sSiteName As String) As BusinessDataAdmin

  Dim objSiteCFG As New SiteConfigReadOnly

  Dim objBDAO As New BusinessDataAdmin

  Dim sDSN As String

  objSiteCFG.Initialize gSiteName

  sDSN = objSiteCFG.Fields("Biz Data_   Service").Value.Fields_
  ("s_BizDataStoreConnectionString").Value_

                            objBDAO.Connect sDSN

  Set LoadBDAO = objBDAO

End Function

The Commerce.BusinessDataAdmin object interface exposes and describes the internal structure of the profile schema in XML format. The Microsoft Extensible Markup Language (MSXML) version 2.0 parser handles the XML Document Object Model (DOM) manipulation, though this can be changed to use the later version of the MSXML parser.

Obtaining Profile and Data Source Names

To export a profile schema from its data source, the Profiles Schema Mover tool first calls the GetCatalog method for the Commerce.BusinessDataAdmin object. This method returns an XML DOM object that contains a list of catalogs, as well as a list of business object profiles and data sources belonging to each of the catalogs, as defined in the following profile schema for the site:

Set objBDAO = LoadBDAO(gSiteName)

Set CatalogsDoc = objBDAO.GetCatalogs

For example, if you use the Profile Schema Mover tool to export a schema for the Retail Solution Site, the following XML would be returned:

<Document xmlns="urn:schemas-microsoft-com:bizdata-profile-schema">

    <Catalog name="Profile Definitions" displayName="Profile Catalog" 
    description="Profile Definitions">

       <Profile name="Address" displayName="Address" description="Addresses"/>

       <Profile name="BlanketPOs" displayName="BlanketPOs" description="Blanket Purchase Orders"/>

       <Profile name="Organization" displayName="Organization" description="Organization Object"/>

       <Profile name="UserObject" displayName="User Object" description="User Object"/>

       <Profile name="TargetingContext" displayName="Targeting
 Context" description="CSF Targeting Context"/>

       <DataSource name="UPM_SQLSource" displayName="ProfileService_SQLSource" description=
"Source" sourceType="OLEDB-ANSI"/>

    </Catalog>

    <Catalog name="Site Terms" displayName="Site Terms">

       <Profile name="MSCommerce" displayName="Site Terms" description="Site Terms for 
Microsoft Commerce Server" isProfile="0"/>

    </Catalog>

</Document>

Obtaining Profile Definitions

The GetCatalog method returns only the Catalog node and its immediate child nodes, Profile and DataSource. To generate an XML document representing the entire definition of the profile schema, the tools adds the remaining child nodes (such as Group, Property, Attribute, Data Object, and Data Member) to the XML document. To do this, the Profiles Schema Mover tool iterates through each Profile node and retrieves all of its child nodes as well as the elements beneath the child nodes.

The tool obtains an XML DOM object representing each individual Profile node and its child nodes by calling the GetProfile method for the Commerce.BusinessDataAdmin object, passing in the Profile name. The profile is passed in the <Catalog Name>.<Profile Name> format (for example, Profile Definitions.Address). After a complete structure is obtained, the tool replaces each Profile node represented as <Profile … /> in the XML DOM document obtained by the BDAO.GetCatalog method, as follows:

<Profile …>

   <Attribute …/>

   <Group …>

           <Property …>

                   <DataRef …/>

                   …

                   <Attribute …/>

<Attribute …/>

                   …

           </Property>

           <Property …>

                   …

           </Property>

   </Group>

   <Group …>

           …

   </Group>

</Profile>

The Profiles Schema Mover tool performs the same operation on each DataSource node in the Profile Definitions catalog.

Obtaining the Site Terms Catalog

After the Profiles Schema Mover tool has obtained the catalog for each data source, it must process the Site Terms catalog to carry out the same operation on its Profile nodes. It uses the following code to do this:

' Process each catalog

Set Catalogs = CatalogsDoc.selectNodes("//Catalog")

  For Each Catalog In Catalogs    

  ' Get the catalog name

    CatalogName = Catalog.getAttribute("name")

  ' Get each profile and add it to the XML document

    sProfileXSL = "//Catalog[@name='" & CatalogName & "']/Profile"

    Set Profiles = CatalogsDoc.selectNodes(sProfileXSL)

      For Each Profile In Profiles

         ProfileName = CatalogName & "." & Profile.getAttribute("name")

           Set ProfileDoc = objBDAO.GetProfile(CStr(ProfileName))

           Set ProfileNode = ProfileDoc.selectSingleNode("//Profile")

           Set NewChild = Catalog.replaceChild(ProfileNode, Profile)

      Next

  ' Get each data source and add it to the XML document

    sDataSourceXSL = "//Catalog[@name='" & CatalogName & "']/DataSource"

    Set Datasources = CatalogsDoc.selectNodes(sDataSourceXSL)

      For Each DataSource In Datasources

        DataSourceName = CatalogName & "." _

        & DataSource.getAttribute("name")

        Set DataSourceDoc = objBDAO.GetDataSource(CStr(DataSourceName))

        Set DataSourceNode =   DataSourceDoc.selectSingleNode("//DataSource")

        Set NewChild = Catalog.replaceChild(DataSourceNode, DataSource)

      Next

  Next

Saving the Profile Schema XML Document

Finally, the Profiles Schema Mover tool calls the CatalogsDoc.Save method to save the profile schema XML document.

For this reason, the ExportCatalog method includes the primary partition setting for the site data source, but leaves out the settings for any other partitions from the profiles XML schema it generates. The Profiles Schema Mover tool implements its own logic (described in the previous "Obtaining the Site Terms Catalog" topic) to include the settings for all data source partitions and to export the complete "picture" of the site profile catalog in the generated profiles XML schema.

Importing a Catalog

When you click the Import Catalog button in the Profiles Schema dialog box shown previously in Figure 9.1, the selected profile schema settings for the Commerce Server site selected in the Site Name box are loaded. To import catalog code, the Profiles SchemaMover tool:

1. Loads and validates the XML document.
2. Selects a data source for the import.

Loading and Validating the XML Document

The Profiles Schema Mover tool parses the content of the selected file and loads it into the XML DOM object for processing. If the file loads properly, the tool next verifies that the loaded XML document is correctly formatted, by ensuring that the namespace Uniform Resource Identifier (URI) element of the loaded XML document is set to the following address: urn:scheams-microsoft-com:bizdata-profile-schema.

Before initiating the import process, you can use the Profiles Schema Mover tool to change the data source connection strings specified in the import profiles XML schema to match the configuration settings used in the target site environment. A data source connection string is specified in the connStr attribute of the SourceInfo element in the import profiles XML schema. In the partitioned data source environment, the SourceInfo element is created for each partition. The connection string attribute is also specified for each partition.

For example, you could represent the import profiles XML schema for a site with two SQL data sources and two partitions created on the first SQL data source, as follows:

<DataSource name="UPM_SQLSource" displayName="ProfileService_SQLSource" description="Source"
 sourceType="OLEDB-ANSI">

<SourceInfo name="SQLSource_Partition1" isDefault="1"
 connStr="Provider=SQLOLEDB; Data Source=CSITS;Initial Catalog=RETAIL_COMMERCE;User
 ID=SA;Password=;Extended Properties=;Network Library=DBMSSOCN" />

<SourceInfo name="UPM_SQLSource_Partition2" 
 connStr="Provider=SQLOLEDB.1;Password="";Persist Security Info=True;User 
 ID=SA;Initial Catalog=RETAIL_COMMERCE2;Data Source=CSITS">

  <Attribute name="Username" displayName="" /> 

           <Attribute name="Password" displayName="" /> 

</SourceInfo>

…

</DataSource>

  <DataSource name="UPM_SQLSource2"   displayName="ProfileService_SQLSource2" sourceType="OLEDB-ANSI">

…

</DataSource>

Selecting a Data Source for the Import

The Profiles Schema Mover tool iterates through each DataSource node in the import profiles XML schema, reads the connection string attribute (connStr) of each partition element under the DataSource node (SourceInfo), and then displays the results. Figure 9.2 shows how the Profiles Schema Mover tool displays the data sources.

Figure 9.2 Import Profiles Schema dialog box (Image unavailable)

You can select a specific data source partition in the tree view control to display the connection string currently specified in the import profiles XML schema. Click the Edit button to open a dialog box in which you can edit the connection string for the selected data source partition.

The Profiles Schema Mover tool determines the appropriate dialog box to display, based on the type of data source (OLEDB-ANSI SQL source or LDAP directory) you select. The following code sample illustrates how the tool determines which dialog box to display:

Dim oDataLinks As DataLinks, oConn As ADODB.Connection

Dim SourceInfo As IXMLDOMElement, Source As IXMLDOMElement

…

Set SourceInfo = gXMLDoc.selectSingleNode("//DataSource[@name='" &   
 sSourceName & "']/SourceInfo[@name='" & sSourceInfoName & "']")

  If Not SourceInfo Is Nothing Then

    sConnStr = SourceInfo.getAttribute("connStr")

    Set Source = SourceInfo.parentNode

    sSourceType = Source.getAttribute("sourceType")

      If StrComp("OLEDB-ANSI", sSourceType, vbTextCompare) = 0 Then

        Set oDataLinks = New DataLinks

        Set oConn = New ADODB.Connection

        oConn.ConnectionString = sConnStr

        oConn.Properties.Item("Persist Security Info").Value = True

        oDataLinks.hWnd = Me.hWnd

       'PROMPTAGAIN:

        If oDataLinks.PromptEdit(oConn) Then

           oConn.Properties.Item("Persist Security Info").Value = True

           sConnStr = oConn.ConnectionString

             If InStr(1,sConnStr,"Integrated Security", vbTextCompare) > 0 _             Then

              MsgBox "Windows NT Integrated security is not supported._ You_must use SQL
 Server authentication.  Use a specific_  user name and password.", vbCritical,
 "Profile schema"

               'GoTo PROMPTAGAIN:

            End If

          SourceInfo.setAttribute "connStr", sConnStr

         End If     

        ElseIf StrComp("LDAPv3", sSourceType, vbTextCompare) = 0 Then

         Set gXMLNode = SourceInfo DlgLDAP.Show 1, Me

        End If

      End If

  End If

After you have adjusted the data source connection strings in the import profiles XML schema to match the target Commerce Server site environment, you click the Import button in the Import Profiles Schema dialog box (Figure 9.2) to begin the import.

Once again, a programmatic manipulation of the site profile schema is done using the Commerce.BusinessDataAdmin object, and its ImportCatalog method is made available to update the profile schema by importing the XML document, as shown in the following code:

Dim objBDAO As New BusinessDataAdmin

…

Set objBDAO = LoadBDAO(gSiteName)

objBDAO.ImportCatalog gXMLFileName

Deployment Scenarios

The scenarios in this section describe how to migrate a profile schema from one site to another. Note that the term Commerce Server environment denotes one instance of Microsoft Windows 2000 Server on which Commerce Server is installed.

Migration Across Multiple Commerce Server Environments

In this scenario, two Commerce Server sites (Site A and Site B) are installed in two different Commerce Server environments. The Profiles Schema Mover tool is used to migrate the profile schema from Site A into the Profiles data source of Site B. The tool is installed in both Commerce Server environments. The installation in the environment of Site A is used to generate the profile XML schema file, and the installation in the environment of Site B is used to import the XML file into the Profiles data store of Site B. Figure 9.3 shows an example of migration across multiple Commerce Server environments.

Figure 9.3 Migration across multiple Commerce Server environments (Image unavailable)

This scenario represents a project environment in which a site's profile schema is maintained in the development environment and any schema changes made in the development environment are then migrated to the other environments, such as the test environment, staging environment, and production environment.

The Profiles Schema Mover tool is especially useful if you make a large number of changes to the profile schema, because it eliminates the time you would otherwise have to spend applying the same changes manually in the different environments, using Commerce Server Manager or Business Desk. The Profiles Schema Mover tool enables you to generate a single XML file that represents the entire profiles schema of the site, and then migrate the changes to multiple environments, without errors, by simply importing a XML file.

Migration Within a Single Commerce Server Environment

In this scenario, both Site A and Site B are installed in a single Commerce Server environment, thus sharing the same Administration database. This scenario is possible because each individual site in the Commerce Server environment has its own Profiles data store. Changing the profile schema for Site A does not impact the profile schema for Site B. In the Administration database, the global configuration data is maintained once and shared by both sites, but site configuration data, such as the connection string for the Profiles data store, is maintained separately for each site. Figure 9.4 shows migration within a single Commerce Server environment.

Figure 9.4 Migration within a single Commerce Server environment (Image unavailable)

Site Terms Viewer

The second tool provided in the Profiles Schema Manager directory of the Commerce Server 2000 Resource Kit CD is the Site Terms Viewer script. This script illustrates how you can programmatically access a site's profile schema and display a list of all site terms and their values at the command line.

The implementation of this script is relatively simple. The script reads a site name as an argument from the command line prompt. It then uses the SiteConfigReadOnly object to retrieve the connection string for the site's Profiles data source from the Administration database, and establishes a connection through the Commerce.BusinessDataAdmin object, as follows:

' Get the BDAO connection string

Set SiteCFG = CreateObject("Commerce.SiteConfigReadOnly")

SiteCFG.Initialize SiteName

ConnStr = SiteCFG.Fields("Biz Data _ Service").Value.Fields("s_BizDataStoreConnectionString").Value

' Create Biz Data Admin Object

Set BDAO = CreateObject("Commerce.BusinessDataAdmin")

BDAO.Connect ConnStr

The site terms settings are all stored in the Site Terms catalog node within the profile schema, and the Commerce.BusinessDataAdmin object accesses these settings using XML. By default, the Site Terms catalog contains one Profile node named MSCommerce, and each individual site term is defined as a single Property node under this Profile node. The values for each site term are then defined as attributes belonging to the corresponding Property node. Using the Retail Solution Site as an example, the Site Terms schema is represented as the following XML:

<Catalog name="Site Terms" displayName="Site Terms">

  <Profile name="MSCommerce" displayName="Site Terms"
 description="Site_   Terms for Microsoft Commerce Server"
 isProfile="0">

     <Group name="UserSiteTerms" displayName="User Site Terms">

     <Property name="AccountStatus" displayName="Account Status"_
description="Account Class" propType="STRING" isDefaultNull="0"_
isExported="1" isRequired="1" isSearchable="1">

       <Attribute name="1" displayName="Active Account"_
description="Active"_/> 

       <Attribute name="0" displayName="Inactive Account"_
description="Inactive" /> 

     </Property>

     <Property name="UserRole" displayName="User Role"
 description="User_ Role" propType="STRING" isDefaultNull="0"
 isExported="1"_ isRequired="1" isSearchable="1">

… 

           </Property>

…

           </Group>

       <Group name="CalendarSiteTerms" displayName="Calendar Site Terms">

                   …

                   </Group>

  </Profile>

</Catalog>

Using the Commerce.BusinessDataAdmin object, the Site Terms Viewer script retrieves the MSCommerce profile XML schema from the Site Terms catalog. Then the script iterates through each site term defined in the Property node of this profile, and displays each site term value defined in the Attribute node of each property, as shown in the following code:

' Get the Site Terms Catalog

Set SiteTermsXML = BDAO.GetProfile("Site Terms.MSCommerce")

' Get a list of the site terms and display them

Set Terms = SiteTermsXML.SelectNodes("//Property")

For Each Term in Terms

   wscript.echo Term.GetAttribute("displayName")

   Set Values = Term.SelectNodes("Attribute")

   For Each Value in Values

           wscript.echo "    " & Value.GetAttribute("displayName")

   Next

Next 

To run the Site Terms Viewer script, use the Cscript command from the command line. The syntax for running the script is as follows:

cscript "<directory path>\SiteTerms.vbs" "<Site Name>"

cscript "C:\SiteTerms.vbs" "Retail"

Profiling System: Operational Considerations

This section describes the choices and caveats developers need to consider before they design and effectively use the Commerce Server Profiling System. It describes the following:

• Profile definition keys
• Design considerations
• Run-time considerations
• Ways to manage pre-existing accounts in Microsoft Active Directory stores
• User profile import Data Transformation Services (DTS) tasks

Profile Definition Keys

You must define one or more keys for every valid profile definition. You can identify unique, primary, join, and hashing keys by examining the Key type property in the Advanced Attributes section in the Profile Designer module of Business Desk or in the profile definition of the Profiles resource in Commerce Server Manager. This section describes how to define the following keys:

• Unique key
• Primary key
• Join key
• Hashing key

Unique Key

Every profile definition property marked as a key has the Unique Key attribute turned on. Only properties of string or numeric data types can be marked as keys. A profile definition can have any number of keys, although from a performance and memory perspective, it is better to have as few keys as possible.

All core profile object management operations in the Profiling System (CreateProfile, GetProfile, GetProfileByKey, DeleteProfile, DeleteProfileByKey) work with key members only. The Profiling System does not guarantee the uniqueness of properties that are marked as unique keys. Instead, it relies on constraints on objects in the underlying data stores (tables for relational databases or classes for directory stores) to implicitly enforce uniqueness.

Primary Key

Every profile definition must have exactly one unique key property marked as a primary key. You should mark the profile property most commonly used to operate on profile object instances as the primary key.

A primary key is identified by a red "P" or a green "D" (for a dual primary and join key) that precedes the property in the Profile Designer module of Business Desk or in the profile definition of the Profiles resource in Commerce Server Manager.

Join Key

Every profile definition must have exactly one unique key property marked as a join key. For optimal performance, you should also mark the primary key on the profile definition as the join key. If you don't provide a value for the join key property when you create the profile object, then the Profiling System automatically generates a value for this member.

A join key is identified by either a blue "J" or a green "D" (for a dual primary and join key) that precedes the property in the Profile Designer module of Business Desk or in the profile definition of the Profiles resource in Commerce Server Manager. The Profiling System uses the join key property to assemble profile object fragments stored in multiple data stores. Join key property values are replicated across all data stores.

Hashing Key

Every profile definition can have one unique key property marked as the hashing key. The profile aggregation layer uses the hashing key property to hash a profile object to a unique partition within a data source. The presence of a hashing key property is the only way to indicate that instances of a profile definition will be stored across multiple partitions of a data source. The absence of this property results in all profile instances being stored in the default partition.

You should mark the join key on the profile definition as the hashing key. For optimal performance, you should mark the same property as the primary key, the join key, and the hashing key.

You can identify a hashing key by examining the Advanced Attributes/Hashing key in the Profile Designer module of Business Desk or in the profile definition of the Profiles resource in Commerce Server Manager.

Figure 9.5 displays the Key type drop-down box and the Hashing key check box.

Figure 9.5 Profile definition keys (Image unavailable)

Profiling System Design Considerations

This section describes the following considerations for designing effective profile definitions:

• Keys
• Recommended data type mappings
• Other considerations

Keys

Choosing the appropriate key members can help you maximize the performance of the Profiling System. To effectively define keys in the profile definition, answer the following questions, and then use the table to find the corresponding guideline.

• Question 1. Should the primary key property be updateable after the object has been committed to the underlying stores?
• Question 2. Should the data be partitioned within a data source?

Guideline	Question 1	Question 2
Use the same property as the primary key and the join key.	No	No
Use the same property as the primary key, the join key, and the hashing key. This configuration maximizes the performance of Profiling System operations in partitioned scenarios.	No	Yes
Do not use the same property as the primary key and the join key.	Yes	No
Do not use the same property as the primary key and the join key. However, use the same property as the join key and the hashing key. This configuration provides sub-optimal performance for profile object operations based on a non-hashing (or non-join) key property.	Yes	Yes

Recommended Data Type Mappings

The following tables list the recommended mappings between Profiling System data types and the data types supported by SQL Server, Oracle, Active Directory, and Membership Directory.

ANSI SQL Stores

Profiling System data type	SQL Server data type	Oracle data type
BOOL	smallint	number
NUMBER	in t	number
FLOAT	float	number
STRING/PROFILE/PASSWORD/ SITETERM	nvarchar	nvarchar2
CURRENCY	money	number
DATETIME/DATE/TIME	datetime	date
BINARY	varbinary	raw
LONGTEXT	ntext	nclob
IMAGE	image	blob

LDAP-v3 Stores

Profiling System data type	Active Directory data type	Membership Directory data type
BOOL	boolean	integer
NUMBER	integer	integer
STRING/PROFILE/ PASSWORD/SITETERM	string (Unicode)	UnicodeString
CURRENCY	LargeInteger	integer
DATETIME	string (GeneralizedTime)	generalizedTime
BINARY	string (Octet)	binary
LONGTEXT	string (Unicode)	UnicodeString
IMAGE	string (Octet)	binary

The following table describes other items you should consider to define effective profile definitions.

Design consideration	Description
Restrictions on WHERE clauses	OLE DB Provider for Commerce Server requires that all properties in the WHERE clauses of queries passed to it map to the same underlying store. This restriction becomes important when you design profile definitions that aggregate data across multiple data objects.
Non-encrypted storage	The Profiling System does not store any properties in encrypted format in the underlying data stores. If you want to restrict access to data, you must consider storing sensitive data in secure data stores such as Active Directory.
Data size limitations	For a detailed description of each of the data types exposed by the Profiling System, see "Profile Definition Components," located in the following path "Administering Commerce Server/Running the Profiles Resource/About the Profiles Resource/Profile Definitions/" in Commerce Server 2000 Help.
Valid characters in object names	Profile definition object names such as ProfileDefinitionName, ProfilePropertyName, and so on, can contain only alphanumeric characters and the underscore (_) character.

Profiling System Run-Time Considerations

This section describes the following Profiling System run-time considerations:

• CSOLEDB handles
• Accessing properties
• Transaction support
• Data size validation

CSOLEDB Handles

You must always store handles to the Profiling System and OLE DB Provider for Commerce Server at application scope. You should do this because the CSOLEDB handles were designed so that they create an object once in the Global.asa file, store the object at application scope, and then use the object on every ASP page. The CSOLEDB handles coordinate the concurrency issues that arise from processing multiple queries simultaneously. They also manage the fault-tolerance of connections to underlying stores for reliable query processing.

Accessing Properties

The Profiling System provides a number of mechanisms to access profile object properties. For example, the following are different ways of accessing the GeneralInfo.user_id property of a ProfileObject object named oUser:

• Access using standard Microsoft ActiveX Data Objects (ADO) notation:

oUser.Fields.Item("GeneralInfo").Value.Item("user_id").Value

oUser.Fields("GeneralInfo").Value("user_id").Value

• Access using extended dot notation:

oUser.Fields("GeneralInfo.user_id"

• Access using smart dispatch notation:

oUser.GeneralInfo.user_id

The performance difference between these options is insignificant.

Transaction Support

The Profiling System, by default, does not transact write operations across multiple data stores. More specifically, it does not support executing a two-phase commit protocol across transactional data stores.

The Profiling System provides loose support for transactions. The data aggregation layer brackets INSERT, UPDATE and DELETE data store operations that aggregate across multiple stores in a transaction, and commits them only after all data store operations have succeeded against non-transactional data stores (such as directory stores).

You can enable loose support by creating a custom attribute named IsTransactioned in the profile definition and setting it to "True." If this attribute is absent or you set it to "False," this feature is disabled.

Figure 9.6 shows the IsTransactioned custom attribute being added to the UserObject profile in the profile definition of the Profiles resource in Commerce Server Manager.

Figure 9.6 IsTransacted custom attribute (Image unavailable)

Data Size Validation

The Profiling System does not perform any data size validations, and depends on the underlying data stores to perform the validation.

Managing Pre-Existing Accounts in Active Directory Stores

To leverage pre-existing accounts in Active Directory, you must configure the search container and search scope of Active Directory data sources appropriately. Configuring the search container and search scope correctly enables the Profiling System to find the pre-existing accounts for directory operations such as object creation and object retrieval. At the beginning of every search operation, the Profiling System determines the starting container for the search operation and whether it should perform a one-level search or a sub-tree search.

This section describes the following:

• Starting container for directory operations
• Search scope

Starting Container for Directory Operations

The Profiling System provides three levels of support for defining the starting search container:

• ParentDN
• DefaultParentURL
• Parent URL

These levels are arranged in a hierarchy that determines the precedence for searching. The following three topics are arranged according to this hierarchy.

ParentDN

The ParentDN property is optionally added to the profile definition to specify the distinguished name (DN) of the starting search container. If used, this property allows the container to be specified for an individual profile and overrides the settings for the DefaultParentURL and Parent URL attributes. Specifying this property provides the most granular level of control.

DefaultParentURL

The DefaultParentURL attribute is added as a custom attribute to the profile definition, as shown in the following figure. The value of this attribute is relative to the defaultNamingContext custom attribute specified for the data source. This value is used as the starting search container for all profiles (of this definition type) that do not have a different value specified in a ParentDN property. This attribute overrides the Parent URL attribute. Figure 9.7 shows the DefaultParentURL attribute being added to the UserObject profile.

Figure 9.7 DefaultURL custom attribute (Image unavailable)

Parent URL

You can configure the Parent URL attribute through the System Attributes tab in the Properties dialog box for the LDAP data source that is using the Profiles resource of Commerce Server Manager. The value of this attribute is the DN of the starting search container. Figure 9.8 shows the Parent URL attribute being added.

Figure 9.8 Parent URL and default search scope (Image unavailable)

As an example, assume that existing accounts are stored in the CN=Users,DC=testDomain,DC=com directory path. One way to direct the Profiling System to read accounts from this container is to set the Parent URL attribute of the Active Directory data source to CN=Users,DC=testDomain,DC=com. The Profiling System will perform all subsequent directory operations against this container unless overridden by the DefaultParentURL attribute or the ParentDN property.

Search Scope

The search scope depends on whether the client operation is a bulk operation (invoking a SELECT query against an OLE DB Provider) or a single-instance operation (invoking the GetProfile method of the ProfileService object). Bulk operations always set the search scope to sub-tree (sub-directories of the specified Parent URL attribute are also searched). Single instance operations default to one-level search scope (sub-directories are not searched). You can configure the client operation as sub-tree search scope using the Profiles resource of Commerce Server Manager, as shown in the preceding figure.

User Profile Import DTS Task

The User profile data import DTS task imports profile data into the Data Warehouse. By default, this DTS task imports only the Address and UserObject profiles.

Importing New Profile Types

To import other profiles supplied by Commerce Server, or new custom profiles, use the Profiles resource in Commerce Server Manager to add the custom attribute, DWClassName, to the profile definition. The value of the DWClassName attribute is the name of the class in the Data Warehouse where the profile data will be imported. A property named date_last_changed must also be defined for the profile if it will be imported.

To specify the data members of a profile to be imported, use the Profile Designer module in Business Desk to select the Exported check box in the Advanced Attributes section for each property to be imported. By default, the property is imported into a data member of the same name. To specify a different data member in the Data Warehouse class, add the attribute, DWMemberName, to the property in the Custom Attributes section of the Profile Designer module.

When you create a new profile type, you must also create a source table with matching properties, in addition to specifying the profile data source and the profile definition. You do not have to explicitly create the destination class and data members in the Data Warehouse. When the User profile data import DTS task is run, it automatically creates these, if they do not already exist, based on the two custom attributes specified earlier.

Profile Mappings

The following tables list the source to destination mappings for the Address and UserObject profiles.

Address Profile

Address profiles are stored in the Addresses table in the Commerce Server database. By default, the Addresses table (source) is mapped to the Address class (destination) in the Data Warehouse.

Source column	Source data type	Destination column	Destination data type
g_address_id	nvarchar (510)	Id	uniqueidentifier (16)
i_address_type	int (4)	AddressType	int (4)
u_address_name	nvarchar (510)	AddressName	varchar (255)
u_city	nvarchar (510)	City	varchar (255)
u_country_code	nvarchar (510)	CountryCode	varchar (255)
u_country_name	nvarchar (510)	CountryName	varchar (255)
u_first_name	nvarchar (510)	FirstName	varchar (255)
u_last_name	nvarchar (510)	LastName	varchar (255)
u_postal_code	nvarchar (510)	PostalCode	varchar (255)
u_region_code	nvarchar (510)	RegionCode	varchar (255)
u_region_name	nvarchar (510)	RegionName	varchar (255)
u_tel_extension	nvarchar (510)	TelephoneExtension	varchar (255)
u_tel_number	nvarchar (510)	TelephoneNumber	varchar (255)
d_date_created	datetime (8)	DateCreated	datetime (8)
d_date_last_changed	datetime (8)	DateLastChanged	datetime (8)

UserObject Profile

UserObject profiles are stored in the UserObject table in the Commerce Server database. By default, the UserObject table (source) is mapped to the RegisteredUser class (destination) in the Data Warehouse.

Source column	Source data type	Destination column	Destination data type
g_user_id	nvarchar (510)	UserId	varchar (255)
i_user_type	int (4)	UserType	int (4)
u_first_name	nvarchar (510)	FirstName	varchar (255)
u_last_name	nvarchar (510)	LastName	varchar (255)
u_email_address	nvarchar (510)	Email	varchar (255)
u_tel_number	nvarchar (510)	TelephoneNumber	varchar (255)
d_date_registered	datetime (8)	DateRegistered	datetime (8)
i_account_status	int (4)	AccountStatus	int (4)
d_date_created	datetime (8)	DateCreated	datetime (8)
d_date_last_changed	datetime (8)	DateLastChanged	datetime (8)

Advertising Scoring and Selection

Advertising Scoring and Selection The advertising selection engine in Commerce Server uses the Content Selection Framework (CSF). At the center of the framework are pipeline objects that describe a linear ordering of stages and components used in content selection: loading, filtering, initial scoring, scoring, selecting, recording, and formatting. This section focuses on the scoring and selection stages of the Advertising pipeline, which is included with the Commerce Server Solution Sites.

Commerce Server supports the delivery of two main types of advertisements: house ads and paid ads. The key difference between these ads is that paid ads are goaled-–that is, a certain number of impressions, clicks, or other events must be served within a given time period. A house ad, on the other hand, is assigned a weight that controls how frequently it should be delivered relative to all other house ads active in the system. Paid ads take priority and are served until they begin to run ahead of their goals, at which time house ads are also served. You can determine how paid ads are selected by adjusting their goals, while house ads are selected based on the probabilities and random number generation that determine their weight. You target both paid ads and house ads to site users in the same ways.

Campaign Goals and Item Goals

When you create an advertising campaign in Business Desk, you must specify whether the advertisements should be goaled at the advertisement item level or at the campaign level (campaign-goaled is the default). With campaign goaling, you must specify the total number of events (impressions, clicks, or other events, such as downloads) to serve across all advertising items in the campaign. Then for each advertising item, you specify a weight. The weight is considered relative to the weights of all other advertising items in the campaign. The total number of events scheduled for the campaign is distributed to the advertising campaign items in the campaign based on their weights, and each item then runs using those goals. In contrast, for item-goaled campaigns, you specify the number of events scheduled for each ad item in the campaign independently.

For example, if Contoso, Ltd. created a campaign to show advertisements for a brand of shoes, this campaign might have a goal of displaying 1,000 advertisements over a two-week period. If the campaign were made up of 10 different advertisements, all 10 advertisements would be displayed 100 times each during the two weeks. Contoso could also set a goal for each advertisement to be displayed 100 times during the two-week period. The first example is campaign-goaled, while the second is item-goaled.

You can change the way a campaign is goaled at any time. If you turn an item-goaled campaign into a campaign-goaled campaign, the number of events scheduled for each ad is used to derive the item weights and vice-versa.

Initial Scoring

Advertisements that have passed through the filter stage of the Advertising pipeline require scores to be assigned. Scoring is actually split into two pipeline stages, one to assign the initial score to each advertisement, and one to augment those scores by applying multipliers (targeting).

For house ads, the initial score for each ad is simply the assigned weight for the house ad. The weight for each ad is relative to the weights of all the other house ads. For example, if there are three house ads in the system, two with a weight of 1 and one with a weight of 2, then all else being equal, the first two ads will have a 25 percent chance of being served and the second ad will have a 50 percent chance of being served. Of course, targeting may change the scores before the selection stage is reached, thus altering the probabilities.

Paid ads are assigned an initial score based on how the ad is performing against its goals. The goal is the number of events (impressions, clicks, sold events, or others) that should be served in a given amount of time. This calculation is referred to as Need of Delivery (NOD). The basic formula for this calculation is:

Need of Delivery = (Events Scheduled / Time Periods Total)/

             (Events Served / Time Periods Elapsed)

Need of Delivery represents the ratio of the scheduled delivery rate (average events / sec over the entire run) compared to the actual delivery rate observed so far. A Need of Delivery score greater than 1.0 means the ad is running behind schedule, while a score less than 1.0 means the ad is ahead of schedule. Because all ads are scored using this same formula, the result is a fair distribution in the overall delivery of paid ads. If the ad inventory is oversold (that is, more events are scheduled during a given period than can actually be delivered), then all the ads should under-deliver on their goals proportionally.

Notice that this formula is undefined when no time periods have yet elapsed or when no events have yet been served. You can avoid the first situation by assuming one time period has already elapsed even though it hasn't, as the CSFNeedOfDelivery component uses seconds as the time period. To avoid the second situation, when no events have yet been served, you should set the Need of Delivery to a very large number (such as one million) to force an initial delivery event. After that first event has been served, the ad will subsequently be scored using the formula.

The NeedOfDelivery component is also responsible for ensuring that the ad is currently active. That is, if the ad has time of day or day of week schedule restrictions, then it is scored to zero if it is currently outside of those times.

If a Content Selection pipeline does not have any component in the initial scoring stage, then each advertisement is assigned an initial score of 1.0.

Scoring (Targeting)

Scoring in a Content Selection pipeline means applying multipliers to the ad item scores. A multiplier greater than 1.0 will increase the likelihood of the ad being selected, while a multiplier less than 1.0 will decrease it. You can disqualify an advertisement entirely by applying a multiplier of zero. The scoring components in a standard Advertising pipeline are the CSFEValTargetGroups and CSFHistoryPenalty components.

A target group is a collection of expression-action pairs. With the exception of the Sponsor action, each action corresponds to a pair of multipliers. One multiplier is applied if the expression evaluates to True, and the other is applied if the expression evaluates to False. The default multipliers are listed in the following table.

Action	Multiplier
Target	True 1.2 False 1.0
Require	True 1.0 False 0.0
Exclude	True 0.0 False 1.0
Sponsor	True 1.0 (exclusive) False 0.0 (not configurable)

The Require and Exclude actions are filters that disqualify an ad if the filter isn't met. The Target action, on the other hand, is fuzzier. It will increase the advertisement's score if the expression evaluates to True, but will not affect the score if it evaluates to False. You can change any of these multipliers (with the exception of the Sponsor action) in the Pipeline Editor module using the property page of the EvalTargetGroups component. For example, you might want to change the Target action so that it decreases the score of advertisements for which a targeted expression result is False by using a multiplier such as 0.85.

The Sponsor action is a little different. Sponsorships are used to give an ad or set of ads exclusive access to the target. If for any given ad request one or more ads have a sponsorship expression that evaluates to True, then only those ads that have a sponsorship expression that evaluates to True will be eligible for selection on that request. Sponsorships are common in the advertising industry. An advertiser may pay a premium to sponsor your site's home page, for example, and the ads for that advertiser should be the only ones eligible for selection on that page.

If more than one target group is associated with an advertisement, then the target group that evaluates to the largest multiplier is the one that is actually applied. You can think of this as a logical "Or" operation on the target groups (target group one .OR. target group two .OR. target group three, and so on). An important consideration to keep in mind is that Require and Exclude actions apply only to the target group(s) they appear in and will not prevent the ad from being displayed if the ad is also targeted using other target groups that evaluate to a non-zero multiplier. However, when any sponsorship expression result is True, then all ads and target groups without a sponsorship expression are automatically scored to zero.

The CSFHistoryPenalty component assigns a penalty to ads that have recently been selected for the current user in order to avoid "banner-burnout." The more recently an advertisement has been selected, the greater the penalty. You can specify the number of recent ads to be penalized and the range of penalties to apply using the property page of the CSFHistoryPenalty component.

The CSFHistoryPenalty component also enforces exposure limits. An exposure limit is the maximum number of times an advertisement can be shown to a given user. Whether this is a session limit or a persistent user limit depends on how you store the history string.

To use the CSFHistoryPenalty component, you must ensure that the CSFLoadHistory, CSFRecordHistory, and CSFSaveHistory components are also in the pipeline and configured appropriately. CSFLoadHistory and CSFSaveHistory allow you to select a means of storing the user history. This history is stored in a string that contains a comma-delimited list of the advertisement IDs of ads already displayed to the user (oldest first). The maximum length of the history string (in ad IDs) can be specified on the property page of the CSFRecordHistory component. If you want this history string to be persisted across user sessions, you should configure CSFLoadHistory and CSFSaveHistory to use the UserProfile option. If session history strings meet your requirements, you can use either the HTTP Cookie or ASP Session options, as appropriate. A final option is to create a custom implementation of persisting the history strings and to remove the CSFLoadHistory and CSFSaveHistory components from the pipeline.

Selection

After the initial scoring and targeting is complete, the selection stage of the Advertising pipeline is reached and the CSFSelectWinners component is run to pick the winning ad or ads. The CSFSelectWinners component determines whether to serve a paid ad or a house ad based on the maximum Need of Delivery for all paid ads not disqualified for a request. If the maximum Need of Delivery is greater than the threshold value, then the component serves a paid ad; otherwise it serves a house ad.

The threshold value is 0.95 by default and corresponds to all advertisements being at least 5 percent ahead of their goals before a house ad is served. You can configure this threshold using the property page of the CSFSelectWinners component. If you find, for example, that your ad campaigns are falling short of their goals but house ads are being mixed in during the ad runs, then you might want to lower the threshold score so that ads must be farther ahead of their goals before any house ads are mixed in.

After the CSFSelectWinners component determines a paid ad should be served, it selects the ad with the highest score. However, if a house is to be served, then the scores of all house ads are taken to be relative probabilities and the winner is selected randomly based on those probabilities. For example, if a house ad is to be served and there are three house ads with scores of 1.0, 2.0, and 3.0, then the ads will have selection probabilities of 17 percent (1/6), 33 percent (2/6), and 50 percent (3/6) respectively.

Note that if there are no eligible house ads and no eligible paid ads with a Need of Delivery above the specified threshold, then paid ads with Needs of Delivery less than the threshold will be eligible for selection.

Ad selection also takes into account a PageHistory string. The PageHistory string is a comma-delimited list of the ad IDs of those ads that were already selected on the page. This string is used to prevent the same ad from being selected multiple times on the same page when more than one call to the GetContent method is made on that page. The PageHistory string is also used to avert industry collision, which is defined as ads from different advertisers who are in the same industry appearing on the same page. (To prevent this, you specify a tag describing an ad's industry at the time you create the ad.)

Troubleshooting Ad Scoring and Selection

The file TraceScores.asp in the path SDK\Samples\Marketing\Debug in the Commerce Server 2000 SDK, contains a routine that, when used together with trace mode enabled (CSO.Trace = True), produces trace information showing the final score for each ad along with all of the score modifications made to each ad. This information, together with an understanding of how the SelectWinners component chooses ads to serve, is useful in troubleshooting and debugging ad selection problems on your site.

For more information about the TraceScoresasp file, see "Ads or discounts do not appear on the Web site" in the "Troubleshooting Commerce Server" section of Commerce Server 2000 Help.