Microsoft Commerce Server 2000: Developer Notes

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

Cc936705.spacer(en-US,CS.10).gifCc936705.spacer(en-US,CS.10).gif

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 https://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:

Note These steps are also summarized in the Instructions.txt file, located in the path <installation location>\SDK\Samples\Management\BizDesk\Instructions.txt.

  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><U>O</U>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

The root node is named Catalog, and you must have a minimum of two catalogs for the Profiling System in any Commerce Server site:

  • 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.

Note The term profile schema represents the entire set of schemas for a site's Profiling System and does not denote the schema for an individual profile, such as user object, address, and organization, which represent the business entities of the site. Schemas for individual business entities are always called business object profile schemas.

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.

Note The Profiles Schema Mover tool does not migrate the business object profile data or the physical database tables and Lightweight Directory Access Protocol (LDAP) classes used to store the business object profile data. It simply automates the process of manually creating the profile schema (profile definitions, data sources, and data members) using Commerce Server Manager.

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

Note The type libraries provided by Commerce Server are automatically installed and registered on the server where Commerce Server is installed.

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.

Cc936705.f09csrk01(en-US,CS.10).gif 

Figure 9.1 Profiles Schema dialog box 

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).

Important The Profiles Schema Mover tool manipulates the site schema programmatically by using the Commerce.BusinessDataAdmin object (BDAO). The Commerce.BusinessDataAdmin object is provided in the Microsoft Commerce 2000 BizData Admin Type Library (BizDataManager.dll), but is currently not documented.

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.

Note The Commerce.BusinessDataAdmin object also exposes the method ExportCatalog to export the profile schema in XML format. This method works specifically with Site Packager to generate and package the profiles XML schema in a Site Packager file.

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 Schema Mover 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.

Cc936705.f09csrk02(en-US,CS.10).gif 

Figure 9.2 Import Profiles Schema dialog box 

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.

Cc936705.f09csrk03(en-US,CS.10).gif 

Figure 9.3 Migration across multiple Commerce Server environments 

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.

Cc936705.f09csrk04(en-US,CS.10).gif 

Figure 9.4 Migration within a single Commerce Server environment 

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

For example, you might type the following command: cscript "C:\SiteTerms.vbs" "Retail"

Profiling System: Operational Considerations

Cc936705.spacer(en-US,CS.10).gifCc936705.spacer(en-US,CS.10).gif

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.

Note After the join key property has been committed to the underlying stores, it can't be updated.

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.

Note After the profile object has been committed to the underlying stores, the hashing key property value can't be updated.

Important For partitioned ANSI SQL stores only, profile object retrieval operations based on a non-hashing key and the GetInfo method of the ProfileObject object could fail. However, this is not true for LDAP version 3-compliant stores.

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

Cc936705.f09csrk05(en-US,CS.10).gif

Figure 9.5 Profile definition keys 

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

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

int

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

Note For ANSI SQL stores, the Profiling System supports multi-values only for the string data type. For LDAP-v3 stores, the Profiling System supports multi-values for all data types, except longtext and image data types.

Other Considerations

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.

Cc936705.f09csrk06(en-US,CS.10).gif

Figure 9.6 IsTransacted custom attribute 

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.

Cc936705.f09csrk07(en-US,CS.10).gif

Figure 9.7 DefaultURL custom attribute 

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.

Cc936705.f09csrk08(en-US,CS.10).gif

Figure 9.8 Parent URL and default search scope 

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

Cc936705.spacer(en-US,CS.10).gifCc936705.spacer(en-US,CS.10).gif

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.

Note The information in this section applies to the default Advertising pipeline configuration and might not be applicable if you have reconfigured or replaced the standard components in the pipeline.

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.

Cc936705.spacer(en-US,CS.10).gif