Product Catalog Programming Concepts

Article
11/12/2009

The CatalogManager object is the foundation of the Product Catalog System object model. You use the CatalogManager object to create and manage the ProductCatalog, Category, and Product objects in the system. The CatalogSets and CatalogToVendorAssociation objects are managed directly by application code rather than through the CatalogManager object.

The CatalogManager object instantiates one or more ProductCatalog objects. Each ProductCatalog object represents a catalog in the Product Catalog System. A catalog can consist of a flat list of products or it can have a hierarchy of categories in which to organize the products. Each Category object represents a node in this hierarchy and contains products or other categories.

The CatalogManager object also manages a collection of properties. These properties are used to define the attributes of the objects in the Product Catalog System. Appropriate properties must be created before the CatalogManager object can create any other objects.

The Commerce Server 2002 product catalog objects are described in the following topics:

CatalogManager Object
ProductCatalog Object
Product Object
Category Object
CatalogSets Object
CatalogToVendorAssociation Object
Category and Product Properties

CatalogManager Object

The CatalogManager object is the first object you create to use the Commerce Server 2002 Product Catalog System. Typically, a single CatalogManager object is created in the Global.asa file and used throughout an application. This object sets and retrieves properties that apply to all the catalogs in the Product Catalog System. You also use the CatalogManager object to create properties, define their attributes, and to create product and category definitions using those properties. See Category and Product Properties for more information about the properties in the Product Catalog System.

The CatalogManager object provides methods for queries and free text searches across single or multiple catalogs. The CatalogManager object provides methods for importing or exporting catalogs in comma-separated values (CSV) or XML formats.

The CatalogManager.CreateCatalog and CatalogManager.GetCatalog methods return a ProductCatalog object representing a specific catalog. The CatalogManager.Catalogs property is a recordset of all the catalogs in the Product Catalog System.

ProductCatalog Object

The ProductCatalog object represents a single catalog in the Product Catalog System. A catalog can be created either as a base catalog that contains products or as a virtual catalog that references products in one or more base catalogs. A virtual catalog can present products in a different hierarchy than the base catalog that it references. In Commerce Server 2002, virtual catalogs replace the custom catalogs available in Commerce Server 2000. Custom catalogs are not supported in Commerce Server 2002. All the methods for supporting custom catalogs exist in Commerce Server 2002, but they return an error. An upgrade from Commerce Server 2000 to Commerce Server 2002 converts all custom catalogs to virtual catalogs. Virtual catalogs are more flexible than custom catalogs.

You use the ProductCatalog object to add new products and categories to a catalog, either directly or through inclusion rules, to retrieve the products or categories in a catalog, or to perform a specification search of a catalog. All of the methods of the ProductCatalog object are run from the context of a specific catalog. Most methods apply equally to both base and virtual catalogs. Because a virtual catalog presents products that are contained in a base catalog, you cannot create a product from within a virtual catalog. A virtual catalog can contain new categories that are used to present included products or categories in a different hierarchy. Virtual catalog rules and price rules apply only to virtual catalogs and cannot be used within a base catalog. Virtual catalogs can also be used to support multicurrency applications.

A virtual catalog can present categories and products from several base catalogs. This is referred to as an aggregated catalog. Category names, product IDs, and variant IDs must be unique within a catalog. A virtual catalog handles these identifiers differently from a base catalog to avoid name conflicts. It does this by appending the name of the containing catalog to the identifier. For example, the product ID property in "BaseCatalog1" is "ProductNumber". When the base catalog is included in "VirtualCatalog2" the property name is changed to "ProductNumber(BaseCatalog1)" within the virtual catalog. When a new category is created in the same virtual catalog with "VirtualCategory" specified as the category name, the name is changed to "VirtualCategory(VirtualCatalog2)".

A virtual catalog acts exactly like a base catalog from the perspective of your application, but is quite different from the perspective of Commerce Server Business Desk. Likewise, the run-time API methods and properties act identically, but the design-time methods and properties are quite different. Some methods apply only to base catalogs, while others apply only to virtual catalogs. For example, you can create products only in a base catalog and you can add inclusion or exclusion rules only to a virtual catalog. Some properties, such as the PrimaryParent property, can be edited only in a base catalog.

Each time a virtual catalog rule or a price rule is changed, the virtual catalog is marked as dirty. Each time a change is made to a base catalog the catalog is marked as dirty. These changes will not affect the contents of a virtual catalog until it is rebuilt. The VirtualCatalogStatus catalog attribute stores the state of the catalog.

By default, virtual catalogs are created as views. This makes it easier and quicker to edit a virtual catalog, but can reduce the run-time performance in comparison to base catalogs. You can materialize a virtual catalog to improve the run-time performance. The tradeoff is that it takes much longer to rebuild that catalog after editing it. The materialize.vbs script can be used to set or reset a catalog attribute so that the catalog will be materialized when it is rebuilt.

You can use the CatalogManager.AddCatalogAttribute method to extend the ProductCatalog object with user-defined attributes. You could, for example, store information about the product vendor as one or more attributes of a catalog. This would eliminate the need for the CatalogToVendorAssociation object.

The ProductCatalog object supports multilingual catalogs. ProductCatalog objects have a multilingual DisplayName attribute. Each multilingual property in a multilingual catalog has a separate value for each language in the catalog. Any ProductCatalog object method that returns these properties returns them in the current language of the catalog. This maintains backward compatibility with existing application code. The current language is specified in the Language property of the ProductCatalog object. The ProductCatalog.Language property also specifies the language for all product/category objects that are obtained from this ProductCatalog object.

The ProductCatalog.RootCategories method returns a recordset of categories that is the starting point for traversing the category hierarchy. Similarly, the ProductCatalog.RootProducts method returns a recordset of products that are not in the category hierarchy.

Product Object

The Product object represents a single product or product family in the catalog. A product definition is created by using the CatalogManager object and can be used across the Product Catalog System, but a product is always stored in the context of a single base catalog. Use the Product object to perform operations on a product, such as modifying properties, creating product variants, or managing relationships.

Category Object

The Category object represents a single category in the catalog. Categories provide a method for organizing products within a catalog. Use this object to perform various operations on a category, such as adding products or other categories, or managing relationships. You can also use the Category object to perform a search that is scoped to the Category object. All categories have a multilingual DisplayName attribute. This attribute supports multilingual catalogs and allows different categories to appear to have the same name. See Code to Change How a Category is Displayed for details.

The Category.ChildCategories property is a recordset containing the names of categories that exist below this category in the hierarchy. The Category.Products property is a recordset containing all the products that exist directly in this category.

CatalogSets Object

The CatalogSets object stores and manages catalog sets, which are arbitrary collections of catalogs. Catalog sets allow you to present different collections of catalogs to different users and organizations.

CatalogToVendorAssociation Object

The CatalogToVendorAssociation object stores and manages associations between catalogs and vendors (suppliers).

Category and Product Properties

Properties are created and managed by the CatalogManager object. Property names must be unique across the Product Catalog System; however, the same property can be shared by any number of product or category definitions. Each property has a number of built in attributes, such as PropertyName and Datatype. You can extend properties by adding user-defined attributes.

Properties can be language neutral or multilingual. Language neutral properties have a single value; multilingual properties have a different value for each language supported in a catalog. Multilingual string, enumeration, and text properties can have a default value for each language in the Product Catalog System. All properties have a multilingual DisplayName attribute, even if they are language neutral. Monetary properties can have an attribute to specify their currency. All properties have an IsRequired attribute. If the IsRequired attribute is True, then Commerce Server Business Desk enforces requiring a value for the property.

The collation order and word breaker can be specified on a per-language basis. This is done by editing an XML file that is also used to configure Business Desk. See Language Configuration for details about the XML configuration file.