Extending the Commerce Foundation Order Translator

  • Article

The Order Translator allows the objects being passed from the Commerce Server Core Services order system to Commerce Server 2009 to be properly translated to Commerce Server 2009 objects and vice versa. If the Commerce Server Core Services objects have been extended by a developer, the Order Translator needs to be extended to be properly handled by Commerce Server 2009. 

Architecture

The Order Translator works with any Commerce Server order object (default schema or an extended schema) and implements a base class that converts the Commerce Server order object to a Microsoft Multi-Channel Commerce Foundation Commerce Entity. For extended Commerce Server order schemas, extensions to the Microsoft Multi-Channel Commerce Foundation object allow these schema extensions to be passed properly to Commerce Server 2009. The object property translation is done through the Commerce Server 2009 metadata store instead of being hard coded to allow this extensibility to function properly.

The design of the Order Translator implements the base class, which can be overridden with custom order types, created in Commerce Server. The procedure for adding an extension to the Commerce Server orders schema and handling that extension properly in Commerce Server 2009 is:

  1. Extend the Commerce Server 2009 Order Translator class to use the custom Order type

  2. Update the Commerce Server 2009 configuration file to specify the custom Order translator

  3. Issue the appropriate Microsoft Multi-Channel Commerce Foundation API call to get an Order from Commerce Server

  4. The Order is retrieved from Commerce Server through an API call

  5. The customized order translator is called to do the translation

  6. The customized Order translator queries the Commerce Server 2009 metadata system for the strongly-typed Commerce Server Order classes

  7. The customized Order translator converts the Commerce Server Order objects to the corresponding Commerce Server 2009 objects

  8. Modify the <orders> section of the web.config file to list your custom types for the Commerce Server Order system. For example, if you defined a new LineItem class, then change the tag:

    <Type Key="LineItem" UserTypeName="LineItem" AssemblyType="GAC" NameSpace="Microsoft.CommerceServer.Runtime.Orders" Assembly="Microsoft.CommerceServer.Runtime, Version=6.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>

to:

        <Type Key="LineItem" UserTypeName="MyLineItem" AssemblyType="Local" NameSpace="MyCompany.ExtendedOrderClasses” Assembly=" MyCompany.ExtendedOrderClasses, Version=6.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>

OrdersMetadataProvider Class

Namespace Microsoft.Commerce.Providers.Metadata; assembly Microsoft.Commerce.Providers

This class contains the Boolean property PropertyDefinition.IsStronglyTyped which is set True for the strongly typed properties in the Commerce Server Order system types. This eliminates the need to provide this information through the Commerce Server 2009 metadata repository. If a custom extension if provided to the Commerce Server Order system, the OrdersMetadataProvider class automatically flows the updated Order system metadata (including the information on the strongly typed properties) to the Microsoft Multi-Channel Commerce Foundation API. Developers still have to override the corresponding translator methods that set or retrieve the values of the strongly typed properties for the custom Order types.

OrderTranslatorBase Class

Namespace Microsoft.Commerce.Providers.Translators; assembly Microsoft.Commerce.Providers

This class provides the following virtual methods designed to be overridden in the derived classes that handle translation for specific Commerce Server entities like LineItem and ShippingMethod:

  • TranslateToStronglyTypedCommerceServerProperty

  • TranslateToWeaklyTypedCommerceServerProperty

  • TranslateFromStronglyTypedCommerceServerProperty

  • TranslateFromWeaklyTypedCommerceServerProperty

The methods TranslateToStronglyTypedCommerceServerProperty and TranslateFromStronglyTypedCommerceServerProperty should be overridden in every specific derived class (because they handle each strongly typed property specific to that class) while the other two methods will rarely need overriding since their implementation handles weakly typed properties in a generic way for all translations.

The OrderTranslatorBase class retrieves the metadata information for the corresponding Commerce Server Entity and verifies which properties need to be translated. This class directs the property translation to the virtual methods that handle either strongly typed or weakly typed properties (the Commerce Server 2009 metadata specifies if the property is strongly typed or weakly typed). Strongly typed properties are defined by the Commerce Server system itself unless that information is overridden in the Commerce Server 2009 Metadata Repository. The weakly typed properties must be specified in the Metadata Repository, as in the following example:

<CommerceEntity name="LineItem">

<EntityMappings>

<!-- EntityMappings not shown for brevity -->

</EntityMappings>

<Properties>

<!--Weakly typed properties-->

<Property name="ItemPriority" dataType="Integer" isStronglyTyped="false" />

<Property name="GiftMessage" dataType="String" isStronglyTyped="false" />

<Property name="GiftWrap" dataType="Boolean" isStronglyTyped="false" />

</Properties>

</CommerceEntity>

Setting the property isStronglyTyped to false is optional (since this is its default value). Weakly typed properties must be listed specifically; otherwise they will not be translated.

The following classes reside in the namespace Microsoft.Commerce.Providers.Translators and assembly Microsoft.Commerce.Providers and are derived from OrderTranslatorBase:

  • LineItemTranslator

  • OrderAddressTranslator

  • OrderTranslator

  • DiscountTranslator

  • PaymentAccountTranslator

  • PaymentMethodTranslator

  • PaymentTranslator

  • PromoCodeTranslator

  • ShipmentTranslator

  • ShippingMethodTranslator

These classes override the following methods as needed:

  • TranslateToStronglyTypedCommerceServerProperty

  • TranslateToWeaklyTypedCommerceServerProperty

  • TranslateFromStronglyTypedCommerceServerProperty