Mappings and Advanced Configuration

The purpose of this chapter is to document the built-in mappings as well as the steps for adding custom mappings from Magento to OrderFlow.

Built-In Mappings

The purpose of the OrderFlow Magento extension mappings is to identify specific values of properties within the Magento environment and map them to their equivalents in Orderflow. The next sections describe the key built-in mappings that exist in the Magento Orderflow module.

Product Export

The list below are mappings identified from the OrderFlow Magento module class SixBySix_RealTimeDespatch_Model_Catalog_Product, found in the file app/code/community/SixBySix/RealTimeDespatch/Model/Catalog/Product.php, or in the built-in Magento class Mage_Catalog_Model_Product.

Also included is the Magento API expression, which gives an indication of the code used in the Magento API to extract the field name specified.

Orderflow Field Name	Magento API expression	Description
category	getCategory()->getName()	Product category.
currency	Mage::app()->getStore()->getCurrentCurrencyCode()	Returns the product's current currency code.
externalReference	getSku()	Retrieves ku throught ype instance.
description	getName()	Product description.
imageReference	getSmallImageUrl()	Product image URL,for displaying product images.
magentoType	getTypeId()	Product type identifier.
sellable	isSalable()	Whether the product is available for sale.
priceGross	Mage::helper('tax')->getPrice($this,$this->getFinalPrice(),true)	Returns the gross product price, including tax.
priceNet	Mage::helper('tax')->getPrice($this,$this->getFinalPrice())	Returns the net product price, excluding tax.
tax	getGrossPrice()-getNetPrice()	The tax on the product.
weight	getWeight()	Retrieve weight throught type instance.

The following built-in mappings are based on named product attributes attributes.

Orderflow Field Name	Description
barcode	The barcode for the product.
length
width
height
area
volume
weightUnits	Optional weight units for the product weight. Normally either 'gram' or 'kilogram'.
taxCode	The tax code for the product.

Order Export

The built-in order import mappings include mappings to order, shipment and order line entities in OrderFlow, and are based on the following entry in app/code/community/SixBySix/RealTimeDespatch/etc/config.xml.

As with the product mappings, the order mappings are based on the extension class SixBySix_RealTimeDespatch_Model_Sales_Order, found in app/code/community/SixBySix/RealTimeDespatch/Model/Sales/Order.php, which in turns extends Mage_Sales_Model_Order.

<order>
   <IncrementId>externalReference</IncrementId>
   <OrderCurrencyCode>currency</OrderCurrencyCode>
   <OrderCurrencyUnits>currencyUnits</OrderCurrencyUnits>
   <CustomerNote>customerComment</CustomerNote>
   <CouponCode>promotionCode</CouponCode>
   <DiscountDescription>promotionDescription</DiscountDescription>
   <Subtotal>goodsPriceNet</Subtotal>
   <SubtotalInclTax>goodsPriceGross</SubtotalInclTax>
   <GoodsTaxAmount>goodsTax</GoodsTaxAmount>
   <GoodsTaxCode>goodsTaxCode</GoodsTaxCode>
   <ShippingAmount>shippingPriceNet</ShippingAmount>
   <ShippingInclTax>shippingPriceGross</ShippingInclTax>
   <ShippingTaxAmount>shippingTax</ShippingTaxAmount>
   <ShippingTaxCode>shippingTaxCode</ShippingTaxCode>
   <PaymentMethodTitle>paymentGatewayIdentifier</PaymentMethodTitle>
   <NetTotal>totalPriceNet</NetTotal>
   <GrandTotal>totalPriceGross</GrandTotal>
   <TaxAmount>totalTax</TaxAmount>
   <TotalTaxCode>taxCode</TotalTaxCode>
</order>
<order_shipment>
   <CustomerNote>deliveryInstruction</CustomerNote>
   <ShippingMethod>deliverySuggestionCode</ShippingMethod>
   <ShippingDescription>deliverySuggestionName</ShippingDescription>
</order_shipment>
<delivery_address>
   <Street1>addressLine1</Street1>
   <Street2>addressLine2</Street2>
   <Street3>addressLine3</Street3>
   <Street4>addressLine4</Street4>
   <City>addressLine5</City>
   <Region>addressLine6</Region>
   <Postcode>postCode</Postcode>
   <Company>companyName</Company>
   <Name>contactName</Name>
   <CountryId>countryCode</CountryId>
   <Telephone>dayPhoneNumber</Telephone>
   <Email>emailAddress</Email>
   <EveningTelephone>eveningPhoneNumber</EveningTelephone>
   <Fax>fax</Fax>
   <MobileTelephone>mobilePhoneNumber</MobileTelephone>
</delivery_address>
<billing_address>
   <Street1>addressLine1</Street1>
   <Street2>addressLine2</Street2>
   <Street3>addressLine3</Street3>
   <Street4>addressLine4</Street4>
   <City>addressLine5</City>
   <Region>addressLine6</Region>
   <Postcode>postCode</Postcode>
   <Company>companyName</Company>
   <Name>contactName</Name>
   <CountryId>countryCode</CountryId>
   <Telephone>dayPhoneNumber</Telephone>
   <Email>emailAddress</Email>
   <EveningTelephone>eveningPhoneNumber</EveningTelephone>
   <Fax>fax</Fax>
   <MobileTelephone>mobilePhoneNumber</MobileTelephone>
</billing_address>
<order_item>
   <Name>description</Name>
   <QtyOrdered>quantity</QtyOrdered>
   <RowTotal>totalPriceNet</RowTotal>
   <TaxAmount>totalTax</TaxAmount>
   <RowTotalInclTax>totalPriceGross</RowTotalInclTax>
   <TotalTaxCode>totalTaxCode</TotalTaxCode>
   <Price>unitPriceNet</Price>
   <UnitTaxAmount>unitTax</UnitTaxAmount>
   <PriceInclTax>unitPriceGross</PriceInclTax>
   <TaxCode>unitTaxCode</TaxCode>
</order_item>

Custom Mappings Setup

The following section describes how to add custom order and product mappings to the Magento environment.

In line with Magento best practices, the technique involves the following elements:

define a custom module, which overrides the OrderFlow extension module
create a configuration, defining any custom mappings
provided overridden model classes if necessary for the custom mappings

An example of a custom mapping module may have the following structure:

Custom module

Note that we use a new module to apply mapping changes, as this minimises the likelihood of conflicts, and allows in most cases for future upgrades to the OrderFlow Magento extension without requiring additional changes to apply the custom mappings.

Custom Module Definition

An example custom mapping module definition is shown below.

<?xml version="1.0"?>
<config>
    <modules>
        <SixBySix_CustomValue>
            <active>true</active>
            <codePool>local</codePool>
            <depends><SixBySix_RealTimeDespatch/></depends>
        </SixBySix_CustomValue>
    </modules>
</config>

In the example above, the custom value module extends the SixBySix_RealTimeDespatch module, which is the OrderFlow extension module.

Mapping Configuration

Next, we need to create a configuration file for the module, found in this example in app/code/local/SixBySix/CustomValue/etc/config.xml.

<?xml version="1.0"?>
<config>
    <modules>
        <SixBySix_CustomValue>
            <version>0.0.0.1</version>
        </SixBySix_CustomValue>
    </modules>
    <global>
        <models>
            <customvalue>
                <class>SixBySix_CustomValue_Model</class>
            </customvalue>
            <catalog>
                <rewrite>
                    <product>SixBySix_CustomValue_Model_Catalog_Product</product>
                </rewrite>
            </catalog>
            <sales>
                <rewrite>
                    <order>SixBySix_CustomValue_Model_RealTimeDespatch_Sales_Order</order>
                </rewrite>
            </sales>
        </models>
    </global>
    <rtd_mappings>
        <product>
            <export>
                <CustomValue>customValue</CustomValue>
            </export>
        </product>
        <order>
            <CustomField>customOrderField</CustomField>
            <OrderCreateDate>createDateValue</OrderCreateDate>
        </order>
    </rtd_mappings>
</config>

Note in this example that we need to provide rewrite rules replace the order and product model classes with ones that apply our custom mappings. These are covered next.

Custom Mapping Classes

The custom mapping classes created need to extend the classes provided in the OrderFlow Magento extension.

Having added the custom mapping to the config.xml file, you will need to implement the methods that the methods to which the mapping applies.

This is shown clearly in the example product and order model classes below.

Product Model

<?php

/**
 * Custom Valued Product Model.
 */
class SixBySix_CustomValue_Model_Catalog_Product extends SixBySix_RealTimeDespatch_Model_Catalog_Product
{
    /**
     * Returns a custom value.
     *
     * This could be a call to a helper, service, additional business logic etc.
     *
     * @return string
     */
    public function getCustomValue()
    {
        return $this->getDescription();
    }
}

Order Model

class SixBySix_CustomValue_Model_RealTimeDespatch_Sales_Order extends SixBySix_RealTimeDespatch_Model_Sales_Order {

   /**
    * Returns a custom value.
    *
    * This could be a call to a helper, service, additional business logic etc.
    *
    * @return string
    */
   public function getCustomField()
   {
      return 'custom order field value';
   }


   /** Example to retrieve the order create date
    *
    * @return string
    */

   public function getOrderCreateDate()
   {
      return $this->getCreatedAtDate();
   }

}

Applying the Changes

You will then simply need to copy the files into the appropriate location in the Magento web root directory, then flush the Magento cache.