Commerce Foundation Metadata Repository Design

Article
01/18/2011

The following are the design goals for the Microsoft Multi-Channel Commerce Foundation Metadata Repository:

To provide a store to persist the metadata delta. This delta only contains what the Microsoft Multi-Channel Commerce Foundation adds to the Commerce Server definitions or what it overrides.
To provide metadata variations between different channels of the same Commerce Server site.
To provide type information for the Microsoft Multi-Channel Commerce Foundation Commerce Entities that would allow their dynamic instantiation.

Metadata Repositories and Commerce Entity Definitions

The simplest metadata repository would only contain a list of the commerce entities with their type and assembly information. This allows the factory methods in the Microsoft Multi-Channel Commerce Foundation to instantiate CommerceEntity objects through the reflection without creating dependencies on concrete types, which provides one of the Microsoft Multi-Channel Commerce Foundation extensibility features.

<MetadataDefinitions xmlns="urn:schemas-microsoft-commerce-server-multi-channel-metadata">
    <DefaultChannel>
        <CommerceEntities>
            <CommerceEntity name="Product"/>
            <CommerceEntity name="Basket"/>
        </CommerceEntities>
    </DefaultChannel>
</MetadataDefinitions>

Metadata Repositories and Entity Mapping

Though, in most cases the Microsoft Multi-Channel Commerce Foundation Metadata Repository will at least contain information that allows mapping the Microsoft Multi-Channel Commerce Foundation Commerce Entities to the corresponding Commerce Server Core Systems classes. The mapping between a Microsoft Multi-Channel Commerce Foundation Commerce Entity and a Commerce Server Core Systems class is defined within the <EntityMapping> element. This element must contain, at very least, the Commerce Server Core Systems class type information such as the fully qualified type name and the full .NET assembly name. Quite often the <EntityMapping> also includes the <PropertyMappings>, which defines how the Commerce Server properties are exposed in the Microsoft Multi-Channel Commerce Foundation Commerce Entities. The example shows that the Commerce Server's Product.ProductId will be exposed as Product.Id. Those Commerce Server properties that are not listed in the <PropertyMappings> element will simply "flow through" the Microsoft Multi-Channel Commerce Foundation Metadata and will be exposed through the Microsoft Multi-Channel Commerce Foundation Commerce Entities using their Commerce Server names. Generally, they are accessed in the Microsoft Multi-Channel Commerce Foundation through CommerceEntity.Properties collection using their names as keys. For example, CommerceEntity.Properties["Size"] will provide access to the Size property of the Product even though it is not defined in the <PropertyMappings> as long as it is defined in the Commerce Server Core Systems Product Catalog's schema.

<MetadataDefinitions xmlns="urn:schemas-microsoft-commerce-server-multi-channel-metadata">
    <DefaultChannel>
        <CommerceEntities>
            <CommerceEntity name="Product">
                <EntityMappings>
                    <EntityMapping
                        csType="Microsoft.CommerceServer.Catalog.Product"
                        csAssembly="Microsoft.CommerceServer.Catalog, Version=6.0.1.0, 
                        Culture=neutral, PublicKeyToken=31bf3856ad364e35">
                        <PropertyMappings>
                            <PropertyMapping property="Id" csProperty="ProductId" />
                            <PropertyMapping property="ListPrice"csProperty="cy_list_price" />
                        </PropertyMappings>
                    </EntityMapping>
                </EntityMappings>
            </CommerceEntity>
        </CommerceEntities>
    </DefaultChannel>
</MetadataDefinitions>

Metadata Repositories and Multi-Source Entity Mapping

In some cases, a single Microsoft Multi-Channel Commerce Foundation CommerceEntity can be mapped to more than one Commerce Server Core Systems class. For example, the Microsoft Multi-Channel Commerce Foundation Address can be either mapped to the Commerce Server Core Systems Profile Address or the Order Address. Such Commerce Entities will contain multiple <EntityMapping> elements in the repository, one for each corresponding Commerce Server Core Systems class.

<MetadataDefinitions xmlns="urn:schemas-microsoft-commerce-server-multi-channel-metadata">
    <DefaultChannel>
        <CommerceEntities>
            <CommerceEntity name="Address">
                <EntityMappings>
                    <EntityMapping
                        csType="Microsoft.CommerceServer.Runtime.Orders.OrderAddress"
                        csAssembly="Microsoft.CommerceServer.Runtime, Version=6.0.1.0, 
                        Culture=neutral, PublicKeyToken=31bf3856ad364e35"
                        csArea="Orders">
                        <PropertyMappings>
                            <PropertyMapping property="Id" csProperty="OrderAddressId"/>
                            <PropertyMapping property="DaytimePhone" csProperty="DaytimePhoneNumber" />
                        </PropertyMappings>
                    </EntityMapping>
                    <EntityMapping
                        csType="Microsoft.CommerceServer.Runtime.Profiles.Profile"
                        csAssembly="Microsoft.CommerceServer.Runtime, Version=6.0.1.0, 
Culture=neutral, PublicKeyToken=31bf3856ad364e35"
                        csDefinitionName="Address"
                        csArea="Profiles">
                        <PropertyMappings>
                            <PropertyMapping property="Id" csProperty="GeneralInfo.address_id" />
                            <PropertyMapping property="DaytimePhone" csProperty="GeneralInfo.daytime_phone" />
                        </PropertyMappings>
                    </EntityMapping>
                </EntityMappings>
            </CommerceEntity>
        </CommerceEntities>
    </DefaultChannel>
</MetadataDefinitions>

Note that when multiple <EntityMapping> elements exist they must contain the csArea attribute.

Metadata Repositories and Catalog Entities

The <EntityMapping> element can optionally have <DefinitionMappings> element, which is used to provide property mappings for specific Commerce Server definitions. As in the case with the regular <PropertyMapping>, the <DefinitionMappings> is only required when there is a need to change the property name or the name of the definition itself. Otherwise, all the Commerce Server definitions and their properties will "flow through" the Microsoft Multi-Channel Commerce Foundation Metadata object model having the names originally defined in the Commerce Server Core Systems Catalog Schema.

<DefinitionMappings>
    <!-- To override a definition name --> 
    <DefinitionMapping definitionName="Rock-Shoes" csDefinitionName="Rockshoes" />
    <DefinitionMapping csDefinitionName="Boots">
        <PropertyMappings>
            <!-- To override a property name for a given definition -->
            <PropertyMapping property="Sole" csProperty="SoleMaterial" />
        </PropertyMappings>
    </DefinitionMapping>
</DefinitionMappings>

Metadata Repositories and Property Definitions

Besides the CommerceEntity type information and the Commerce Server Core Systems mappings, the Microsoft Multi-Channel Commerce Foundation Metadata Repository can contain <Properties> element within the <CommerceEntity>. It provides property definitions that extend or override the Commerce Server Core Systems property metadata. For those properties that are not present in the repository, the Microsoft Multi-Channel Commerce Foundation will "flow through" the corresponding metadata provided in the Commerce Server Core Systems, but reflected through the Microsoft Multi-Channel Commerce Foundation Metadata object model. The common entries in the <Properties> element are <DisplayName>, <Description> and <Constraints>. Also, <DefaultValue>, <Format> and <EnumeratedValues> can be used. Please note that all Property metadata elements provide multilingual support for all the displayable messages.

<Properties>
    <Property name="Email" dataType="String" isMultilingual="false">
        <DisplayName value="E-mail">
            <LanguageSpecific value="French: E-mail" language="fr-CA"/>
        </DisplayName>
        <Description value="User's e-mail address">
            <LanguageSpecific value="French: User's e-mail address" language="fr-CA"/>
        </Description>
        <Constraints>
            <RequiredProperty>
                <Message value="E-mail address is required">
                    <LanguageSpecific 
                        value="French: E-mail address is required" 
                        language="fr-CA"/>
                </Message>
            </RequiredProperty>
            <RegularExpression 
                    pattern="^([a-zA-Z0-9_\-\.]+)@([a-zA-Z0-9_\-\.]+)\.([a-zA-Z]{2,5})$">
                    <Message value="E-mail address must follow the format ...">
                        <LanguageSpecific 
                            value="French: E-mail address must follow the format ..." 
                            language="fr-CA"/>
                    </Message>
            </RegularExpression>
        </Constraints>
    </Property>
<Properties>

Metadata Repositories and Relationship Definitions

Another important element that can be added to the <CommerceEntity> element in the Microsoft Multi-Channel Commerce Foundation Metadata Repository is <Relationships>. It contains definitions of the relationships for the current CommerceEntity. Each definition specifies the relationship type through the type attribute the related Commerce Entity type through the targetType attribute and the relationship multiplicity through the isMultipleItems attribute. Optionally, the relationship Display Name and Description can be provided.

It is important to realize that the <Relationships> element is required for all the commerce entities whose model defines the relationships. Relationships not defined in the Microsoft Multi-Channel Commerce Foundation Metadata Repository will not be present in the Microsoft Multi-Channel Commerce Foundation Metadata runtime objects since they are not "flown through" from the Commerce Server metadata. The reason for that is that relationships are not part of the metadata available through the Commerce Server Core Systems APIs for Catalog, Orders and Marketing systems. The Commerce Server Core Systems Profile relationships could have been translated into the Microsoft Multi-Channel Commerce Foundation relationship definitions, but for the consistency's sake we require all the Microsoft Multi-Channel Commerce Foundation Relationships to be defined in the Microsoft Multi-Channel Commerce Foundation Metadata Repository.

<Relationships>
    <Relationship name="Variants" type="Relationship" targetType="Variant" isMultipleItems="true" >
        <DisplayName value="Variants">
            <LanguageSpecific value="fr: Variants" language="fr-CA"/>
        </DisplayName>
        <Description value="Product Variants">
            <LanguageSpecific value="fr: Product Variants" language="fr-CA"/>
        </Description>
    </Relationship>
    <Relationship name="CrossSellProducts" type="CatalogRelationship" targetType="Product" isMultipleItems="true" >
        <DisplayName value="Cross-Sell Products">
            <LanguageSpecific value="fr: Cross-Sell Products" language="fr-CA"/>
        </DisplayName>
        <Description value="Cross-Sell Products">
            <LanguageSpecific value="fr: Cross-Sell Products" language="fr-CA"/>
        </Description>
    </Relationship>
</Relationships>

Metadata Repositories and Relationship Types

The relationship types referred to through the type attribute are defined within the <RelationshipTypes> section in the Microsoft Multi-Channel Commerce Foundation Metadata Repository. The RelationshipType is identified by its name and is mapped to a corresponding .NET class that defines this type. The RelationshipType may contain the <Properties> section similar to the one in the <CommerceEntity> element, which defines the metadata for the RelationshipType properties.

<RelationshipTypes>
    <RelationshipType name="Relationship" />
    <RelationshipType name="CatalogRelationship">
        <Properties>
            <Property name="Quantity" dataType="Integer" isMultilingual="false">
                <DisplayName value="Quantity">
                    <LanguageSpecific value="fr: Quantity" language="fr-CA"/>
                </DisplayName>
                <Description value="Number of the related items">
                    <LanguageSpecific value="fr: Number of the related items" language="fr-CA"/>
                </Description>
                <Constraints>
                    <Range minValue="1" minBoundaryType="Include" maxValue="100" maxBoundaryType="Include">
                        <Message value="Quantity must be within the defined range.">
                            <LanguageSpecific value="fr: Quantity must be within the defined range." language="fr-CA"/>
                        </Message>
                    </Range>
                </Constraints>
            </Property>
            <Property name="Enabled" dataType="Boolean" isMultilingual="false">
                <DisplayName value="Enabled">
                    <LanguageSpecific value="fr: Enabled" language="fr-CA"/>
                </DisplayName>
                <Description value="Is the relationship enabled?">
                    <LanguageSpecific value="fr: Is the relationship enabled?" language="fr-CA"/>
                </Description>
            </Property>
        </Properties>
    </RelationshipType>
</RelationshipTypes>

Metadata Repositories and Channels

The Microsoft Multi-Channel Commerce Foundation Metadata Repository allows for overriding metadata definitions for a specific channel in the <Channels> section of the repository. Metadata definitions in the <Channels> section override the definitions in the <DefaultChannel> in a similar way as the definitions in the <DefaultChannel> override the Commerce Server metadata. The following principles apply:

Metadata definitions can be added to any metadata collection (such as <EntityMappings>, <DefinitionMappings>, <Properties>, <Relationships>, <CommerceEntities>, <Constraints>, <PropertyMappings> and <EnumeratedValues>) in the <Channels> to extend or override the corresponding definitions from the <DefaultChannel> section.
Metadata definitions can be removed from the metadata collections in the <Channels> section using the <remove> element. Alternatively, a metadata collection can be cleared of all the definitions using the <clear> element. The <remove> and <clear> elements remove the definitions provided by the <DefaultChannel> section. If new definitions are provided in place of the removed ones they completely replace the definitions from the <DefaultChannel> section rather than extending or overriding them.